OCDEP 7: Votes¶
- Created:
2014-06-18
- Author:
James Turk
- Status:
Accepted
Overview¶
Definition of the Open Civic Data vote types.
(Based in part on Popolo types for the Open Civic Data Vote and VoteEvent).
Rationale¶
Determining how legislators have voted on specific proposals is a vital component to creating
legislative accountability. The VoteEvent
type and its related subtypes exist to enable the recording
of votes (meaning the outcome of a proposal as well as the individual positions of legislators).
An attempt has been made to reconcile our vote types (originally based in Open States work) with the schemas put forward by the Popolo specification.
Implementation¶
Because at the time of writing (June 2014) the Popolo vote specification was still somewhat in a state of flux we’ve included pieces of the specification here for consistency.
VoteEvent¶
Because the term ‘vote’ can mean multiple things, Popolo makes use of the term VoteEvent
to describe
the actual event of a legislative vote taking place and the term Vote
for a legislator’s vote
in a given VoteEvent
. We generally use that terminology here, with the exception that the recommended API endpoint and ID scheme for VoteEvent
objects will use vote
and ocd-vote/{{uuid}}
for VoteEvent.
Each VoteEvent
has the following fields:
- id
Open Civic Data-style id, in the format
ocd-vote/{{uuid}}
.- identifier
optional Upstream identifier if one exists, such as ‘Roll Call #2372’.
- motion
The motion being voted upon. Represented as an object with
text
andclassification
elements.text
is a required string describing the motion.classification
is a list of classifiers (e.g. ‘bill-passage’) and can also be an empty list.In Popolo there is a Motion class that has additional properties, only text and classification are supported at this time.
- start_date
Time at which the vote begins. In flexible YYYY-MM-DD format.
- end_date
optional Time at which the vote ends, should such a time exist. In flexible YYYY-MM-DD format.
- result
The outcome of the vote, can be ‘pass’ or ‘fail’.
- organization, organization_id
The
Organization
in which theVoteEvent
took place.- legislative_session, legislative_session_id
Reference to the
Jurisdiction.legislative_session
theVoteEvent
takes place in.- bill, bill_id
optional Reference to the
Bill
object theVoteEvent
is related to (if the vote in question is on a bill).- votes
A list of objects representing individual legislator’s votes. (Popolo refers to these as Vote).
This list may not be present if the individual voters are not known, for example in the case of a voice vote.
Each element has the following properties:
- voter_name
The name of the voter as it appears on the primary source. (Useful for when it cannot yet be resolved to a specific individual.)
- voter, voter_id
A reference to the
Person
responsible for the vote. (may be null if thevoter_name
has not been resolved to an individual.)- option
The opinion of the
voter
casting thisVote
. See Voting Options.- note
A freeform text field describing any additional information about the vote. An example might be an excuse if the option is ‘excused’.
- counts
A list of count objects (what Popolo calls Count).
These represent the total number of individuals voting a particular way. Each has two properties:
- option
The voting option being tallied. See Voting Options.
- value
The total number of individuals voting this way. (Should match the sum of the
votes
with the sameoption
in almost every case, assuming they are present.)
- created_at
Time that this object was created at in the system, not to be confused with the start_date.
- updated_at
Time that this object was last updated in the system.
- sources
List of sources used in assembling this object. Has the following properties:
- url
URL of the resource.
- note
optional Description of what this source was used for.
- extras
Common to all Open Civic Data types, the value is a key-value store suitable for storing arbitrary information not covered elsewhere.
Voting Options¶
The possible values of counts.option
and votes.option
are as follows:
yes
no
abstain
absent
not voting
paired
Additional values will be added in the future as needed.
Differences from Popolo¶
VoteEvent
has anextra
attribute which is not defined in Popolo.Vote
objects (withinVoteEvent.votes
) have avoter_name
property that is used for when a voter cannot be linked to a knownPerson
. Additionally,voter
can only link to aPerson
.Vote
objects also do not currently support thegroup
,role
,weight
, orpair
properties. There is a chance these will be adopted in the future after their use is necessary.Vote
objects have anote
property that is not present in Popolo’s specification.Motion
objects from Popolo are represented simply asmotion.text
, this is future-proof should we ever choose to adopt additionalMotion
properties.
Copyright¶
This document has been placed in the public domain per the Creative Commons CC0 1.0 Universal license (http://creativecommons.org/publicdomain/zero/1.0/deed).