diff --git a/catalog.md b/catalog.md index b87946b2..a3fb0562 100644 --- a/catalog.md +++ b/catalog.md @@ -26,18 +26,18 @@ Each agency will describe their existing datasets as they see fit using the belo Machine-Readable Format ----------------------- -All information deemed "machine-readable" required in this policy must be described in the JSON file format, with the option of RDFa Lite and XML as well. See [this specification](/schema/) for the required schema. Agencies must post their files at agency.gov/data.json (and optionally at /data.html or data.xml as well). Additionally, the web page which reads and formats these files must be posted at /data/index.html (or data.html). The files should be updated a minimum of monthly. It is our intent that future publications of Data.gov will simply crawl for all agency.gov/data.json to populate Data.gov. +All information deemed "machine-readable" required in this policy must be described in the JSON file format, with the option of RDFa Lite and XML as well. See [this specification](/schema/) for the required schema. Agencies must post their files at agency.gov/data.json (and optionally at /data.html or data.xml as well). Additionally, the web page which reads and formats these files must be posted at /data/index.html (or /data.html). The files should be updated a minimum of monthly. It is our intent that future publications of Data.gov will simply crawl for all agency.gov/data.json to populate Data.gov. Implementing ------------ -To fulfill the requirements of this memorandum, agencies should begin to describe datasets as a catalog using the vocabulary of the [common core metadata](/schema/). This catalog is to be published in two places. First, as a standalone JSON file at `agency.gov/data.json` and second with RDFa Lite, either embedded within a HTML page which include human readable markups (e.g., `agency.gov/data.html`) or as an XML file (e.g., `agency.gov/data.xml`). +To fulfill the requirements of this memorandum, agencies should begin to describe datasets as a catalog using the vocabulary of the [common core metadata](/schema/). This catalog is to be published as a standalone JSON file at `agency.gov/data.json`. Agencies may optionally also publish it with RDFa Lite, either embedded within a HTML page which include human readable markups (e.g., `agency.gov/data.html`) or as an XML file (e.g., `agency.gov/data.xml`). ### JSON JSON is a lightweight and simple way to represent machine-readable data. It is quickly becoming the *de facto* standard for shuttling data across the internet, fueled primarily by the rise of mobile and APIs. Modern programming languages can interpret and produce JSON out of the box. -The JSON representation of the catalog should track directly to the RDFa version, with the exception that JSON keys should not contain the domain prefix (e.g., `dcterms:title` becomes `title` and `dcterms:description` becomes simply `description`). Catalogs should be composed of an array of JSON objects, and all fields other than keywords should be a string (where keywords is an array of strings). +The JSON representation of the catalog should track directly with any other optional formats, with the exception that JSON keys should not contain the domain prefix (e.g., `dcterms:title` becomes `title` and `dcterms:description` becomes simply `description`). Catalogs should be composed of an array of JSON objects, and all fields other than keywords should be a string (where keywords is an array of strings). ### RDFa Lite diff --git a/faq.md b/faq.md index c925884f..b8302215 100644 --- a/faq.md +++ b/faq.md @@ -140,7 +140,7 @@ In the near term, Data.gov will continue its current dataset publishing process. ### Are redirects allowed for /data pages? -No, the files should be located at agency.gov/data web space. Each agency should populate files named agency.gov/data.json, agency.gov/data.html and agency.gov/data.xml. +No, the file should be located at the agency.gov/data web space. Each agency should publish their Public Data Listing at agency.gov/data.json. ### What options exist for hosting the /data.json file specifically at agency.gov/data.json? @@ -158,9 +158,9 @@ Data.gov will (when possible) help agencies get started by creating a /data file A wide variety of tools are available to manage a data catalog, whether public-facing or for internal data managements. The records of metadata in the file can be managed by databases, spreadsheets, or even text editors. Data management systems should be able to export the metadata either in the desired format or in one which may be simply mapped with [tools](http://labs.data.gov). -### What formats are required/recommended for the agency.gov/data file? +### What formats are required/optional for the agency.gov/data file? -There are several syntaxes that may be used when publishing the data file. The syntax that is required to make the data readily available to developers is JSON (JavaScript Object Notation). It is recommended that agencies also create a data.html file and use RDFa Lite (Resource Description Framework) to mark-up the metadata using the [common core metadata schema](/schema/). The RDFa Lite file can be easily consumed by major search engines and applications and make you data easier to find by the public. A third alternative for populating your metadata file is XML (eXtensible Markup Language). Agencies are encouraged to maintain all three version of the metadata file. [Tools](http://labs.data.gov) are available to transform any instance of the file into the alternative formats. +JSON is required though there are several optional syntaxes that can also be used when publishing the data file. The syntax that is required to make the data readily available to developers is JSON (JavaScript Object Notation). Agencies should also create a data.html file for the human-browsable data homepage and may use RDFa Lite (Resource Description Framework) to mark-up each dataset's metadata using the [common core metadata schema](/schema/). Agencies may also choose to populate a metadata file using XML (eXtensible Markup Language). These alternate metadata files are optional but agencies must maintain the JSON version at agency.gov/data.json. [Tools](http://labs.data.gov) are available to transform any instance of the file into the alternative formats. ## Agency participation with Open Data diff --git a/metadata-resources.md b/metadata-resources.md index e7f52414..72d13c2d 100644 --- a/metadata-resources.md +++ b/metadata-resources.md @@ -64,9 +64,9 @@ E) Manual translating a data file from another system Agencies may also manage their data catalogs through various database solutions such as Access, an asset management system, document management system, geoportal, or assorted proprietary systems. Regardless of which system an agency employs, it should include a fundamental export option which allows the catalog to be exported as a CSV file, which can then be imported into the [Catalog Generator](http://project-open-data.github.com/catalog-generator/) for conversation to an appropriately formatted JSON file. Depending on the solutions' varied further functionality, some of them may also provide APIs which can then be configured to maintain the data.json file. If not, they may instead support XML and JSON exports, which can then be converted to the proper format. -F) Convert from CSV or JSON to XML or RDFa lite. +F) Convert from CSV to JSON. -In order to generate appropriately formatted XML or RDFa Lite files, simply import an appropriately formatted CSV or JSON file into the [Catalog Generator](http://project-open-data.github.com/catalog-generator/), ensure that the metadata fields line up, and re-export the file. +In order to generate appropriately formatted JSON, simply import an appropriately formatted CSV into the [Catalog Generator](http://project-open-data.github.com/catalog-generator/), ensure that the metadata fields line up, and re-export the file.