Conceptual Data Model of Formal Legislative Processes in the U.S. Federal Government

Motivation

Goal is to have an:

• open, authoritative set of machine processable data covering formal actions of Congress and its members
• to enable (not create) a variety of uses for a variety of users:
  • for data processors (ontologies, codifications, correlations with other datasets)
  • for end users (apps, mashups, human-searchable websites, researchers, reporters)
  • for other government entities

Scope of the Specification

• a general statement of transparent data practices
• a conceptual model (descriptive and prescriptive) of desired data concerning the formal legislative process
• and not of specific publication or serialization technologies or methodologies

Transparent Data Practices

• availability
  • permanent
  • stable (always in same location)
  • complete
  • bulk accessible
  • incrementally accessible
  • open (publicly accessible and free of proprietary encumbrances)
• authority
  • authoritative (Authoritative sources will emerge from consistent practices.)
  • timely/real-time
  • correctable (in response to consumers of data)
• machine-discoverability
  • internet-accessible
  • cross-referenceable
• machine-processability
  • comprehensive conceptual data model
  • semantically rich
  • well-defined, published serializations

Conceptual Data Model

Metamodel

Entities

An Entity represents an object in the world. An Entity is composed of unordered named Properties and is uniquely identified by an Identifier.

An Entity’s Class defines what Properties and Identifiers compose a given Entity.

An Entity Class may be specified by other Entity Classes. Such Entity Classes are called Subclasses of the specified Entity Class. An Entity Subclass inherits the Properties and Identifiers of the Entity Class.

Properties

A Property consists of a Name and a Value. Names must be unique within an Entity. A Value must be an Entity, a Collection of Entities, or a typed literal.

A Property may be derived or computed, meaning that its value can be inferred from other Properties.

Identifiers

Identifiers uniquely identify an Entity. Identifiers are composed of the Values of one or more Properties which taken together are the minimum necessary to identify that Entity.

Identifiers should be natural where possible; if there is no natural Identifier for an Entity, a surrogate Identifier must be assigned and transmitted by an authority. Every Entity must have an Identifier.

Types

A Type describes a literal Value for a Property. Types may be simple (e.g., Integers, Strings, URIs, Currency Amounts, Dates, etc) or complex (XML documents, PDF documents, etc).

This specification does not define the textual representation for typed Values, but one should use representations which are standardized, machine-readable, and in conformance with the principles set forth in the Transparent Data Practices outlined in this document.

Collections

Collections are groups of Entities indicated together. Collections may be heterogeneous or homogeneous. Collections may have cardinality constraints.

Bag

A Bag is an unordered non-unique set of Entities. A single Entity may occur more than once within a Bag.

List

A List is an ordered non-unique set of Entities. A single Entity may occur more than once within a Bag. The sort order should be specified.

Set

A Set is an unordered unique set of Entities. An Entity may occur only once within a Set.

Ordered Set

An Ordered Set is an ordered unique set of Entities. The sort order should be specified.

Extending

This data model is not meant to be exhaustive. It may be extended by augmentation (adding additional properties to Entity Classes defined in this specification), or by subclassing (defining new Entity Classes inheriting from an existing Entity Class defined in this specification).

Abstract Entity Classes may not be augmented, only subclassed.

Any extensions must make use of a namespacing mechanism to prevent Property Name and Entity Class Name collisions with other extensions. No namespacing mechanism is defined by this specification—namespacing mechanisms are implementation-specific.

Metamodel Notation

The following notation is used to describe entities.

[«SuperClassName»] EntityClassName

Description of Entity Class.

• «Identifier» (PropertyName1, PropertyName2, …) this defines the property names which compose the Entity Class’ identifier
• PropertyName: PropertyValueType[cardinality constraints] {collection information and other notes}
• /DerivedPropertyName: PropertyValueType

Model (Entity Classes)

Static Entities

Static Entities are those which change infrequently.

Body

An abstract Entity Class representing an official body of people.

«Body» ConstitutionalBody

An abstract Entity Class representing the House or Senate. This Entity Class is unusual in that most of its properties are derived. In principle, the value of these properties may be derived by examining all open Terms of all FederalElectiveOfficeholders.

• date: date {all other properties of this Body are assertions which are true on the date indicated by this property}
• /congress: number
• /session: number

«ConstitutionalBody» HouseOfRepresentatives

The membership of the House of Representatives on a given date

• /speaker: FederalElectiveOfficeholder
• /majorityLeader: FederalElectiveOfficeholder
• /minorityLeader: FederalElectiveOfficeholder
• /majorityWhip: FederalElectiveOfficeholder
• /majorityWhip: FederalElectiveOfficeholder
• /members: FederalElectiveOfficeholders[1..n] {Set, includes all members of the House of Representatives for a given Congress}

«ConstitutionalBody» Senate

The membership of the Senate on a given date

• /senatePresident: FederalElectiveOfficeholder {always the Vice President}
• /presidentProTempore: FederalElectiveOfficeholder
• /majorityLeader: FederalElectiveOfficeholder
• /assistantMajorityLeader: FederalElectiveOfficeholder
• /minorityLeader: FederalElectiveOfficeholder
• /AssistantMinorityLeader: FederalElectiveOfficeholder
• /members: FederalElectiveOfficeholders[1..n] {Set, includes all members of the Senate for a given Congress}

«Body» AbstractCommittee

Abstract Entity Class shared by Committees and Subcommittees

• «Identifier» code: string
• house: constitutionalbody_enum {house, senate, or joint}
• name: string
• jurisdiction: string {describes committee’s purview}
• chairman: FederalElectiveOfficeholder[1,2] {Set, two chairmen reflects co-chairmanship}
• rankingMember: FederalElectiveOfficeholder[0,1] {leading member of the minority party, may be empty if committee has co-chairmanship}
• members: FederalElectiveOfficeholder[1..n] {Set, complete including chairman and rankingmember}

«AbstractCommittee» Committee

A Congressional Committee. Includes the Committee of the Whole.

• subcommittee: Subcommittee[0..n] {Set}

«AbstractCommittee» Subcommittee

A congressional subcommittee: must have only one parent Committee.

• «Identifier» code: string {full Identifier is (Committee code, SubCommittee code)}

Congress

A two-year meeting of the United States Congress composed of Sessions.

• «Identifier» number: integer
• start: date
• end: date
• sessions: Session[1..n] {OrderedSet}

Session

A meeting of a Congress. A Session must be part of one and only one Congress.

• «Identifier» number: integer {full identifier is (Congress number, Session number)}
• start: date
• end: date

Seat

Represents a Congressional Seat. This is an abstract class which exists solely to define Subclasses; there are no concrete Entities of this Class.

• state: usa_state

«Seat» HouseSeat

A Seat in the House of Representatives

• district: integer {0 for at-large}

«Seat» SenateSeat

A Seat in the Senate

• class: integer {senatorial class: 1, 2 or 3}

Term

Represents the time during which an official seat is held.

• start: date
• end: date
• office: House

«Term» CongressionalTerm

Represents a Congressional Term. A new Term beings when a person is sworn in.

• seat: Seat
• /congress: Congress {OrderedSet}

«Term» CongressionalOfficialTerm

Represents a Term of a Congressional office aside from Congressional Membership.

• office: congressionaloffice_enum

«Term» ExecutiveTerm

Represents a Term of an Executive office.

• office: executiveoffice_enum {president or vice president}

PartyAffiliation

Represents the time during which a person is a member of a party.

• start: date
• end: date
• party: party_enum

Person

Represents a Person. This is an abstract class which exists solely to define Subclasses; there are no concrete Entities of this Class.

• honorific: string {optional}
• firstName: string
• middleName: string {optional}
• lastName: string
• suffix: string {optional}

«Person» FederalElectiveOfficeholder

Represents a Person who holds an elective federal office. All federal elective officeholders should be identified by a single identifier system.

• terms: Term {Set}
• parties: PartyAffiliation {OrderedSet; ordered by start date}
• officialPortrait: image
• gender: gender_enum
• /currentTerm: Term
• /currentParty: {the current party affiliation of the officeholder}

«Person» Functionary

A person who is identified by title or purpose rather than by name. This is used for non-FederalElectiveOfficeholders who appear frequently in congressional proceedings but whose individial identies are not important. E.g.: a clerk or a chaplain.

• title: string

Substantive Entities

Substantive Entities are those which contain information on the deliberations of Congress.

Bill

A Bill in Congress that has not become law.

• «Identifier» (congress, type, number)
• congress: Congress
• type: bill_type
• number: integer
• text: billtext {must include machine-extractable title and bill body text information}
• sponsor: FederalElectiveOfficeholder
• isByRequest: Boolean {indicates introduction without a show of support for the bill}
• cosponsor: FederalElectiveOfficeholder[0..n] {OrderedSet, date of cosponsorship must be recoverable through the actionlog}
• actionlog: Action {List, only actions that concern this bill}
• /state {state of the bill; inferred from actionlog and bill state machine}
• /introduced: datetime {date on which bill was introduced; inferred from actionlog}
• /introducedSession: {session during which bill was introduced; inferred from actionlog or date introduced}

PublicLaw

A Bill which has passed into law.

• «Identifier» (congress, lawnumber)
• congress: Congress
• lawnumber: integer
• bill: Bill {The bill passed to create this law.}
• dateEnacted: date

Amendment

An amendment to a Bill or to another Amendment.

• «Identifier» (object {Bill}, number) {the identifying object must be a Bill; it is found by following the object property of an amendment entity through its parent entities until a Bill is found.}
• venue: Body {where the amendment was offered}
• adoptionDate: datetime {if it was adopted, the time at which the amendment was adopted}
• number: integer {a monotonically increasing number unique among all amendments for a given Bill}
• object: Bill, Amendment {the thing amended; must eventually terminate at a Bill}
• changes: amendmentchange {the changes themselves; should be machine-processable can be applied to the object by machine}
• /afterChange: billtext, amendmentchange {optional; the text of the Bill or Amendment after applying the change}
• /introduced: datetime {the time at which the amendment was introduced, inferred from the Motion that introduces it}

Meeting

A specific temporally and spatially delineated gathering of a Body. Includes House of Representative, Senate, Committee, and Subcommittee meetings.

• legislativeDay: integer {A meeting’s call to order and adjournment define the boundaries of a legislative day. Legislative days are numbered sequentially and numbering is reset at the beginning of a new Congress}
• start: datetime
• end: datetime
• location {physical location}
• title: string {optional: the official title of the meeting if one exists}
• purpose: text {optional}
• billSubject: Bill[0..n] {Set; bills discussed at a meeting}
• meetingBody: Body
• meetingType: meeting_type
• participants: Person[1..n] {Set}
• statements: LegislativeStatement {OrderedList, by time}
• records: Record {Set, transcripts of the meeting}
• materials: url {Set, reference to supplemental non-transcript documents used in the meeting}

LegislativeStatement

Something said to a Body convened in a Meeting.

• «Identifier» (meeting, time)
• time: datetime
• /meeting: Meeting {inferred}
• speaker: Person
• bill: Bill {optional, bill which is mentioned or indicated by the speaker}
• text: transcript {optional}
• officialText: transcript {optional}
• video: url {optional, reference to video files}
• /records: Record {Set, Records which include this statement, inferred from the meeting’s records property}

Record

A record of the entire content of a meeting released as a single document. Although not composed of LegislativeStatements, these should be derivable from the text, video, or audio. Must include at least one of the optional properties.

• source: text {who prepared the record}
• released: date
• text: Transcript {optional}
• video: video {optional}
• audio: audio {optional}

Report

A report submitted by a committee to a house of Congress

• number: integer {identifier assigned when report is filed}
• committee: AbstractCommittee {Committee or SubCommittee}
• text: string {the text of the report in a structured markup language}
• /contains: Vote, Bill, Amendment, Decision {Set; entities present in the report itself; should be inferred from the text}
• /about: Bill

Administrative Entities

Administrative Entities are those which affect the state of a Bill.

Motion

A formal proposition put before a Body which requires the consent of that Body to be approved. The thing approved depends on the nature of the Motion, but includes Amendments, passage of Bills, adjournments, etc. Motions are closely tied to Decisions.

• «Identifier» (meeting, time)
• time: datetime
• meeting: Meeting {the meeting in which the Motion was made}
• /before: Body {the Body to whom the proposition is addressed and from whom it requires a Decision; inferred from meeting’s Body}
• motionType: motion_type {optional; where the proposition is of a standard type outlined in the rule it is indicated here; otherwise the proposition text itself must suffice}
• proposition: string {the natural-language text of the motion}
• object: Bill, Amendment, Meeting {optional; where the proposition is about some object it is indicated here. The object should be evident from the proposition.}
• decisions: {OrderedSet; A motion may have several Decisions because members may object to a Decision. The last and only the last Decision in this set must be the deciding one and have an isDeciding property set to true}
• /isAdopted: Boolean {inferred from decisions property}

«Motion» Referral

The assignment of a bill to a committee for consideration. This is a Motion with a motionType of “to refer” and a Bill as its object.

• terms: referral_term {whether the bill is to be considered by all committees at once or one at a time}
• referredTo: Committee {List}

Decision

The expression of assent or dissent by a Body for or against a Motion.

• «Identifier» (motion, time)
• time: datetime
• motion: Motion {the motion being decided}
• /proposition: string {inferred from Motion}
• /object {inferred from Motion}
• objectionGrounds: text {optional; if there is an objection to the outcome of this Decision, the grounds for the objection is noted here}
• objector: FederalElectiveOfficeholder {optional; present if there is an objection}
• type: decision_type {the means of measuring assent by the Body as a whole, e.g. by roll call}
• rule: decision_rule {the type of assent required by a Body’s members, e.g. simple majority, lack of objection}
• result: decision_result {the final outcome of the decision}
• isDeciding: boolean {whether this Decision was the final and deciding one for the referenced Motion; if true, it must be the last Decision for a given Motion and it must have no value for the objector and objection properties}

«Decision» RollCall

A Decision resolved by voting.

• «Identifier» (congress, session, number) {congress and session are inferred from the motion}
• number: integer {the number assigned to this roll call}
• votes: Vote[1..n] {Set}

Vote

An individual vote

• voter: FederalElectiveOfficeHolder
• vote: vote_cast

Communication

A formal message or communication between houses of Congress or the president and Congress

• «Identifier» (congress, house, number) {Congress and House are inferred from the Meeting indicated by the introducedAt property}
• number: int {a monotonically-increasing number uniquely identifying the communication; resets at the beginning of each Congress}
• from: Body
• to: Body
• introducedAt: Meeting
• text: communication {content of the communication with machine-processable markup}
• summary: communication {summarized content of the communication as shown in the House or Senate Journal}
• /about: Bill {Set, optional; derived from text property. If the communication references one or more bills, these should be accessible through this property}

Actions/Events

Relationship to Entity Classes

Actions are an event-based, incremental view of congressional activities. Every Action should contain enough information to fully specify either a new entity or a set of modifications to an existing entity, or both.

The entity an action modifies is called the object of that action.

An ordered list of actions with an identical object is called a actionlog. Actionlogs should be available for entities retrieved through bulk access. E.g. A Bill Entity should have some way to list all actions which affected it.

Action Entity Class

Action

• «Identifier» (meeting, timestamp)
• timestamp: datetime
• meeting: Meeting
• type: action_type
• object: Entity {Set}

Action Types

Below are the defined action types and the Entity they create or modify

• CallToOrder: Meeting, Session, Congress
• Adjourn: sets end date on Meeting, Session, or Congress
• SwearIn: Term {refers to a Person indirectly}
• Establish: Committee, Subcommittee
• Introduce: Bill
• Refer: Referral, Bill
• Report: Bill
• Cosponsor: Bill
• Remove-Cosponsor: Bill
• Amend: Bill, Amendment
• Say: Statement, Transcript
• Decide: Decision {refers to Bill, PublicLaw, or Amendment indirectly}
• Present: Report, Communication
• Pass: Bill
• Veto: Bill

State Machines

In principle the set of allowed action types and entity modifications at any point in a sequence of actions is constrained by the state of those entities. Some actions advance the state of entities in such a way that other actions upon those entities are no longer possible and new actions are possible. (For example, a Meeting that has been called to order may not be called to order again.)

The rules that govern the transitions between states are called state machines. Because of the complexity of the formal legislative process and because the details of this process may change over time, this specification does not rigorously define a set of state machines governing entity states.

Bill States

However, the value of the Bill state property is governed by a state machine because the state of a Bill is important to know and difficult to discover algorithmically.

Below is a description of the defined bill state values and their types.

introduced

Last action was a successful motion to Introduce.

referred

Last action was a successful motion to Refer.

reported

Last action was a Report by committee.

pass.house

Last action was a Pass by the House for a bill originating in the House which requires both chambers to be enacted. The bill must go to the senate.

pass.senate

Last action was a Pass by the Senate for a bill originating in the Senate which requires both chambers to be enacted. The bill must go to the house.

pass_back.house

Last action was a Pass by the House for a bill originating in the Senate which requires both chambers to be enacted, but the bill contains motifications to which the Senate must agree. Motifications are noted by successful Amend actions since the Pass action in the House.

pass_back.senate

Last action was a Pass by the Senate for a bill originating in the House which requires both chambers to be enacted, but the bill contains motifications to which the House must agree. Motifications are noted by successful Amend actions since the Pass action in the Senate.

passed

Last action was a Pass by any chamber which was sufficient for the bill to achieve final passage.

• For simple resolutions, the bill passed in the originating chamber. This is the final state for a simple resolution.
• For concurrent resolutions, the bill passed identically in both chambers. This is the final state for concurrent resolutions.
• For constitutional amendments, the bill passed identically in both chambers, but must still be ratified bt the states.
• For all other bill types, the bill passed identically in both chambers and must be presented to the President to be signed or vetoed.

vetoed

The last action was that the President vetoed a passed bill. The veto may still be overridden.

veto_override.house

The last action was that the House overrode a presidential veto, but the Senate has not.

veto_override.senate

The last action was that the Senate overrode a presidential veto, but the House has not.

enacted

The bill has become a public law or constitutional amendment either by presidential signature, veto override by both houses, or state ratification. This is a final state.

Types (property-level specifications)

The exact representation of the types below will depend on the concrete data model that implements this abstract model. Use existing standards where possible and aim for unambiguous machine-readablility.

markuptype

An abstract type. A markuptype is a document with inline machine-processable markup (e.g. XML) from which it is easy to extract contained or related Entities and other semantic information.

Special considerations:

• References to U.S. Public Laws or Codes and Statues should include an explicit machine-readable reference to the prior law affected.
• Agencies and Programs should be referenced by a standard numbering scheme, such as MAX codes or contractor codes, which are unambiguous over time.
• Where a person is mentioned, this fact should be indicated inline with a machine-readable proper name even if a unique identifier of the person is not available.
• Where a location is mentioned, this fact should be indicated inline with a machine-readable name even if a unique identifier of the location is not available.
• Where a government or agency is mentioned, this fact should be indicated inline with a machine-readable name even if a unique idenfier of the government is not available. At the very least, federal agencies and U.S. State governments should have unique identifiers.

billtext (markuptype)

The text of a bill. Titles, agencies or programs affected, U.S. Code sections affected, authorizations or appropriations of funds and their amounts, locations, people, foreign and state governments and agencies, internal section numbers, the version of the text itself, the status, and the date should be easily extractable from a billtext document.

Special considerations:

• Where Authorizations and Appropriations appear in the text of a bill, the following should be noted inline: the fact that a passage’s language is authorizing or appropriating, what the mandate or agency or program is which is being authorized or appropriated, and any applical dollar amounts attached to the authorization or appropriation

amendmentchange (markuptype)

The text of an amendment. Should be an unambiguous machine-processable description of the changes that have been proposed for another markuptype (billtext or amendmentchange) to produce the desired new document.

committeereport (markuptype)

The text of a committee report. If any other entities are expressed in the markup (e.g. Decisions, Statements, Bills), these should be expressed in a way rich enough to allow one to derive the corresponding Entity.

Where applicable, a committeereport should include: statements, minority statements, statement of authorizing clause of the Constitution, any special statements required by House or Senate rules (indicating rule number), bill texts, section-by-section summaries of bills, proposed amendments, and committee voting records.

transcript (markuptype)

The record of human speech or action. One should be able to identify every Person Entity speaking and the time of each utterance so that one may derive LegislativeStatement Entities. If any other entities are expressed in the markup (e.g. Reports, Decisions, Statements), these should be expressed in a way rich enough to allow one to derive the corresponding Entity. This markup type should be appropriate for any temporally-arranged, mixed-content documents, such as the Congressional Record.

Special considerations:

• Support documents, such as presentation files or testimony documents, should be referenced.
• Gaps in the transcript which are caused by breaks or adjournments should be indicated.
• The entrance or exit of People into the Meeting should be indicated.

communication (markuptype)

The text of a communication to a house of Congress from the other house of Congress or from the executive. One should be able to identify mentioned people, bills, public laws, U.S. Code sections, dockets, and regulations (RIN).

constitutionalbody_enum

• House of Representatives
• Senate
• Joint (used by some committees)
• Conference (used by conference committees)
• Presidency (used by a President)
• Vice Presidency (used by the Vice President)

congressionaloffice_enum

• House of Representatives
  • speaker
  • majorityLeader
  • minorityLeader
  • majorityWhip
  • majorityWhip
• Senate
  • senatePresident {always the Vice President}
  • presidentProTempore
  • majorityLeader
  • assistantMajorityLeader
  • minorityLeader
  • AssistantMinorityLeader

executiveoffice_enum

• president
• vicePresident

party_enum

• democrat
• independent
• republican

meeting_type

• Meeting
  • Hearing
  • Markup
• Debate

bill_type

• h (House of Representatives Bill)
• hr (House Simple Resolution)
• hj (House Joint Resolution)
• hc (House Concurrent Resolution)
• s (Senate Bill)
• sr (Senate Simple Resolution)
• sj (Senate Joint Resolution)
• sc (Senate Concurrent Resolution)

vote_cast

• yes
• no
• conflict of interest {Senate only, Rule XII}
• not voting
• present {for quorum calls}

motion_types

• to adjourn
• for the previous question
• to postpone to a day certain
• to amend
• to postpone indefinitely
• to establish quorum
• to proceed with debate {cloture}
• to pass
• to reconsider
• to rise
• to refer {includes “to commit” and “to recommit”}
• to concur {committee motion}
• to disagree {committee motion}
• to close debate {committee motion}
• to subpoena {hearing motion}
• to close the meeting {hearing motion}
• to establish an investigative subcommittee {hearing motion}
• to call witnesses selected by the minority {hearing motion, Rule XI 2.(j)(1)}

decision_type

• voice vote
• roll call
• unanimous consent

decision_rule

• simple majority
• 2/3rd majority
• 3/5ths majority
• lack of objection

decision_result

• Passed
• Agreed
• Confirmed
• Failed
• Defeated
• Rejected
• Not Sustained
• Passed contrary to rule

referral_term

• single
• joint
• sequential

Special Considerations

Bill Versions

A bill version is the official text of a bill at a given time. The passing of an amendment to a bill creates a new version of a bill.

There are two ways to identify a bill version given the text of the bill as introduced and a full set of adopted amendments to the bill and of adopted amendments to adopted amendments of the bill.

The first way is by date and time. Given a date and time, one must be able to apply all adopted amendments to a bill text or to adopted amendment texts in order of their adoptionDate up to the desired date and time. The result of these transformations should be the official text of the bill.

The second way is by amendment number. A bill’s version may be identified by the amendment number of an amendment which has that bill as its object. Given the amendment identified by this amendment number, one must be able to apply all adopted amendments to a bill text or to adopted amendment texts in order of their adoptionDate up to and including the amendment indicated. The result of these transformations should be the official text of the bill at the moment the indicated amendment was adopted.

All amendments must express their changes as against the official version of the bill at the time of amendment adoption. Amendments must be applied sequentially in order of adoption, and may not be applied concurrently to the same version of a bill.

Only adopted amendments are considered for bill versioning. This specification does not define identifiable bill versions for amendments that have not been adopted. Thus this specification defines no mechanism for identifying proposed or unrealized versions of bills.