OCDEP 4: Events¶

Created:: 2014-06-09
Author:: Paul Tagliamonte
Status:: Accepted

Overview¶

Definition of Open Civic Data Events.

Definitions¶

Event: Something happening at a given time and location, past, present or future.
Media: Audio and/or Video recordings.
Agenda: Points to be discussed at the event, as defined in the Agenda section below.

Rationale¶

A core part of the democratic process is ensuring that citizens have representation and a say in how the government operates. One important way in which this happens is through hearings and opportunities for public testimony. As such, Open Civic Data Events need to be able to store data such as hearings, and provide structure to represent this aspect of government.

Implementation¶

Core Fields¶

name: Name of the event, examples include “Fiscal committee meeting on April 10th” or “Appropriations - S/C on Article II”
classification: Classification of the event. Current values (which may be expanded) are committee-meeting and hearing.
start_time: Starting time of the event. This field is serialized as an ISO 8601 datetime string, normalized to UTC, and must be fully datetime aware. ISO 8601 defines times expressed in UTC with a special UTC designator (“Z”) as the timezone.
timezone: This must always be set to the timezone in which the event is held. This also aids in display, since you may always know what the local time of the event is.

Optional Fields¶

agenda

List of agenda items as defined in the Agenda Items section below.

description

Description of the Event.

location

Location object, as defined in the Location section below.

all_day

Boolean value set to boolean True if the event is an all-day event, otherwise it must be set to the boolean value False.

end_time

Ending time of the event. This field is serialized as an ISO 8601 datetime string, normalized to UTC, and must be fully datetime aware. ISO 8601 defines times expressed in UTC with a special UTC designator (“Z”) as the timezone.

status

Status of the event, values are currently:

cancelled for a cancelled event
tentative for an event which is scheduled but not confirmed.
confirmed for an event which is confirmed as happening.
passed for a past event.

links

Links associated with the event, as defined in the Links section below.

participants

Participants associated with the event, as defined in the Participants section below.

documents

List of documents associated with the Event, as described in the Documents section below.

media

List of media objects, as defined in the Media section below.

Location¶

name: Name of the location, such as “City Hall, Boston, MA, USA”, or “221B Baker Street”.
note: Optional human-readable note to help with getting to the meeting place, such as “The meeting will take place at the Minority Whip’s desk on the floor”
url: Optional URI of the venue, such as a webpage.
coordinates: Object to store the exact coordinates of the venue. This object has two keys, latitude and longitude.

Participants¶

name: Name of the participant
id: Open Civic Data ID of the participants
type: Type of the participant, either person or organization.
note: Human-readable note regarding the relationship

Agenda Items¶

Agenda items are the list of topics to be discussed at the meeting, as well as metadata related to the topic or proceeding.

Required Fields¶

description: Description of the agenda item. Examples include “Consideration of SB 2339, HB 100” or “John Q. Public will give testimony”.

Optional Fields¶

related_entities: List of objects as defined in the Related Entities section below.
media: List of media objects, as defined in the Media section below.
documents: List of documents associated with the Agenda Item, as described in the Documents section below.
notes: List of strings, which store any notes taken during the event while discussing this item.
subjects: List of subjects (stored as strings) of this item.

Documents¶

Related documents to the event, things like pre-written testimony, spreadsheets or a slide deck should be related here.

note: Relationship of the document to the event. Examples include “Fiscal Report” or “John Smith’s slides”
url: URI where the content may be found.
media_type: Full IANA media type of the remote content.

Links¶

Links are a list of related URLs which are not documents, media or agenda items. Examples include a committee’s homepage, reference material or links to learn more about subjects related to the event.

note: Human-readable name of the link.
url: URI pointing to the resource referenced.

Media¶

Media, most often recordings of the event, are extremely useful for those who wish to review what was dicsussed at a meeting, and provides a record of resolutions to issues discussed.

Required Fields¶

name: A required string that describes the particular media link. Examples include “Discussion of the contstruction near the watershed” or “Fiscal committee meeting on April 9th.”
type: What kind of media this is, as defined below in the section Defined Types.
links: List of objects which contain two keys, url and media_type. url is a fully qualified URI to the media. media_type is the full IANA media type of the content at the URI.

Optional Fields¶

date: A string in YYYY-MM-DD format which stores the date of the recording.
offset: Integer offset into the media to use as a starting point. This is defined as a nonzero positive integer, the value of which is the number of seconds into the recording to skip to. Implementations should use this (if present) as the starting point when playing back video.

Defined Types¶

recording: A recording of the event
testimony: recorded testimony, either pre-recorded and submitted, or a recording made at the event.

Examples¶

Example:

{
    "_id": "ocd-event/146e36d8-d243-11e3-ad6e-f0def1bd7298",
    "_type": "event",
    "agenda": [
        {
            "description": "Opening remarks from Speaker Andy Tobin",
            "order": 1,
            "subjects": [],
            "media": [],
            "notes": [],
            "related_entities": [
                {
                    "id": "ocd-person/072c3c11-cd8c-4544-9ab1-b60486e1832e",
                    "name": "Andy Tobin",
                    "note": "speaker"
                }
            ]
        },
        {
            "description": "Presentation by Director Henry Darwin, Arizona Department of Environmental Quality, regarding the Environmental Protection Agency (EPA) Clean Power Plan proposed rule",
            "order": 2,
            "subjects": ["epa", "green energy", "environmental issues"],
            "media": [],
            "notes": [],
            "related_entities": [
                {
                    "id": "ocd-person/a284a515-32b2-4338-a38d-1938a4ac9f8f",
                    "name": "Henry Darwin",
                    "note": null
                },
                {
                    "id": "ocd-organization/684139f7-b5a5-4702-9a92-2be976b29eef",
                    "name": "Environmental Protection Agency (EPA)",
                    "note": null
                }
            ]
        },
        {
            "description": "Public Testimony",
            "order": 3,
            "subjects": [],
            "media": [],
            "notes": [],
            "related_entities": []
        },
    ],
    "all_day": false,
    "description": null,
    "documents": [
        {
            "note": "Agenda",
            "url": "http://committee.example.com/agenda.pdf",
            "media_type": "application/pdf",
        }
    ],
    "end": null,
    "extras": {},
    "links": [
        {
            "name": "EPA Website",
            "url": "http://www.epa.gov/"
        }
    ],
    "location": {
        "coordinates": {
            "latitude": "33.448040",
            "longitude": "-112.097379"
        },
        "name": "State Legislative Building",
        "note": null
    },
    "media": [
        {
            "date": "2014-04-12",
            "links": [
                {
                    "media_type": "video/mp4",
                    "url": "http://example.com/video.mp4"
                },
                {
                    "media_type": "video/webm",
                    "url": "http://example.com/video.webm"
                }
            ],
            "name": "Recording of the meeting",
            "offset": 19,
            "type": "recording"
        }
    ],
    "name": "Meeting of the Committee on Energy",
    "participants": [
        {
            "id": "ocd-organization/487b972c-4aa6-40e7-b355-0d73580e06e8",
            "name": "Committee on Energy",
            "note": "Host Committee"
        },
        {
            "id": "ocd-person/072c3c11-cd8c-4544-9ab1-b60486e1832e",
            "name": "Andy Tobin",
            "note": "Speaker"
        }
    ],
    "sources": [
        {
            "note": "scraped source",
            "url": "http://example.com/events"
        }
    ],
    "status": "passed",
    "type": "event",
    "start_date": 1408932805.0
}

Defined Schema¶

Schema:

media_schema = {
    "items": {
        "properties": {
            "name": { "type": "string" },
            "type": { "type": "string" },
            "date": fuzzy_date_blank,
            "offset": { "type": ["number", "null"] },
            "links": {
                "items": {
                    "properties": {
                        "media_type": { "type": "string", "blank": True },
                        "url": { "type": "string" },
                    },
                    "type": "object"
                },
                "type": "array"
            },
        },
        "type": "object"
    },
    "type": "array"
}

schema = {
    "properties": {
        "name": { "type": "string" },
        "start_time": { "type": "datetime", },
        "timezone": { "type": "string" },
        "all_day": { "type": "boolean" },
        "end_time": { "type": ["datetime", "null"] },
        "status": {
            "type": "string", "blank": True,
            "enum": ["cancelled", "tentative", "confirmed", "passed"],
        },
        "classification": { "type": "string" }, # TODO: enum
        "description": { "type": "string", "blank": True, },

        "location": {
            "type": "object",
            "properties": {

                "name": { "type": "string", },

                "note": {
                    "type": "string", "blank": True,
                },

                "url": {
                    "required": False,
                    "type": "string",
                },

                "coordinates": {
                    "type": ["object", "null"],
                    "properties": {
                        "latitude": {
                            "type": "string",
                        },

                        "longitude": {
                            "type": "string",
                        }
                    }
                },
            },
        },

        "media": media_schema,

        "documents": {
            "items": {
                "properties": {
                    "note": { "type": "string", },
                    "url": { "type": "string", },
                    "media_type": { "type": "string", },
                },
                "type": "object"
            },
            "type": "array"
        },

        "links": {
            "items": {
                "properties": {

                    "note": {
                        "type": "string",
                        "blank": True,
                    },

                    "url": {
                        "format": "uri",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "type": "array"
        },

        "participants": {
            "items": {
                "properties": {

                    "name": {
                        "type": "string",
                    },

                    "id": {
                        "type": ["string", "null"],
                    },

                    "type": {
                        "enum": ["organization", "person"],
                        "type": "string",
                    },

                    "note": {
                        "type": "string",
                    },

                },
                "type": "object"
            },
            "type": "array"
        },

        "agenda": {
            "items": {
                "properties": {
                    "description": { "type": "string", },

                    "order": {
                        "type": ["string", "null"],
                    },

                    "subjects": {
                        "items": {"type": "string"},
                        "type": "array"
                    },

                    "media": media_schema,

                    "notes": {
                        "items": {
                            "type": "string",
                        },
                        "type": "array",
                        "minItems": 0,
                    },

                    "related_entities": {
                        "items": {
                            "properties": {
                                "entity_type": {
                                    "type": "string",
                                },

                                "id": {
                                    "type": ["string", "null"],
                                },

                                "name": {
                                    "type": "string",
                                },

                                "note": {
                                    "type": ["string", "null"],
                                },
                            },
                            "type": "object",
                        },
                        "minItems": 0,
                        "type": "array",
                    },
                },
                "type": "object"
            },
            "minItems": 0,
            "type": "array"
        },
        "sources": sources,
        "extras": extras,
    },
    "type": "object"
}

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).

OCDEP 4: Events¶

Overview¶

Definitions¶

Rationale¶

Implementation¶

Core Fields¶

Optional Fields¶

Location¶

Participants¶

Agenda Items¶

Required Fields¶

Optional Fields¶

Related Entities¶

Documents¶

Links¶

Media¶

Required Fields¶

Optional Fields¶

Defined Types¶

Examples¶

Defined Schema¶

Further Reading¶

Copyright¶