Project Open Data Metadata Schema v1.1

New Schema
This version of the schema replaces Project Open Data Metadata Schema v1.0. Federal CFO-Act agencies are expected to complete the transition to the v1.1 schema by February 1st, 2015.

To see changes from v1.0 to v1.1 see the Version 1.1 Update especially the field mappings in Metadata Resources and the Metadata Changelog


This section contains guidance to support the use of the Project Open Data metadata to list agency datasets and application programming interfaces (APIs) as hosted at agency.gov/data.

Updates to the metadata schema can be found in the changelog. Current metadata version: 1.1 as of November 6th, 2014.

Standard Metadata Vocabulary

Metadata is structured information that describes, explains, locates, or otherwise makes it easier to retrieve, use, or manage an information resource (NISO 2004, ISBN: 1-880124-62-9). The challenge is to define and name standard metadata fields so that a data consumer has sufficient information to process and understand the described data. The more information that can be conveyed in a standardized regular format, the more valuable data becomes. Metadata can range from basic to advanced, from allowing one to discover the mere fact that a certain data asset exists and is about a general subject all the way to providing detailed information documenting the structure, processing history, quality, relationships, and other properties of a dataset. Making metadata machine readable greatly increases its utility, but requires more detailed standardization, defining not only field names, but also how information is encoded in the metadata fields.

Establishing a common vocabulary is the key to communication. The metadata schema specified in this memorandum is based on DCAT, a hierarchical vocabulary specific to datasets. This specification defines three types of metadata elements: Required, Required-if (conditionally required), and Expanded fields. These elements were selected to represent information that is most often looked for on the web. To assist users of other metadata standards, field mappings to equivalent elements in other standards are provided.

What to Document – Datasets and Web APIs

A dataset is an identifiable collection of structured data objects unified by some criteria (authorship, subject, scope, spatial or temporal extent…). A catalog is a collection of descriptions of datasets; each description is a metadata record. The intention of a data catalog is to facilitate data access by users who are first interested in a particular kind of data, and upon finding a fit-for-purpose dataset, will next want to know how to get the data.

A Web API (Application Programming Interface) allows computer programs to dynamically query a dataset using the World Wide Web. For example, a dataset of farmers markets may be made available for download as a single file (e.g., a CSV), or may be made available to developers through a Web API, such that a computer program could use a ZIP Code to retrieve a list of farmers markets in the ZIP Code area.

The catalog file for each agency should list all of the agency’s datasets that can be made public, regardless of whether they are distributed by a file download or a Web API. Please also see the extended guidance on documenting Web APIs in your data.json files.

Metadata File Format – JSON

The Implementation Guidance available as a part of Project Open Data describes Agency requirements for the development of metadata as per the Open Data Policy. A quick primer on the file format involved:

JSON is a lightweight data-exchange format that is very easy to read, parse and generate. Based on a subset of the JavaScript programming language, JSON is a text format that is optimized for data interchange. JSON is built on two structures: (1) a collection of name/value pairs and (2) an ordered list of values.

Where optional fields are included in a catalog file but are unpopulated, they may be represented by a null value. They should not be represented by an empty string ("").

When a record has an accessURL or downloadURL, they should be contained as objects within a distribution. Any object may be described by title, description, format, or mediaType, though when an object contains downloadURL, it must be accompanied by mediaType.

The Project Open Data schema is case sensitive. The schema uses a camel case convention where the first letter of some words within a field are capitalized (usually all words but the first one). While it may seem subtle which characters are uppercase and lowercase, it is necessary to follow the exact same casing as defined in the schema documented here. For example:

Correct: contactPoint
Incorrect: ContactPoint
Incorrect: contactpoint
incorrect: CONTACTPOINT

Links to downloadable examples of metadata files developed in this and other formats are in the metadata resources. Tools to help agencies produce and maintain their data inventories are available on GitHub and hosted at Labs.Data.gov.

Catalog Fields

These fields describe the entire Public Data Listing catalog file. Publishers can also use the describedBy field to reference the default JSON Schema file used to define the schema (https://project-open-data.cio.gov/v1.1/schema/catalog.json) or they may refer to their own JSON Schema file if they have extended the schema with additional schema definitions. Similarly, @context can be used to reference the default JSON-LD Context used to define the schema (https://project-open-data.cio.gov/v1.1/schema/catalog.jsonld) or publishers can refer to their own if they have extended the schema with additional linked data vocabularies. See the Catalog section under Further Metadata Field Guidance for more details.

Field Label Definition Required
@context Metadata Context URL or JSON object for the JSON-LD Context that defines the schema used. No
@id Metadata Catalog ID IRI for the JSON-LD Node Identifier of the Catalog. This should be the URL of the data.json file itself. No
@type Metadata Type IRI for the JSON-LD data type. This should be dcat:Catalog for the Catalog. No
conformsTo Schema Version URI that identifies the version of the Project Open Data schema being used. Always
describedBy Data Dictionary URL for the JSON Schema file that defines the schema used. No
dataset Dataset A container for the array of Dataset objects. See Dataset Fields below for details. Always

Dataset Fields

See the Further Metadata Field Guidance section to learn more about the use of each element, including the range of valid entries where appropriate. Consult the field mappings to find the equivalent v1.0, DCAT, Schema.org, and CKAN fields.

Field Label Definition Required
@type Metadata Type IRI for the JSON-LD data type. This should be dcat:Dataset for each Dataset. No
title Title Human-readable name of the asset. Should be in plain English and include sufficient detail to facilitate search and discovery. Always
description Description Human-readable description (e.g., an abstract) with sufficient detail to enable a user to quickly understand whether the asset is of interest. Always
keyword Tags Tags (or keywords) help users discover your dataset; please include terms that would be used by technical and non-technical users. Always
modified Last Update Most recent date on which the dataset was changed, updated or modified. Always
publisher Publisher The publishing entity and optionally their parent organization(s). Always
contactPoint Contact Name and Email Contact person’s name and email for the asset. Always
identifier Unique Identifier A unique identifier for the dataset or API as maintained within an Agency catalog or database. Always
accessLevel Public Access Level The degree to which this dataset could be made publicly-available, regardless of whether it has been made available. Choices: public (Data asset is or could be made publicly available to all without restrictions), restricted public (Data asset is available under certain use restrictions), or non-public (Data asset is not available to members of the public). Always
bureauCodeUSG Bureau Code Federal agencies, combined agency and bureau code from OMB Circular A-11, Appendix C (PDF, CSV) in the format of 015:11. Always
programCodeUSG Program Code Federal agencies, list the primary program related to this data asset, from the Federal Program Inventory. Use the format of 015:001. Always
license License The license or non-license (i.e. Public Domain) status with which the dataset or API has been published. See Open Licenses for more information. If-Applicable
rights Rights This may include information regarding access or restrictions based on privacy, security, or other policies. This should also serve as an explanation for the selected “accessLevel” including instructions for how to access a restricted file, if applicable, or explanation for why a “non-public” or “restricted public” data asset is not “public,” if applicable. Text, 255 characters. If-Applicable
spatial Spatial The range of spatial applicability of a dataset. Could include a spatial region like a bounding box or a named place. If-Applicable
temporal Temporal The range of temporal applicability of a dataset (i.e., a start and end date of applicability for the data). If-Applicable
distribution Distribution A container for the array of Distribution objects. See Dataset Distribution Fields below for details. If-Applicable
accrualPeriodicity Frequency The frequency with which dataset is published. No
conformsTo Data Standard URI used to identify a standardized specification the dataset conforms to. No
dataQualityUSG Data Quality Whether the dataset meets the agency’s Information Quality Guidelines (true/false). No
describedBy Data Dictionary URL to the data dictionary for the dataset. Note that documentation other than a data dictionary can be referenced using Related Documents (references). No
describedByType Data Dictionary Type The machine-readable file format (IANA Media Type also known as MIME Type) of the dataset’s Data Dictionary (describedBy). No
isPartOf Collection The collection of which the dataset is a subset. No
issued Release Date Date of formal issuance. No
language Language The language of the dataset. No
landingPage Homepage URL This field is not intended for an agency’s homepage (e.g. www.agency.gov), but rather if a dataset has a human-friendly hub or landing page that users can be directed to for all resources tied to the dataset. No
primaryITInvestmentUIIUSG Primary IT Investment UII For linking a dataset with an IT Unique Investment Identifier (UII). No
references Related Documents Related documents such as technical information about a dataset, developer documentation, etc. No
systemOfRecordsUSG System of Records If the system is designated as a system of records under the Privacy Act of 1974, provide the URL to the System of Records Notice related to this dataset. No
theme Category Main thematic category of the dataset. No

Dataset Distribution Fields

Within a dataset, distribution is used to aggregate the metadata specific to a dataset’s resources (accessURL and downloadURL), which may be described using the following fields. Each distribution should contain one accessURL or downloadURL. A downloadURL should always be accompanied by mediaType.

Field Label Definition Required
@type Metadata Type IRI for the JSON-LD data type. This should be dcat:Distribution for each Distribution. No
accessURL Access URL URL providing indirect access to a dataset, for example via API or a graphical interface. If-Applicable
conformsTo Data Standard URI used to identify a standardized specification the distribution conforms to. No
describedBy Data Dictionary URL to the data dictionary for the distribution found at the downloadURL. Note that documentation other than a data dictionary can be referenced using Related Documents as shown in the expanded fields. No
describedByType Data Dictionary Type The machine-readable file format (IANA Media Type or MIME Type) of the distribution’s describedBy URL. No
description Description Human-readable description of the distribution. No
downloadURL Download URL URL providing direct access to a downloadable file of a dataset. If-Applicable
format Format A human-readable description of the file format of a distribution. No
mediaType Media Type The machine-readable file format (IANA Media Type or MIME Type) of the distribution’s downloadURL. If-Applicable
title Title Human-readable name of the distribution. No

Extending the Schema

“Extensional” and/or domain specific metadata can easily be added using other vocabularies even if it is not a term (entity/property) that will get indexed by the major search engines - it could still be indexed by other custom search engines and by Data.gov. Publishers are encouraged to extend their metadata descriptions using elements from the “Expanded Fields” list shown below, or from any well-known vocabulary (including Dublin Core, Schema.org, FGDC, ISO 19115, and NIEM) as long as they are properly assigned. It’s also recommended that these extensions be defined through the describedBy and @context fields at the top of the Catalog metadata.

Further Metadata Field Guidance

Additional details for each field are provided here broken down into sections for the overarching Catalog, each dataset, and each dataset’s distribution. Consult the field mappings to find the equivalent v1.0, DCAT, Schema.org, and CKAN fields.

  • Key
    • Required
    • Required if Applicable
    • Expanded (optional)

Catalog Fields

Field @context
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes The URL or JSON object for the JSON-LD Context that defines the schema used. The URL for version 1.1 of the schema is https://project-open-data.cio.gov/v1.1/schema/catalog.jsonld
Example {"@context": "https://project-open-data.cio.gov/v1.1/schema/catalog.jsonld"}
Field @id
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes A unique identifier for the Catalog as defined by JSON-LD Node Identifiers. This should be the URL of the data.json file itself
Example {"@id": "https://www.agency.gov/data.json"}
Field @type
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes The metadata type as defined by JSON-LD data types. This should be dcat:Catalog for the Catalog
Example {"@type": "dcat:Catalog"}
Field conformsTo
Cardinality (1,1)
Required Yes, always
Accepted Values String (URI)
Usage Notes This is used to identify the schema version using a URI. The URI for version 1.1 of the schema is https://project-open-data.cio.gov/v1.1/schema
Example {"conformsTo": "https://project-open-data.cio.gov/v1.1/schema"}
Field describedBy
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes This is used to specify a JSON Schema file that defines all fields. By default, it is recommended that the canonical JSON Schema file is referenced (https://project-open-data.cio.gov/v1.1/schema/catalog.json) but if the schema had been extended, publishers may reference a file that defines those extensions.
Example {"describedBy": "https://project-open-data.cio.gov/v1.1/schema/catalog.json"}
Field dataset
Cardinality (1,n)
Required Yes, always
Accepted Values Array of Objects
Usage Notes This field is a container for an array of Dataset objects. See Dataset Fields below for details
Example {"dataset": [...]}

Dataset Fields

Field @type
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes The metadata type as defined by JSON-LD data types. This should be dcat:Dataset for the Dataset
Example {"@type": "dcat:Dataset"}
Field accessLevel
Cardinality (1,1)
Required Yes, always
Accepted Values Must be one of the following: “public”, “restricted public”, “non-public”
Usage Notes This field refers to the degree to which this dataset could be made available to the public, regardless of whether it is currently available to the public. For example, if a member of the public can walk into your agency and obtain a dataset, that entry is public even if there are no files online. A restricted public dataset is one only available under certain conditions or to certain audiences (such as researchers who sign a waiver). A non-public dataset is one that could never be made available to the public for privacy, security, or other reasons as determined by your agency.
Example {"accessLevel":"public"}
Field accrualPeriodicity
Cardinality (0,1)
Required No
Accepted Values ISO 8601 Repeating Duration (or irregular)
Usage Notes Must be an ISO 8601 repeating duration unless this is not possible because the accrual periodicity is completely irregular, in which case the value should simply be irregular. The value should not include a start or end date but rather simply express the duration of time between data publishing. For example, a dataset which is published on an annual basis would be R/P1Y; every three months would be R/P3M; weekly would be R/P1W; and daily would be R/P1D. Further examples and documentation can be found here.
Example {"accrualPeriodicity":"R/P1Y"}
Field bureauCode
Cardinality (0,n)
Required Yes, for United States Federal Government agencies
Accepted Values Array of Strings
Usage Notes Represent each bureau responsible for the dataset according to the codes found in OMB Circular A-11, Appendix C (PDF, CSV). Start with the agency code, then a colon, then the bureau code.
Example The Office of the Solicitor (86) at the Department of the Interior (010) would be: {"bureauCode":["010:86"]}. If a second bureau was also responsible, the format like this: {"bureauCode":["010:86","010:04"]}.
Field conformsTo
Cardinality (0,1)
Required No
Accepted Values String (URI)
Usage Notes This is used to identify a standardized specification the dataset conforms to. If this is a technical specification associated with a particular serialization of a distribution, this should be specified with conformsTo at the distribution level. It’s recommended that this be a URI that serves as a unique identifier for the standard. The URI may or may not also be a URL that provides documentation of the specification.
Example {"conformsTo": "http://www.agency.gov/common-vegetable-analysis-model/"}
Field contactPoint
Cardinality (1,1)
Required Yes, always
Accepted Values vCard object
Usage Notes This is a container for two fields that together make up the contact information for the dataset. contactPoint should always contain both the person’s appropriately formatted full name (fn) and email (hasEmail).
Example See below
            "contactPoint": {
                "@type": "vcard:Contact",
                "fn": "Jane Doe",
                "hasEmail": "mailto:jane.doe@agency.gov"
            }
Field contactPoint → @type
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes The metadata type as defined by JSON-LD data types. This should be vcard:Contact for contactPoint
Example {"@type": "vcard:Contact"}
Field contactPoint → fn
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes This should include included with hasEmail as part of a record’s contactPoint (see above example).
Example {"fn": "Jane Doe"}
Field contactPoint → hasEmail
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes This should be formatted per vCard specifications (see example below) and included with fn as part of a record’s contactPoint (see above example).
Example {"hasEmail": "mailto:jane.doe@agency.gov"}
Field dataQuality
Cardinality (0,1)
Required No
Accepted Values Must be a boolean value of true or false (not contained within quote marks)
Usage Notes Indicates whether a dataset conforms to the agency’s information quality guidelines.
Example {"dataQuality":true}
Field describedBy
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes This is used to specify a data dictionary or schema that defines fields or column headings in the dataset. If this is a machine readable file, it’s recommended to be specified with describedBy at the distribution level along with the associated describedByType. At the dataset level it’s assumed to be a human readable HTML webpage or PDF document. Documentation that is not specifically a data dictionary belongs in “references”
Example {"describedBy": "http://www.agency.gov/vegetables/definitions.pdf"}
Field describedByType
Cardinality (0,1)
Required No
Accepted Values String (IANA Media Type)
Usage Notes This is used to identify the media type (IANA Media Type also known as MIME Type) of the URL used for the dataset’s describedBy field. This should be specified if describedBy is not an HTML webpage.
Example {"describedByType": "application/pdf"}
Field description
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes This should be human-readable and understandable to an average person.
Example {"description":"This dataset contains a list of vegetables, including nutrition information and seasonality. Includes details on tomatoes, which are really fruit but considered a vegetable in this dataset."}
Field distribution
Cardinality (0,n)
Required Yes, if the dataset has an accessURL or downloadURL.
Accepted Values Array of Objects
Usage Notes This is a container for one or multiple distribution objects which group together the fields: accessURL, conformsTo, downloadURL, describedBy, describedByType, description, format, mediaType, and title.
Example See below
"distribution": [
                 {
                     "@type": "dcat:Distribution",
                     "description": "Vegetable data as a CSV file",
                     "downloadURL": "http://www.agency.gov/vegetables/listofvegetables.csv",
                     "format": "CSV",
                     "mediaType": "text/csv",
                     "title": "listofvegetables.csv"
                 }, 
                 {
                     "@type": "dcat:Distribution",
                     "conformsTo": "http://www.agency.gov/vegetables-data-standard/",
                     "describedBy": "http://www.agency.gov/vegetables/schema.xsd",
                     "describedByType": "text/xml",
                     "description": "Vegetable data as an XML file",
                     "downloadURL": "http://www.agency.gov/vegetables/listofvegetables.xml",
                     "format": "XML",
                     "mediaType": "text/xml",
                     "title": "listofvegetables.xml"
                 },
                 {
                     "@type": "dcat:Distribution",
                     "description": "Vegetable data as a zipped CSV file with attached data dictionary",
                     "downloadURL": "http://www.agency.gov/vegetables/vegetables-all.zip",
                     "format": "Zipped CSV",
                     "mediaType": "application/zip",
                     "title": "vegetables-all.zip"
                 },
                 {
                     "@type": "dcat:Distribution",
                     "accessURL": "http://www.agency.gov/api/vegetables/",
                     "description": "A fully queryable REST API with JSON and XML output",
                     "format": "API",
                     "title": "Vegetables REST API"
                 }
                ]
Field distribution → @type
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes The metadata type as defined by JSON-LD data types. This should be dcat:Distribution for each distribution
Example {"@type": "dcat:Distribution"}
Field distribution → accessURL
Cardinality (0,1)
Required Yes, if the file is accessible indirectly, through means other than direct download.
Accepted Values String (URL)
Usage Notes This should be the URL for an indirect means of accessing the data, such as API documentation, a ‘wizard’ or other graphical interface which is used to generate a download, feed, or a request form for the data. When accessLevel is “restricted public” but the dataset is available online indirectly, this field should be the URL that provides indirect access. This should not be a direct download URL. It is usually assumed that accessURL is an HTML webpage.
Example {"accessURL":"http://www.agency.gov/api/vegetables/"}
Field distribution → conformsTo
Cardinality (0,1)
Required No
Accepted Values String (URI)
Usage Notes This is used to identify a standardized specification the distribution conforms to. It’s recommended that this be a URI that serves as a unique identifier for the standard. The URI may or may not also be a URL that provides documentation of the specification.
Example {"conformsTo": "http://www.agency.gov/vegetables-data-standard/"}
Field distribution → downloadURL
Cardinality (0,1)
Required Yes, if the file is available for public download.
Accepted Values String (URL)
Usage Notes This must be the direct download URL. Other means of accessing the dataset should be expressed using accessURL. This should always be accompanied by mediaType.
Example {"downloadURL":"http://www.agency.gov/vegetables/listofvegetables.csv"}
Field distribution → describedBy
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes This is used to specify a data dictionary or schema that defines fields or column headings in the distribution. If this is a machine readable file the media type should be specified with describedByType - otherwise it’s assumed to be a human readable HTML webpage.
Example {"describedBy": "http://www.agency.gov/vegetables/schema.json"}
Field distribution → describedByType
Cardinality (0,1)
Required No
Accepted Values String (IANA Media Type)
Usage Notes This is used to identify the media type (IANA Media Type also known as MIME Type) of the URL used for the distribution’s describedBy field. This is especially important if describedBy is a machine readable file.
Example {"describedByType": "application/schema+json"}
Field distribution → description
Cardinality (0,1)
Required No
Accepted Values String
Usage Notes This should be a human-readable description of the distribution.
Example {"description":"Vegetable data as a zipped CSV file with attached data dictionary"}
Field distribution → format
Cardinality (0,1)
Required No
Accepted Values String
Usage Notes This should be a human-readable description of the file format of the dataset, that provides useful information that might not be apparent from mediaType. Note that API should always be used to distinguish web APIs.
Example {"format":"CSV"}
Field distribution → mediaType
Cardinality (0,1)
Required Yes, if the file is available for public download.
Accepted Values String (IANA Media Type)
Usage Notes This must describe the exact files available at downloadURL using a media type (IANA Media Type also known as MIME Type). For common Microsoft Office files, see Office Open XML MIME types
Example {"mediaType":"text/csv"}
Field distribution → title
Cardinality (0,1)
Required No
Accepted Values String
Usage Notes This should be a useful title for the distribution. Acronyms should be avoided.
Example {"title":"listofvegetables.csv"}
Field identifier
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes This field allows third parties to maintain a consistent record for datasets even if title or URLs are updated. Agencies may integrate an existing system for maintaining unique identifiers. Each identifier must be unique across the agency’s catalog and remain fixed. It is highly recommended that a URI (preferably an HTTP URL) be used to provide a globally unique identifier. Identifier URLs should be designed and maintained to persist indefinitely regardless of whether the URL of the resource itself changes.
Example {"identifier":"http://dx.doi.org/10.7927/H4PZ56R2"}
Field isPartOf
Cardinality (0,1)
Required No
Accepted Values String
Usage Notes This field allows the grouping of multiple datasets into a “collection”. This field should be employed by the individual datasets that together make up a collection. The value for this field should match the identifier of the parent dataset.
Example {"isPartOf":"http://dx.doi.org/10.7927/H4PZ56R2"}
Field issued
Cardinality (0,1)
Required No
Accepted Values ISO 8601 Date
Usage Notes Dates should be ISO 8601 of least resolution. In other words, as much of YYYY-MM-DDThh:mm:ss.sTZD as is relevant to this dataset.
Example {"issued":"2001-01-15"}
Field keyword
Cardinality (1,n)
Required Yes, always
Accepted Values Array of strings
Usage Notes Surround each keyword with quotes. Separate keywords with commas. Avoid duplicate keywords in the same record.
Example {"keyword":["vegetables","veggies","greens","leafy","spinach","kale","nutrition"]}
Field landingPage
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes This field is not intended for an agency’s homepage (e.g. www.agency.gov), but rather if a dataset has a human-friendly hub or landing page that users can be directed to for all resources tied to the dataset.
Example {"landingPage":"http://www.agency.gov/vegetables"}
Field language
Cardinality (0,n)
Required No
Accepted Values Array of strings
Usage Notes This should adhere to the RFC 5646 standard. This language subtag lookup provides a good tool for checking and verifying language codes. A language tag is comprised of either one or two parts, the language subtag (such as en for English, sp for Spanish, wo for Wolof) and the regional subtag (such as US for United States, GB for Great Britain, MX for Mexico), separated by a hyphen. Regional subtags should only be provided when needed to distinguish a language tag from another one (such as American vs. British English).
Example {"language":["en-US"]} or if multiple languages, {"language":["es-MX","wo","nv","en-US"]}
Field license
Cardinality (0,1)
Required Yes, if applicable
Accepted Values String (URL)
Usage Notes See list of license-free declarations and licenses.
Example {"license":"http://creativecommons.org/publicdomain/zero/1.0/"}
Field modified
Cardinality (1,1)
Required Yes, always
Accepted Values ISO 8601 Date
Usage Notes Dates should be ISO 8601 of highest resolution. In other words, as much of YYYY-MM-DDThh:mm:ss.sTZD as is relevant to this dataset. If there is a need to reflect that the dataset is continually updated, ISO 8601 formatting can account for this with repeating intervals. For instance, R/P1D for daily, R/P2W for every two weeks, and R/PT5M for every five minutes.
+Example {"modified":"2012-01-15"} or {"modified":"R/P1D"}
Field primaryITInvestmentUII
Cardinality (0,1)
Required No
Accepted Values String
Usage Notes Use to link a given dataset with its related IT Unique Investment Identifier, which can often be found in Exhibit 53 documents.
Example {"primaryITInvestmentUII":"023-000000001"}
Field programCode
Cardinality (0,n)
Required Yes, for United States Federal Government Agencies
Accepted Values Array of strings
Usage Notes Provide an array of programs related to this data asset, from the Federal Program Inventory.
Example {"programCode":["015:001"]} or if multiple programs, {"programCode":["015:001","015:002"]}
Field publisher
Cardinality (1,1)
Required Yes, always
Accepted Values Object
Usage Notes This is a container for a publisher object which groups together the fields: name and subOrganization. The subOrganization field can also contain a publisher object which allows one to describe an organization’s hierarchy. Where greater specificity is desired, include as many levels of publisher as is useful, in ascending order, using the below format.
Example See below
"publisher": {
  "@type": "org:Organization",
  "name": "Widget Services",
  "subOrganizationOf": {
    "@type": "org:Organization",
    "name": "Office of Citizen Services and Innovative Technologies",
    "subOrganizationOf": {
      "@type": "org:Organization",
      "name": "General Services Administration",
      "subOrganizationOf": {
        "@type": "org:Organization",
        "name": "U.S. Government"
      }
    }
  }
}
Field publisher → @type
Cardinality (0,1)
Required No
Accepted Values String (IRI)
Usage Notes The metadata type as defined by JSON-LD data types. This should be org:Organization for each publisher
Example {"@type": "org:Organization"}
Field publisher → name
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes The plaintext name of the entity publishing this dataset.
Example {"name": "U.S. Department of Commerce"}
Field publisher → subOrganizationOf
Cardinality (0,1)
Required No
Accepted Values publisher object
Usage Notes A parent organizational entity described using the same publisher object fields.
Example "subOrganizationOf": {"name": "General Services Administration", "subOrganizationOf": {"name": "U.S. Government"}}
Field references
Cardinality (0,n)
Required No
Accepted Values Array of strings (URLs)
Usage Notes Enclose each URL within strings. Separate multiple URLs with a comma.
Example {"references":["http://www.agency.gov/legumes/legumes_data_documentation.html"]} or if multiple URLs, {"references":["http://www.agency.gov/legumes/legumes_data_documentation.html","http://www.agency.gov/fruits/fruit_data_documentation.html"]}
Field rights
Cardinality (0,1)
Required Yes, if accessLevel is “restricted public” or “non-public”
Accepted Values String
Usage Notes This may include information regarding access or restrictions based on privacy, security, or other policies. This should also serve as an explanation for the selected “accessLevel” including instructions for how to access a restricted file, if applicable, or explanation for why a “non-public” or “restricted public” data asset is not “public,” if applicable. If the dataset can be made available through a website indirectly, use accessURL for the URL that provides such access.
Example {"rights":"This dataset contains Personally Identifiable Information and could not be released for public access."}
Field spatial
Cardinality (0,1)
Required Yes, if the dataset is spatial
Accepted Values See Usage Notes
Usage Notes This field should contain one of the following types of content: (1) a bounding coordinate box for the dataset represented in latitude / longitude pairs where the coordinates are specified in decimal degrees and in the order of: minimum longitude, minimum latitude, maximum longitude, maximum latitude; (2) a latitude / longitude pair (in decimal degrees) representing a point where the dataset is relevant; (3) a geographic feature expressed in Geography Markup Language using the Simple Features Profile; or (4) a geographic feature from the GeoNames database.
Example {"spatial":"Lincoln, Nebraska"}
Field systemOfRecords
Cardinality (0,1)
Required No
Accepted Values String (URL)
Usage Notes This field should a URL to the System of Records Notice (SORN) that relates to the dataset, specifically from FederalRegister.gov.
Example {"systemOfRecords":"https://www.federalregister.gov/articles/2002/04/08/02-7376/privacy-act-of-1974-publication-in-full-of-all-notices-of-systems-of-records-including-several-new#p-361"}
Field temporal
Cardinality (0,1)
Required Yes, if applicable
Accepted Values ISO 8601 Date
Usage Notes This field should contain an interval of time defined by the start and end dates for which the dataset is applicable. Dates should be formatted as pairs of {start datetime/end datetime} in the ISO 8601 format. ISO 8601 specifies that datetimes can be formatted in a number of ways, including a simple four-digit year (eg. 2013) to a much more specific YYYY-MM-DDTHH:MM:SSZ, where the T specifies a seperator between the date and time and time is expressed in 24 hour notation in the UTC (Zulu) time zone. (e.g., 2011-02-14T12:00:00Z/2013-07-04T19:34:00Z). Use a solidus (“/”) to separate start and end times. If there is a need to define the start or end of applicability using a duration rather than a date, ISO 8601 formatting can account for this with duration based intervals. For instance, applicability starting in January 2010 and continuing for one month could be represented as 2010-01/P1M or 2010-01/2010-02. However, when possible, full dates are preferred for both start and end times.
Example {"temporal":"2000-01-15T00:45:00Z/2010-01-15T00:06:00Z"} or {"temporal":"2000-01-15T00:45:00Z/P1W"}
Field theme
Cardinality (0,n)
Required No
Accepted Values Array of strings
Usage Notes Separate multiple categories with a comma. Could include ISO Topic Categories.
Examples {"theme":["vegetables"]} or if multiple categories, {"theme":["vegetables","produce"]}
Field title
Cardinality (1,1)
Required Yes, always
Accepted Values String
Usage Notes Acronyms should be avoided.
Example {"title":"Types of Vegetables"}

Federal Government Fields

USG — Fields specific to the U.S. Federal Government have been denoted with the USG superscript. The Project Open Data schema has been developed as part of a U.S Federal Government open data policy. However, every attempt has been made to align the schema with existing international standards and to provide opportunities for re-use and interoperability with state and local government as well as non-profits, academic institutions, and businesses. There are however some fields that have been introduced specifically for use by the U.S. Federal Government and have special meaning in that context. These fields are: bureauCode, programCode, dataQuality, primaryITInvestmentUII, and systemOfRecords. Non-federal data publishers are encouraged to make use of this schema, but these fields should not be seen as required and may not be relevant for those entities.

Rationale for Metadata Nomenclature

We sought to be platform-independent and to align as much as possible with existing open standards.

To that end, our JSON key names are directly drawn from DCAT, with a few exceptions.

We added the accessLevel field to help easily sort datasets into our three existing categories: public, restricted public, and non-public. This field means an agency can run a basic filter against its enterprise data catalog to generate a public-facing list of datasets that are, or could one day be, made publicly available (or, in the case of restricted data, available under certain conditions). This field also makes it easy for anyone to generate a list of datasets that could be made available but have not yet been released by filtering accessLevel to public and accessURL to blank.

We added the rights field (formerly accessLevelComment) for data stewards to explain how to access restricted public datasets, and for agencies to have a place to record (even if only internally) the reason for not releasing a non-public dataset.

We added the systemOfRecords field for data stewards to optionally link to a relevant System of Records Notice URL. A System of Records is a group of any records under the control of any agency from which information is retrieved by the name of the individual or by some identifying number, symbol, or other identifier assigned to the individual.

We added the bureauCode field to ensure every dataset is connected in a standard way with an agency bureau.

We added the programCode field to ensure that when applicable, every dataset is connected in a standard way with an agency program office.

We added the dataQuality to indicate whether or not the data meets an agency’s Information Quality Guidelines.

Additional Information