Schema: Bill XML

Bills and resolutions can be found in directories such as data/us/112/bills.

File Naming Convention

Bill files are named as follows: data/us/CCC/rolls/TTTNNN.xml.

  • CCC signifies the Congress number. See the first column of data/us/sessions.tsv. It is a number from 1 to 112 (at the time of writing) without zero-padding.
  • TTT is the type of bill or resolution from the following codes: "h" (displayed "H.R." i.e. a House bill), "hr" (displayed "H.Res.", a House resolution), "hj" (displayed "H.J.Res." i.e. a House joint resolution), "hc" (displayed "H.Con.Res.", i.e. a House Concurrent Resolution), and similarly "s", "sr", "sj", and "sc" for Senate bills displayed as "S.", "S.Res.", "S.J.Res.", and "S.Con.Res." See this blog post for an explanation of the types.
  • NNN is the bill number, without zero-padding.

Example

Here is an example bill file, data/us/111/bills/h14.xml:

<bill session="111" type="h" number="14" 
     updated="2011-01-29T15:05:26-05:00"> 
	<state datetime="2009-01-06">REFERRED</state> 
 
	<introduced datetime="2009-01-06"/> 
	<titles> 
		<title type="short" as="introduced">Federal Ocean Acidification Research And Monitoring Act of 2009</title> 
		<title type="short" as="introduced">FOARAM Act</title> 
		<title type="official" as="introduced">To provide for ocean acidification research and monitoring, and for other purposes.</title> 
	</titles> 
	<sponsor id="400011"/> 
	<cosponsors> 
		<cosponsor id="400041" joined="2009-01-13"/> 
		...
	</cosponsors> 
	<actions> 
		<action datetime="2009-01-06"><text>Referred to the House Committee on Science and Technology.</text></action> 
		<action datetime="2009-01-06"><committee name="House Committee on Science and Technology"/><text>Referred to the Subcommittee on Energy and Environment.</text></action> 
	</actions> 
	<committees> 
		<committee code="HSSY" name="House Science and Technology" activity="Referral, In Committee" /> 
		<committee code="HSSY-20" name="House Science and Technology" subcommittee="Energy and Environment" activity="Referral" /> 
	</committees> 
	<subjects> 
		<term name="Environmental protection"/> 
		<term name="Air quality"/> 
		... 
	</subjects> 
</bill>

Schema

The format of the XML file is:

  • bill root element
    • attributes:
      • session: The session (i.e. Congress) that this bill is a part of (i.e. 110).
      • type: The type of the bill (h, hr, hc, etc., as above).
      • number: The number of the bill.
      • updated: The date the bill XML file was last updated, such as "2007-01-05T15:30:39-05:00".
    • state element: Contains a value indicating the current status of the bill. See below.
    • introduced element: datetime attribute gives the date the bill was introduced.
    • titles element:
      • title element, once for each title given to the bill. The element content has the text of the title. type attribute is "official", "short", or "popular", and as attribute is the status of the bill in which the title was assigned, such as "introduced". This is all as given by THOMAS.
      • The elements are in the order that they appear in THOMAS, which is chronological order, so the last element tells you the last as status available.
    • sponsor element: Most bills have sponsors, and in that case the id attribute is the GovTrack ID of the person sponsoring the bill. Otherwise, a none attribute is set to true if the bill has no sponsor, which has been the case for debt limit raising bills.
    • cosponsors:
      • cosponsor element: Once for each cosponsor. id attribute gives the ID of the cosponsor. (ID attribute is always present.)
    • actions:
      • These elements come in various forms. In all cases, the node (whatever it is), has a text subnode containing a description of the action. It may also have reference subnodes (siblings of the text node) that indicate references to pages in the Congressional Record, as given in THOMAS.
      • vote nodes represent votes on the passage of bills. The where attribute is h or s indicating where the vote took place. type is vote for the vote in the originating chamber, vote2 for the vote in the other chamber, override if the vote is on a veto override. result is pass or fail. how is a textual description of how the vote was conducted, or the string roll if it was a roll call vote, in which case the roll attribute gives the roll call number. suspension may be set to 1 and indicates that the vote was conducted under a suspension of the rules (i.e. On motion to suspend the rules and pass), which requires a 2/3 vote.
      • You will see other tag names on these elements. The names should no longer be relied on. In order to determine what status change was caused by a particular action, use the state attribute (think “finite state machine”), which is documented below.
    • committees:
      • committee element: Once per committee or subcommittee assignment. name attribute gives the name of the main committee. subcommittee attribute is "" for main committee assignments, otherwise the name of the subcommittee. activity attribute give some additional information that I do not understand.
    • relatedbills:
      • bill element: One per related bill or resolution.
        • attributes:
          • relation attribute (rule, unknown, ?).
          • session attribute gives the session for the related item (i.e. 111).
          • type attribute gives the type of the related item (see Bill Type Codes above).
          • number attribute gives the number of the related item (the number of the bill.)
    • subjects:
      • term element: name attribute defines a subject that might be used as a search or categorization term.

Bill Status

The status of the bill is given in a "state" element (think "finite state machine"). That element indicates the current bill status. "state" attributes are also present on action elements when the action resulted in a major status change for the bill.

The value of the state element and attributes are as follows:

  • INTRODUCED. The bill or resolution was introduced but not yet referred to committee.
  • REFERRED. The bill or resolution has been referred to committee in the originating chamber and needs committee action to continue.
  • REPORTED. The bill or resolution was reported by committee in the originating chamber and can now continue with floor debate in the originating chamber.
  • PASS_OVER:. These are a family of status codes indicating the bill or joint or concurrent resolution has passed favorably in its originating chamber and now goes on to the other chamber. If it failed, the status would be the corresponding FAIL:ORIGINATING:.
    • PASS_OVER:HOUSE. The bill or resolution passed the House (Senate next).
    • PASS_OVER:SENATE. The bill or resolution passed the Senate (House next).
  • PASSED:. These are a family of status codes indicating the bill has passed favorably out of Congress. It is a final status code for resolutions but not for bills. If the vote that PASSED it had gone the other way, the status would be the corresponding FAIL:ORIGINATING: for PASSED:SIMPLERES or FAIL:SECOND: for the others.
    • PASSED:SIMPLERES. A simple resolution has been passed in its originating chamber. This is the end of the life for a simple resolution.
    • PASSED:CONSTAMEND. A joint resolution which is proposing an amendment to the Constitution has passed both chambers. This is the end of the life for the resolution in the legislative branch. It goes on subsequently to the states.
    • PASSED:CONCURRENTRES. A concurrent resolution has been passed by both chambers. This is the end of the life for concurrent resolutions.
    • PASSED:BILL. A bill or a joint resolution not proposing an amendment to the constitution has been passed by both chambers. It may require a conference committee first, but will eventually go on to the President.
  • PASS_BACK:. These are a family of status codes that occur when a bill is passed in both chambers, but the second chamber made changes that the first chamber now has to agree to. The bill goes to conference or "ping pong" ensues where the chambers go back and forth between passing the bill until no one makes any more changes. When that finishes, the bill goes into the state PASSED:BILL.
    • PASS_BACK:HOUSE. The House voted on a Senate bill, making changes and sending it back to the Senate.
    • PASS_BACK:SENATE. The Senate voted on a House bill, making changes and sending it back to the House.
  • PROV_KILL:. These are a family of status codes indicating the bill or resolution is provisionally killed, meaning Congress took some action that would often mean the end of life for it (often enough to warrant a status code) but that it could still recover.
    • PROV_KILL:SUSPENSIONFAILED. The bill or resolution was brought up "under suspension of the rules" and failed that vote. It could be voted on again. If the vote had passed, the status would be one of PASSED, PASS_OVER, etc.
    • PROV_KILL:CLOTUREFAILED. A cloture vote was taken on the bill or resolution and the vote failed, meaning it was successfully filibustered. If the vote had succeeded, no status would be noted.
    • PROV_KILL:PINGPONGFAIL. After both chambers have passed a bill or joint/concurrent resolution, if the second chamber made a change the chambers have to resolve their differences. When the second chamber's changes go back to the first chamber for a vote, if the vote fails it's a provisional failure since I think they can try again.
    • PROV_KILL:VETO. The bill "PASSED:BILL" out of Congress but was vetoed by the President. A veto can be overridden. This status applies until an override attempt is made. If the bill was signed instead, the ENACTED status would follow (but not immediately). A pocket veto is indicated separately with VETOED:POCKET.
  • FAIL:. These are a family of status codes indicating the end of life of a bill or resolution. (Unlike PROVKILL, these are always final.)
    • FAIL:ORIGINATING:. This is a subgroup for when a bill or resolution fails in its originating chamber.
      • FAIL:ORIGINATING:HOUSE. The bill or resolution failed in its originating chamber, the House.
      • FAIL:ORIGINATING:SENATE. The bill or resolution failed in its originating chamber, the Senate.
    • FAIL:SECOND. This is a subgroup for when a bill or joint or concurrent resolution fails in the second chamber. It must have passed in the originating chamber to get this far.
      • FAIL:SECOND:HOUSE. The bill or resolution passed in the Senate but failed in the House.
      • FAIL:SECOND:SENATE. The bill or resolution passed in the House but failed in the Senate.
  • VETOED:OVERRIDE_PASS_OVER:. This is a family of status codes indicating a veto override attempt was successful in the originating chamber, and that it is now up to the second chamber to attempt the override. If the override failed, the status would be one of VETOED:OVERRIDE_FAIL_ORIGINATING:.
    • VETOED:OVERRIDE_PASS_OVER:HOUSE. The House (the originating chamber) succeeded at the veto override. It goes on to the Senate next.
    • VETOED:OVERRIDE_PASS_OVER:SENATE. The Senate (the originating chamber) succeeded at the veto override. It goes on to the House next.
  • VETOED:. These are a family of status codes indicating the end of life for a bill that has been vetoed. It is a final status code for a bill.
    • VETOED:POCKET. This status code is for bills that were pocket-vetoed, meaning the President does not sign the bill and Congress adjourns. The bill does not become law and Congress has no opportunity to override.
    • VETOED:OVERRIDE_FAIL_ORIGINATING:. This is a subgroup for bills who failed in the veto-override attempt of its originating chamber, which comes first.
      • VETOED:OVERRIDE_FAIL_ORIGINATING:HOUSE. Veto override failed in the House, the bill's originating chamber. It had not gotten to the Senate yet for an override.
      • VETOED:OVERRIDE_FAIL_ORIGINATING:SENATE. Veto override failed in the Senate, the bill's originating chamber. It had not gotten to the House yet for an override.
    • VETOED:OVERRIDE_FAIL_SECOND::. This is a subgroup for bills whose veto was successfully overridden in its originating chamber but failed in the veto-override attempt of the other chamber, which comes second. If the override had passed, the status would shortly be ENACTED:VETO_OVERRIDE.
      • VETOED:OVERRIDE_FAIL_SECOND:HOUSE. Veto override passed in the Senate (the originating chamber) but failed in the House.
      • VETOED:OVERRIDE_FAIL_SECOND:SENATE. Veto override passed in the House (the originating chamber) but failed in the Senate.
  • ENACTED:. These are a family of status codes for bills and joint resolutions not proposing an amendment to the constitution that have been enacted as law. It comes after a short delay between the signature or override and the administrative action to actually make the bill law.
    • ENACTED:SIGNED. The president signed the bill.
    • ENACTED:VETO_OVERRIDE. The bill was vetoed but the veto was overridden in both chambers.