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.

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"
}

Further Reading

Many ideas here were based on the work in Open States Schema.

Read the Docs v: latest
Versions
latest
Downloads
pdf
htmlzip
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.