This document describes best practices for software components implementing the Popolo specification.
It is recommended to use a URI as the permanent, unique identifier of each instance of each class when distributing data as JSON:
{
"id": "http://example.com/people/john-q-public",
}
A software component may instead choose to use e.g. MongoDB’s automatically-assigned hexadecimal strings as its internal, permanent, unique identifier and to put URIs in the metadata of the JSON document, e.g. using the Hypertext Application Language (HAL):
{
"_links": {
"self": { "href": "http://example.com/people/507f1f77bcf86cd799439011" }
},
"id": "507f1f77bcf86cd799439011",
}
Reusable software components implementing the data specification may want to isolate their database tables from those of their host application. A software component may therefore namespace its database tables by prepending popolo_ to the names of its database tables.
If two software components are to interoperate by allowing direct access to each others’ database (as opposed to offering an API), those databases must agree on the names of their tables. The names must be among the following (optionally prefixed with popolo_):
areascontact_detailscountseventsgroup_resultsidentifierslinksmembershipsmotionsorganizationsother_namespeoplepostssourcesspeechesvote_eventsvotesA developer creates a platform for citizens to ask questions to legislators in public. The platform relies on a third-party data collection system to provide the legislator profiles. The platform is distributed as open source, and lets re-users choose a Popolo-compliant data collection system that best fits their process; for example, an organization with active volunteers may prefer a manual data entry system, whereas another with technical expertise may prefer a data scraping system.
Unless all these systems use the same names for their database tables, the question-and-answer platform will need to add logic to test for known "in-the-wild" database table names used by various Popolo-compliant projects in order to interoperate with them.
MongoDB does not support reduced dates like 2004-08 as in XML Schema; it stores a date as a 64-bit integer that represents the number of milliseconds since the Unix epoch. Unless a use case emerges requiring fast date operations, dates should be serialized as strings in MongoDB.
Many MongoDB ODMs, including Mongoid, use a _type field on a document to indicate that the document represents an instance of a subclass of the base class that is otherwise associated with the MongoDB collection. The management of the _type field should be left to the ODM.