beta
aboutspecificationbuildervalidator

civic.json

(extended)

document your project for the betterment of humankind

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Specification

File location and contents

  1. civic.json MUST reside in the root directory of a project's repository.
  2. civic.json MUST include a single object represented as JSON, with key-value pairs according to the list below.

Fields

Required

The following fields MUST be included:

  1. name - a string specifying the project's name.
  2. status - a string indicating the status of the project. The value MUST be one of:
    1. "Ideation" - brainstorming phase.
    2. "Alpha" - initial prototyping phase and internal testing.
    3. "Beta" - a product is being tested in public.
    4. "Production" - finished Product, with development and maintenance ongoing.
    5. "Archival" - finished Product, but no longer actively maintained.
  3. tags - an array of tag strings to help people search for your project, which SHOULD have at least one item.

Strongly recommended

In addition to the above fields, the following fields SHOULD be included in every civic.json, where applicable:

  1. contact - an object providing the individual or group fielding questions about the project. The object structure MUST contain a name property and SHOULD contain an email and/or url property.
  2. description - a description of the project usable as a summary.
  3. homepage - the project's URL, if it is a website, or the URL of a site describing the project.
  4. id - the URL describing the schema of the civic.json file.
  5. license - a field specifying the license under which the project is provided. This property is not legally binding and does not guarantee that the project is licensed under the terms defined in this property. The value of the propery SHOULD be a current SPDX license identifier for the license you're using—preferably one that is OSI approved. Alternatively, you MAY provide the url to a license file.
  6. repository - the project's public repository URL.

Recommended

The following are commonly used fields that your civic.json MAY contain:

  1. data - an array of data objects, describing the data sources used in the project. Each data object MUST include name and url properties, giving the dataset's name and download URL, respectively. Each data object SHOULD also include a metadata property, providing the URL where the dataset's metadata can be read.
  2. geography - an array of geography strings, indicating the city, state, county, or other geographic entity the project is relevant to.
  3. links - an array of link strings, giving any additional webpage URLs relevant to your project.
  4. partners - an array of partner objects, describing the primary individuals or groups that contributing to the project. Each partner object MUST contain a name property and SHOULD contain an email and/or url property.
  5. thumbnail - the URL of an image file (e.g. logo or screenshot) to be used in a project listing.
  6. type - a string describing the type of project.

Other

You MAY include other fields not listed above.