Skip to content
This repository was archived by the owner on Jun 18, 2024. It is now read-only.

Commit d998980

Browse files
philipashlockphilipashlock
committed
Initial documentation for JSON-LD support re #388 
1 parent 58e0479 commit d998980

File tree

2 files changed

+97
-12
lines changed

2 files changed

+97
-12
lines changed

Diff for: ‎v1.1/schema.md

+97-12
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,16 @@ Links to downloadable examples of metadata files developed in this and other for
5656

5757
Catalog Fields
5858
-------------------------------------------------
59-
These fields describe the entire Public Data Listing catalog file. Optionally, publishers may also use the `describedBy` field to reference the default [JSON Schema](http://json-schema.org/) file used to define the schema (http://project-open-data.cio.gov/v1.1/schema/catalog.json) or they may refer to their own JSON Schema file where they have extended the schema. See the [Catalog section](#Catalog) under *Further Metadata Field Guidance* for more details.
59+
These fields describe the entire Public Data Listing catalog file. Publishers can also use the `describedBy` field to reference the default [JSON Schema](http://json-schema.org/) 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](http://www.w3.org/TR/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](#Catalog) under *Further Metadata Field Guidance* for more details.
6060

6161
{: .table .table-striped}
6262
Field | Label | Definition | Required
6363
-------------- | -------------- | --------------| --------------
64-
[conformsTo](#conformsTo) | Schema Version | A URI that identifies the version of the Project Open Data schema being used. | Always
65-
[describedBy](#describedBy) | Data Dictionary | URL for the [JSON Schema](http://json-schema.org/) file that defines the schema used | No
64+
[@context](#context) | Metadata Context | URL or JSON object for the [JSON-LD Context](http://www.w3.org/TR/json-ld/#the-context) that defines the schema used | No
65+
[@id](#id) | Metadata Catalog ID | IRI for the [JSON-LD Node Identifier](http://www.w3.org/TR/json-ld/#node-identifiers) of the Catalog. This should be the URL of the data.json file itself | No
66+
[@type](#type) | Metadata Type | IRI for the [JSON-LD data type](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Catalog` for the Catalog | No
67+
[conformsTo](#conformsTo) | Schema Version | URI that identifies the version of the Project Open Data schema being used. | Always
68+
[describedBy](#describedBy) | Data Dictionary | URL for the [JSON Schema](http://json-schema.org/) file that defines the schema used | No
6669
[dataset](#dataset) | Dataset | A container for the array of Dataset objects. See [Dataset Fields](#Dataset) below for details. | Always
6770

6871

@@ -73,6 +76,7 @@ See the *[Further Metadata Field Guidance](#further-metadata-field-guidance)* se
7376
{: .table .table-striped}
7477
Field | Label | Definition | Required
7578
-------------- | -------------- | -------------- | --------------
79+
[@type](#dataset-type) | Metadata Type | IRI for the [JSON-LD data type](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Dataset` for each Dataset | No
7680
[title](#title) | Title | Human-readable name of the asset. Should be in plain English and include sufficient detail to facilitate search and discovery. | Always
7781
[description](#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
7882
[keyword](#keyword) | Tags | Tags (or keywords) help users discover your dataset; please include terms that would be used by technical and non-technical users. | Always
@@ -110,6 +114,7 @@ Within a dataset, **distribution** is used to aggregate the metadata specific to
110114
{: .table .table-striped}
111115
Field | Label | Definition | Required
112116
-------------- | -------------- | -------------- | --------------
117+
[@type](#distribution-type) | Metadata Type | IRI for the [JSON-LD data type](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Distribution` for each Distribution | No
113118
[accessURL](#distribution-accessURL) | Access URL | URL providing indirect access to a dataset, for example via API or a graphical interface | If-Applicable
114119
[conformsTo](#distribution-conformsTo) | Data Standard | URI used to identify a standardized specification the distribution conforms to | No
115120
[describedBy](#distribution-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
@@ -123,7 +128,7 @@ Field | Label | Defini
123128

124129
Extending the Schema
125130
------------------------------------------
126-
"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. Agencies 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.
131+
"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](#catalog-fields).
127132

128133

129134
Further Metadata Field Guidance
@@ -140,21 +145,27 @@ Additional details for each field are provided here broken down into sections fo
140145

141146
{: .schema-fields}
142147
* Catalog
148+
* {: .field-optional}[@context](#context)
149+
* {: .field-optional}[@id](#id)
150+
* {: .field-optional}[@type](#type)
143151
* {: .field-required}[conformsTo](#conformsTo)
144152
* {: .field-optional}[describedBy](#describedBy)
145153
* {: .field-required}[dataset](#dataset)
154+
* {: .field-optional}[@type](#dataset-type)
146155
* {: .field-required}[accessLevel](#accessLevel)
147156
* {: .field-optional}[accrualPeriodicity](#accrualPeriodicity)
148157
* {: .field-required}[bureauCode](#bureauCode)
149158
* {: .field-optional}[conformsTo](#dataset-conformsTo)
150159
* {: .field-required}[contactPoint](#contactPoint)
160+
* {: .field-optional}[@type](#contactPoint-type)
151161
* {: .field-required}[fn](#contactPoint-fn)
152162
* {: .field-required}[hasEmail](#contactPoint-hasEmail)
153163
* {: .field-required-if-applicable}[dataQuality](#dataQuality)
154164
* {: .field-optional}[describedBy](#dataset-describedBy)
155165
* {: .field-optional}[describedByType](#dataset-describedByType)
156166
* {: .field-required}[description](#description)
157167
* {: .field-required-if-applicable}[distribution](#distribution)
168+
* {: .field-optional}[@type](#distribution-type)
158169
* {: .field-optional}[accessURL](#distribution-accessURL)
159170
* {: .field-optional}[conformsTo](#distribution-conformsTo)
160171
* {: .field-required-if-applicable}[downloadURL](#distribution-downloadURL)
@@ -175,6 +186,7 @@ Additional details for each field are provided here broken down into sections fo
175186
* {: .field-optional}[primaryITInvestmentUII](#primaryITInvestmentUII)
176187
* {: .field-required}[programCode](#programCode)
177188
* {: .field-required}[publisher](#publisher)
189+
* {: .field-optional}[@type](#publisher-type)
178190
* {: .field-required}[name](#publisher-name)
179191
* {: .field-optional}[subOrganizationOf](#publisher-subOrganizationOf)
180192
* {: .field-required-if-applicable}[rights](#rights)
@@ -188,6 +200,33 @@ Additional details for each field are provided here broken down into sections fo
188200
Catalog Fields {#Catalog}
189201
-------------------------------
190202

203+
{: .table .table-striped #context}
204+
**Field [#](#context){: .permalink}** | **@context**
205+
----- | -----
206+
**Cardinality** | (0,1)
207+
**Required** | No
208+
**Accepted Values** | String (URL)
209+
**Usage Notes** | The URL or JSON object for the [JSON-LD Context](http://www.w3.org/TR/json-ld/#the-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`
210+
**Example** | `{"@context": "http://project-open-data.cio.gov/v1.1/schema/catalog.jsonld"}`
211+
212+
{: .table .table-striped #id}
213+
**Field [#](#id){: .permalink}** | **@id**
214+
----- | -----
215+
**Cardinality** | (0,1)
216+
**Required** | No
217+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
218+
**Usage Notes** | A unique identifier for the Catalog as defined by [JSON-LD Node Identifiers](http://www.w3.org/TR/json-ld/#node-identifiers). This should be the URL of the data.json file itself
219+
**Example** | `{"@id": "https://www.agency.gov/data.json"}`
220+
221+
{: .table .table-striped #type}
222+
**Field [#](#type){: .permalink}** | **@type**
223+
----- | -----
224+
**Cardinality** | (0,1)
225+
**Required** | No
226+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
227+
**Usage Notes** | The metadata type as defined by [JSON-LD data types](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Catalog` for the Catalog
228+
**Example** | `{"@type": "dcat:Catalog"}`
229+
191230
{: .table .table-striped #conformsTo}
192231
**Field [#](#conformsTo){: .permalink}** | **conformsTo**
193232
----- | -----
@@ -219,6 +258,15 @@ Catalog Fields {#Catalog}
219258
Dataset Fields {#Dataset}
220259
-------------------------------
221260

261+
{: .table .table-striped #dataset-type}
262+
**Field [#](#dataset-type){: .permalink}** | **@type**
263+
----- | -----
264+
**Cardinality** | (0,1)
265+
**Required** | No
266+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
267+
**Usage Notes** | The metadata type as defined by [JSON-LD data types](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Dataset` for the Dataset
268+
**Example** | `{"@type": "dcat:Dataset"}`
269+
222270
{: .table .table-striped #accessLevel}
223271
**Field [#](#accessLevel){: .permalink}** | **accessLevel**
224272
----- | -----
@@ -267,11 +315,22 @@ Dataset Fields {#Dataset}
267315

268316
~~~
269317
"contactPoint": {
318+
"@type": "vcard:Contact",
270319
"fn": "Jane Doe",
271320
"hasEmail": "mailto:[email protected]"
272321
}
273322
~~~
274323

324+
325+
{: .table .table-striped .child-field #contactPoint-type}
326+
**Field [#](#contactPoint-type){: .permalink}** | **contactPoint → @type**
327+
----- | -----
328+
**Cardinality** | (0,1)
329+
**Required** | No
330+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
331+
**Usage Notes** | The metadata type as defined by [JSON-LD data types](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `vcard:Contact` for contactPoint
332+
**Example** | `{"@type": "vcard:Contact"}`
333+
275334
{: .table .table-striped .child-field #contactPoint-fn}
276335
**Field [#](#contactPoint-fn){: .permalink}** | **contactPoint → fn**
277336
----- | -----
@@ -338,13 +397,15 @@ Dataset Fields {#Dataset}
338397
~~~
339398
"distribution": [
340399
{
400+
"@type": "dcat:Distribution",
341401
"description": "Vegetable data as a CSV file",
342402
"downloadURL": "http://www.agency.gov/vegetables/listofvegetables.csv",
343403
"format": "CSV",
344404
"mediaType": "text/csv",
345405
"title": "listofvegetables.csv"
346406
},
347407
{
408+
"@type": "dcat:Distribution",
348409
"conformsTo": "http://www.agency.gov/vegetables-data-standard/",
349410
"describedBy": "http://www.agency.gov/vegetables/schema.xsd",
350411
"describedByType": "text/xml",
@@ -355,13 +416,15 @@ Dataset Fields {#Dataset}
355416
"title": "listofvegetables.xml"
356417
},
357418
{
419+
"@type": "dcat:Distribution",
358420
"description": "Vegetable data as a zipped CSV file with attached data dictionary",
359421
"downloadURL": "http://www.agency.gov/vegetables/vegetables-all.zip",
360422
"format": "Zipped CSV",
361423
"mediaType": "application/zip",
362424
"title": "vegetables-all.zip"
363425
},
364426
{
427+
"@type": "dcat:Distribution",
365428
"accessURL": "http://www.agency.gov/api/vegetables/",
366429
"description": "A fully queryable REST API with JSON and XML output",
367430
"format": "API",
@@ -370,6 +433,15 @@ Dataset Fields {#Dataset}
370433
]
371434
~~~
372435

436+
{: .table .table-striped .child-field #distribution-type}
437+
**Field [#](#distribution-type){: .permalink}** | **distribution → @type**
438+
----- | -----
439+
**Cardinality** | (0,1)
440+
**Required** | No
441+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
442+
**Usage Notes** | The metadata type as defined by [JSON-LD data types](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `dcat:Distribution` for each distribution
443+
**Example** | `{"@type": "dcat:Distribution"}`
444+
373445
{: .table .table-striped .child-field #distribution-accessURL}
374446
**Field [#](#distribution-accessURL){: .permalink}** | **distribution → accessURL**
375447
----- | -----
@@ -553,19 +625,32 @@ Dataset Fields {#Dataset}
553625

554626
~~~
555627
"publisher": {
556-
"name": "Widget Services",
628+
"@type": "org:Organization",
629+
"name": "Widget Services",
630+
"subOrganizationOf": {
631+
"@type": "org:Organization",
632+
"name": "Office of Citizen Services and Innovative Technologies",
557633
"subOrganizationOf": {
558-
"name": "Office of Citizen Services and Innovative Technologies",
559-
"subOrganizationOf": {
560-
"name": "General Services Administration",
561-
"subOrganizationOf": {
562-
"name": "U.S. Government"
563-
}
564-
}
634+
"@type": "org:Organization",
635+
"name": "General Services Administration",
636+
"subOrganizationOf": {
637+
"@type": "org:Organization",
638+
"name": "U.S. Government"
639+
}
565640
}
641+
}
566642
}
567643
~~~
568644

645+
{: .table .table-striped .child-field #publisher-type}
646+
**Field [#](#publisher-type){: .permalink}** | **publisher → @type**
647+
----- | -----
648+
**Cardinality** | (0,1)
649+
**Required** | No
650+
**Accepted Values** | String ([IRI](http://www.w3.org/TR/json-ld/#dfn-iri))
651+
**Usage Notes** | The metadata type as defined by [JSON-LD data types](http://www.w3.org/TR/json-ld/#specifying-the-type). This should be `org:Organization` for each publisher
652+
**Example** | `{"@type": "org:Organization"}`
653+
569654
{: .table .table-striped .child-field #publisher-name}
570655
**Field [#](#publisher-name){: .permalink}** | **publisher → name**
571656
----- | -----

Diff for: ‎v1.1/schema/data.jsonld renamed to ‎v1.1/schema/catalog.jsonld

File renamed without changes.

0 commit comments

Comments
 (0)