The key words must, must not, should, should not and may are to be interpreted as described in RFC 2119.

1. Scope

The data specification will define terms (classes and properties) to describe and relate the entities below:

Person
A real person, alive or dead

e.g. William Shakespeare

Organization
A collection of people with a common purpose or reason for existence that goes beyond the set of people belonging to it

e.g. a social, commercial or political structure

Membership
A relationship between a member and an organization

e.g. member of the XYZ Party

Post
A position in an organization that exists independently of the person holding it

e.g. Member of Parliament for Avalon

Contact detail
A means of contacting a person, organization or post

e.g. a telephone number, email address, postal address, contact form, etc.

Motion
A formal step to introduce a matter for consideration by an organization

e.g. "That the House do now proceed to the Orders of the Day."

Vote event
An event at which people's votes are recorded

e.g. a vote to pass a bill

Count
The number of votes for an option in a vote event

e.g. 128 votes in favor of passage

Vote
A voter's vote in a vote event

e.g. John Q. Public voted in favor of passage

Area
A geographic area whose geometry may change over time

e.g. a country, city, ward, etc.

Event
An occurrence that people may attend

e.g. a legislative session, a meeting, a hearing, etc.

Speech
A speech by a person, a scene (e.g. applause), a narrative (e.g. "The House rose at 3:20pm"), or another non-speech part of a discussion (e.g. a list of bills).

e.g. a representative addressing the legislature

2. Conformance

  1. A conforming implementation may use only a subset of this specification’s terms.
  2. It must not use terms from outside this specification’s terms where this specification’s terms would suffice1.
  3. It may use terms from outside this specification’s terms where this specification’s terms are insufficient.
  4. Its usage of this specification’s terms must be consistent with the semantics of those terms.
  5. If an implementation serializes to JSON, its serializations must validate against this specification’s JSON Schema.

1. For example, it must not use vCard's fn where this specification's name would suffice.

3. Use cases & requirements

The data specification should:

  1. Allow the use of imprecise dates [issue 7].

    Shakespeare was born in April 1564.

  2. Have a permanent, unique identifier for each instance of the class.

    e.g. a URL, an integer or a hex string.

Each resource should have metadata properties for:

  1. time of creation

    The electronic resource for Shakespeare was created on May 1, 2000.

  2. time of modification

    The electronic resource for Shakespeare was modified on June 15, 2005.

  3. references to sources of information from which the resource is derived

    e.g. a book, a website or other reference material.

The subdocuments in a later section add more requirements.

4. Standard reuse

Following a survey of existing specifications, the data specification reuses terms from:

Publisher Name Prefix
Bibliographic Framework Initiative BIBFRAME Vocabulary bf
BIO: A vocabulary for biographical information bio
W3C Contact: Utility concepts for everyday life con
DCMI DCMI Metadata Terms dcterms
FOAF Vocabulary Specification foaf
GeoNames GeoNames Ontology gn
ISA ISA Programme Location Core Vocabulary locn
OSCA Foundation NEPOMUK Calendar Ontology ncal
Open Data Institute Open Data Rights Statement Vocabulary odrs
W3C The Organization Ontology org
ISA ISA Programme Person Core Vocabulary person
W3C RDF Schema rdfs
W3C Schema.org schema
W3C SKOS Simple Knowledge Organization System skos
IETF vCard Format Specification vcard

The inventory of terms from the surveyed specifications is captured in an appendix.

The subdocuments in the next section describe specific standard reuse. Some impose cardinality and range restrictions on the properties of the above specifications, in order to allow for a simpler JSON serialization.

5. Classes and properties

Each of the following subdocuments describes a class and its properties:

The structure of each subdocument is:

1. Use cases & requirements
Provides a motivation for the class and its properties
2. Standard reuse
Evaluates and selects existing specifications for reuse
3. Classes and properties
Defines the semantics of the class and its properties
4. Serialization
Defines the RDF and JSON serializations
5. Code lists
Lists any standardized nomenclatures used as property values

The following diagram succinctly describes the relationships among the people and organizations classes. All arrows are one-to-many relationships.

UML diagram

5.1. Metadata properties

The following table defines the metadata properties and maps each term to an RDF URI2:

Term Mapping Definition
time of creation dcterms:created The time at which a resource was created
time of modification dcterms:modified The time at which a resource was modified
source document dcterms:source A URL to, or a citation of, a document from which the resource is derived

2. If you do not use RDF, you may ignore the mapping.

6. Serialization

The data specification defines two serializations: RDF and JSON. RDF is a technology for data modeling, with a variety of syntax notations and serialization formats, including XML, JSON (via JSON-LD), HTML (via RDFa or RDFa Lite), and N3 (a superset of the simpler Turtle and N-Triples formats). JSON is a text-based, language-independent interchange format for structured data, derived from the JavaScript scripting language.

Given that the same RDF resource can be serialized in many different ways using JSON-LD, JSON Schema are provided below to ensure all JSON serializations look alike, to maximize interoperability. A JSON-LD serialization will nonetheless differ from a plain JSON serialization in a few ways:

  • A JSON-LD serialization should use the @context, @type and @id keywords.
  • The value of the email property of a Person must be a ‘mailto’ URI.
  • The value of the role property of a Membership, Post, Vote or Speech must be a URI or blank node for a org:Role.
  • The value of the classification property of an Organization or Motion must be a URI or blank node for a skos:Concept.
  • The value of the classification property of an Area must be a URI or blank node for a gn:Code, which is a subclass of skos:Concept.
  • The value of the type property of a ContactDetail must be a node type, i.e. an IRI.
  • The value of the scheme property of an Identifier must be a value type, i.e. an IRI.
  • The value of the requirement property of a Motion must be a URI or blank node for a opengov:Requirement.
  • The value of the result property of a Motion, VoteEvent or GroupResult must be a URI or blank node for a opengov:Result.
  • The value of the location property of an Event must be a URI or blank node for a schema:Place or schema:PostalAddress.
  • The value of the status property of an Event must be a URI or blank node for a schema:EventStatusType.
  • The value of the audio property of a Speech must be a URI or blank node for a schema:AudioObject.
  • The value of the video property of a Speech must be a URI or blank node for a schema:VideoObject.
  • The value of the links and sources properties must be an array of URIs, not an array of link objects.
  • A JSON-LD serialization should not use the *_id properties:
JSON-LD JSON
@id id
area area_id
audience audience_id
creator creator_id
event event_id
group group_id
legislative_session legislative_session_id
on_behalf_of on_behalf_of_id
organization organization_id
pair pair_id
parent parent_id
person person_id
post post_id
vote_event vote_event_id
voter voter_id

Dates must be stored in UTC. To allow for imprecise dates, the use of ISO 8601:2004 reduced dates3 is recommended. In RDF, the dcterms:W3CDTF datatype is recommended.

Additional serialization details are given in the subdocuments in the previous section.

3. Consult the list of reduced date formats. XML Schema supports reduced dates such as YYYY and YYYY-MM.

6.1. JSON schema and examples

As described in the conformance section, JSON serializations must validate against the JSON Schema (draft v3) below. The terms use snake case (birth_date) instead of camel case (birthDate), due to its popularity among ORMs.

JSON Schema JSON-LD Context Sample JSON document Sample RDF document
Person person.jsonld person.json person.ttl
Organization organization.jsonld organization.json organization.ttl
Membership membership.jsonld membership.json membership.ttl
Post post.jsonld post.json post.ttl
Contact detail contact_detail.jsonld contact_detail.json contact_detail.ttl
Motion motion.jsonld motion.json motion.ttl
Vote event vote_event.jsonld vote_event.json vote_event.ttl
Count count.jsonld count.json count.ttl
Vote vote.jsonld vote.json vote.ttl
Area area.jsonld area.json area.ttl
Event event.jsonld event.json event.ttl
Speech speech.jsonld speech.json speech.ttl

6.2. Metadata serialization

JSON differences from other RDF serializations:

  • Whereas other RDF serializations may have multiple modification times and may cite a variety of materials as sources, the JSON serialization must serialize only the last modification time and cite only URIs.
  • The term created_at is used instead of created, due to its popularity among ORMs.
  • The term updated_at is used instead of modified, due to its popularity among ORMs.
  • The term sources is used instead of source and is serialized as an array of link objects.

The following examples use a Person document to demonstrate the metadata properties.

6.3. Embedded JSON documents

When serializing to JSON, you may relate entities by linking and/or embedding relations.

Linking Embedding Inverse
area_id area memberships, organizations, posts
audience_id audience
creator_id creator motions, speeches
event_id event speeches
group_id group
legislative_session_id legislative_session motions, vote_events
member memberships
motion_id motion vote_events
on_behalf_of_id on_behalf_of
organization_id organization memberships, motions, posts, vote_events
pair_id pair
parent_id parent children
person_id person memberships
post_id post memberships
vote_event_id vote_event votes
voter_id voter votes

contact_details, counts, group_results, identifiers, links, other_names and sources are embedded only.

The first option is straight-forward and is used in the examples in the subdocuments above.

To embed an organization’s posts on its Organization document, add a plural posts property to that document, whose value is an array of Post documents. Since the organization_id property on each Post subdocument is redundant with the id property on the Organization document, you may omit the organization_id property from each subdocument.

For the inverse relation, i.e. to embed a post’s organization on its Post document, add a singular organization property to that document, whose value is the Organization document. You may omit the organization_id property from the Post document, since it is redundant with the id property on the Organization document.

In the case of an organization’s memberships, an organization may both have members and be a member of other organizations. As such, the organization_id property should be present on each subdocument, to avoid ambiguity.

At the risk of stating the obvious, you must not embed an entity in another unless the two are related. You may embed to any depth, but you must not embed recursively, e.g. embed an organization in a post in an organization.

6.4. JSON subschema

The JSON Schema above reuse the following subschema for specific properties.

6.4.1. Identifier

With respect to standard reuse, the term scheme is used in the Organization ontology, SKOS and XBRL.

JSON differences from other RDF serializations:

With respect to standard reuse, note comes from skos:note.

JSON differences from other RDF serializations:

  • A new note property adds a note (e.g. “Wikipedia page”) to the external link.

6.4.3 Other name

If a name object sets an end_date property, it represents a former name. With respect to standard reuse, the terms start_date and end_date are used in the Participation ontology and others, and note comes from skos:note.

6.4.4 Group result

For political groups, the range of the group property will be an organization. For ethnic groups, as in the House of Peoples, it will be an object (a foaf:Group) with a name (a foaf:name).

7. Change history

  • 2022-11-10: Add a pronouns property to the Person class.
  • 2017-05-27: Allow time zones in time values.
  • 2017-02-20: Inherit classification from Event to VoteEvent.
  • 2015-05-05: Add time components to the date properties of the Membership class.
  • 2015-03-03: Use schema:dissolutionDate instead of opengov:dissolutionDate.
  • 2015-03-02: Add an Event class.
  • 2015-02-26: name is no longer a required property in other_name.json.
  • 2014-12-21: Add one-line description and extended description properties to the Organization class.
  • 2014-12-18: A Vote must have a VoteEvent.
  • 2014-12-18: Add missing inverse embedding properties.
  • 2014-12-15: Add an identifier property to the Motion class.
  • 2014-12-14: Add a video property to the Speech class.
  • 2014-11-23: Add a Speech class.
  • 2014-10-28: A Membership need not have an organization if it has a post.
  • 2014-06-22: Remove the object property from the Motion class.
  • 2014-06-22: Add a group result property to the VoteEvent class.
  • 2014-06-22: Add a group property to the Count class.
  • 2014-06-22: Replace the context property with a legislative session property in the VoteEvent class.
  • 2014-06-16: Remove the object_id property from the Motion class’ JSON Schema.
  • 2014-06-14: Add a classification property to the Motion class.
  • 2014-06-14: Add organization and context properties to the VoteEvent class.
  • 2014-06-14: Add a result property to the VoteEvent class.
  • 2014-06-06: Rename the property party to group in the Vote class.
  • 2014-05-09: Add a member property to the Membership class, to relate organizations to organizations.
  • 2014-05-08: Add an Area class and a geographic area property to the Membership, Organization, and Post classes.
  • 2014-05-08: Use schema:validUntil instead of schema:validThrough, for a meaning common to UK and US English.
  • 2014-05-07: Add valid from and valid until properties to the ContactDetail class.
  • 2014-05-07: Add an alternate label property to the Post class.
  • 2014-05-06: Add Motion, VoteEvent, Count and Vote classes.
  • 2014-03-28: Add name component properties to opengov:OtherName.
  • 2014-02-10: name and label are no longer required properties in the JSON Schema.
  • 2014-01-23: Add a national identity property to the Person class.
  • 2013-10-14: Add a property to the Membership class for the organization on whose behalf the person is a party to the relationship.
  • 2013-09-08: Add an image property to the Organization class.
  • 2013-08-28: Add JSON-LD contexts.
  • 2013-08-28: Use schema:validFrom and schema:validThrough instead of org:memberDuring.
  • 2013-07-08: Add a label property to the Membership class.
  • 2013-07-08: Add time of creation, time of modification, and source document metadata properties.
  • 2013-06-20: Reorganize specification and implement feedback.
  • 2013-02-28: Add requirement for dates to be stored in UTC.
  • 2013-02-25: Add conformance requirements. Relax requirements with respect to MongoDB collection names.
  • 2013-02-16: Add a label property to the Post class. Change the cardinality of the classification property of the Organization class.
  • 2013-02-01: First public working draft.

Browse all Git commits on GitHub