Promote "Metadata in Table Schema" recipe to the specs. #961
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -189,7 +189,7 @@ In contrast with `field.constraints.unique`, `uniqueKeys` allows to define uniqu | |||||
|
|
||||||
| #### `foreignKeys` {#foreignKeys} | ||||||
|
|
||||||
| A foreign key is a reference where values in a field (or fields) on the table ('resource' in Data Package terminology) described by this Table Schema connect to values a field (or fields) on this or a separate table (resource). They are directly modelled on the concept of foreign keys in SQL. | ||||||
|
|
||||||
| The `foreignKeys` property, if present, `MUST` be an Array. Each entry in the array `MUST` be a `foreignKey`. A `foreignKey` `MUST` be a `object` and `MUST` have the following properties: | ||||||
|
|
||||||
|
|
@@ -198,7 +198,7 @@ The `foreignKeys` property, if present, `MUST` be an Array. Each entry in the ar | |||||
| key. The structure of the array is as per `primaryKey` above. | ||||||
| - `reference` - `reference` `MUST` be a `object`. The `object` | ||||||
| - `MUST` have a property `fields` which is an array of strings of the same length as the outer `fields`, describing the field (or fields) references on the destination resource. The structure of the array is as per `primaryKey` above. | ||||||
| - `MAY` have a property `resource` which is the name of the resource within the current Data Package, i.e. the Data Package within which this Table Schema is located. For referencing another Data Resource the `resource` property `MUST` be provided. For self-referencing, i.e. references between fields in this Table Schema, the `resource` property `MUST` be omitted. | ||||||
|
|
||||||
| Here's an example: | ||||||
|
|
||||||
|
|
@@ -266,6 +266,44 @@ If the value of the `foreignKey.reference.resource` property is an empty string | |||||
| Data consumer MUST support the `foreignKey.fields` and `foreignKey.reference.fields` properties in a form of a single string e.g. `"fields": "a"` which was a part of the `v1.0` of the specification. | ||||||
| ::: | ||||||
|
|
||||||
| #### `name` | ||||||
|
|
||||||
| A simple name or identifier for the schema (cf. [Data Package](https://datapackage.org/standard/data-package/#name)). | ||||||
|
|
||||||
| #### `title` | ||||||
|
|
||||||
| A string providing a title or one sentence description for the schema. | ||||||
|
|
||||||
| #### `description` | ||||||
|
|
||||||
| A description of the schema (cf. [Data Package](https://datapackage.org/standard/data-package/#description)). | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| #### `homepage` | ||||||
|
|
||||||
| A URL for the home on the web that is related to the schema. | ||||||
|
|
||||||
| #### `keywords` | ||||||
|
|
||||||
| An array of string keywords to assist users searching for the schema in catalogs. | ||||||
|
There was a problem hiding this comment. @pierrecamilleri would you argue this inherits from Data Package or not? If so, please change to:
Suggested change
|
||||||
|
|
||||||
| #### `examples` | ||||||
|
|
||||||
| A list of Data Resources that use and illustrate the schema. | ||||||
|
|
||||||
| If present, it `MUST` be a non-empty array of objects. Each object is a [Data Resource](https://datapackage.org/standard/data-resource/) that `MUST` at least have the `name` and `path` property. The `path` must be a URL. | ||||||
|
|
||||||
| #### `created` | ||||||
|
|
||||||
| The datetime on which the schema was created (cf. [Data Package](https://datapackage.org/standard/data-package/#created)). | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. I think this could inherit from Data Package. Would add:
|
||||||
|
|
||||||
| #### `version` | ||||||
|
|
||||||
| A version string identifying the version of the schema (cf. [Data Package](https://datapackage.org/standard/data-package/#version)). If not specified, the schema inherits from the Data Package if distributed in a Data Package descriptor. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| #### `contributors` | ||||||
|
|
||||||
| The people or organizations that contributed to the schema (cf. [Data Package](https://datapackage.org/standard/data-package/#contributors)). If not specified the schema inherits from the Data Package if distributed in a Data Package descriptor. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Field | ||||||
|
|
||||||
| A field descriptor `MUST` be a JSON `object` that describes a single field. The descriptor provides additional human-readable documentation for a field, as well as additional information that can be used to validate the field or create a user interface for data entry. | ||||||
|
|
||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -81,6 +81,24 @@ tableSchema: | |
| } | ||
| missingValues: | ||
| "$ref": "#/definitions/tableSchemaMissingValues" | ||
| name: | ||
| "$ref": "#/definitions/name" | ||
| title: | ||
| "$ref": "#/definitions/title" | ||
| description: | ||
| "$ref": "#/definitions/description" | ||
| homepage: | ||
| "$ref": "#/definitions/homepage" | ||
| keywords: | ||
| "$ref": "#/definitions/keywords" | ||
| examples: | ||
| "$ref": "#/definitions/tableSchemaExamples" | ||
| created: | ||
| "$ref": "#/definitions/created" | ||
| version: | ||
| "$ref": "#/definitions/version" | ||
| contributors: | ||
|
There was a problem hiding this comment. Four properties from Data Package are not carried over to Schema. I'm fine with waiting for use cases, but wanted to know your opinion on these @pierrecamilleri:
|
||
| "$ref": "#/definitions/contributors" | ||
| examples: | ||
| - | | ||
| { | ||
|
|
@@ -263,6 +281,33 @@ tableSchemaMissingValues: | |
| { | ||
| "missingValues": [] | ||
| } | ||
| tableSchemaExamples: | ||
| title: Examples | ||
| description: A list of Data Resources that use and illustrate the schema. | ||
| type: array | ||
| minItems: 0 | ||
| items: | ||
| "$ref": "#/definitions/tableSchemaExample" | ||
| examples: | ||
| - | | ||
| { | ||
| "examples": [ | ||
| { | ||
| "name": "valid-data", | ||
| "path": "http://example.com/valid-data.csv" | ||
| } | ||
| ] | ||
| } | ||
| tableSchemaExample: | ||
| title: Example | ||
| description: A Data Resource that uses and illustrates the schema. | ||
| type: object | ||
| properties: | ||
| name: | ||
| "$ref": "#/definitions/name" | ||
| path: | ||
| "$ref": "#/definitions/path" | ||
| required: ["name", "path"] | ||
| tableSchemaFieldString: | ||
| type: object | ||
| title: String Field | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -57,7 +57,7 @@ | |||||
| "homepage": { | ||||||
| "propertyOrder": 60, | ||||||
| "title": "Home Page", | ||||||
| "description": "The home on the web that is related to this resource.", | ||||||
|
There was a problem hiding this comment. Two notes:
There was a problem hiding this comment. I am not familiar with the build process, in particular what is the difference between "build/profiles" and "profiles/target" ? When I run the "build.js", with "VERSION=2.1-draft", it does not create (or for the matter, populate) a There was a problem hiding this comment. @peterdesmet |
||||||
| "type": "string", | ||||||
| "format": "uri", | ||||||
| "examples": [ | ||||||
|
|
@@ -153,7 +153,7 @@ | |||||
| "keywords": { | ||||||
| "propertyOrder": 90, | ||||||
| "title": "Keywords", | ||||||
| "description": "A list of keywords that describe this descriptor.", | ||||||
| "type": "array", | ||||||
| "minItems": 1, | ||||||
| "items": { | ||||||
|
|
@@ -348,7 +348,7 @@ | |||||
| "homepage": { | ||||||
| "propertyOrder": 70, | ||||||
| "title": "Home Page", | ||||||
| "description": "The home on the web that is related to this resource.", | ||||||
|
There was a problem hiding this comment.
Suggested change
@roll If these files are rebuild, it should say |
||||||
| "type": "string", | ||||||
| "format": "uri", | ||||||
| "examples": [ | ||||||
|
|
@@ -3093,6 +3093,174 @@ | |||||
| "{\n \"missingValues\": [\n \"-\",\n \"NaN\",\n \"\"\n ]\n}\n", | ||||||
| "{\n \"missingValues\": []\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "name": { | ||||||
| "title": "Name", | ||||||
| "description": "An identifier string.", | ||||||
| "type": "string", | ||||||
| "context": "This is ideally a url-usable and human-readable name. Name `SHOULD` be invariant, meaning it `SHOULD NOT` change when its parent descriptor is updated.", | ||||||
| "examples": [ | ||||||
| "{\n \"name\": \"my-nice-name\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "title": { | ||||||
| "title": "Title", | ||||||
| "description": "A human-readable title.", | ||||||
| "type": "string", | ||||||
| "examples": [ | ||||||
| "{\n \"title\": \"My Package Title\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "description": { | ||||||
| "title": "Description", | ||||||
| "description": "A text description. Markdown is encouraged.", | ||||||
| "type": "string", | ||||||
| "examples": [ | ||||||
| "{\n \"description\": \"# My Package description\\nAll about my package.\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "homepage": { | ||||||
| "title": "Home Page", | ||||||
| "description": "The home on the web that is related to this resource.", | ||||||
| "type": "string", | ||||||
| "format": "uri", | ||||||
| "examples": [ | ||||||
| "{\n \"homepage\": \"http://example.com/\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "keywords": { | ||||||
| "title": "Keywords", | ||||||
| "description": "A list of keywords that describe this descriptor.", | ||||||
| "type": "array", | ||||||
| "minItems": 1, | ||||||
| "items": { | ||||||
| "type": "string" | ||||||
| }, | ||||||
| "examples": [ | ||||||
| "{\n \"keywords\": [\n \"data\",\n \"fiscal\",\n \"transparency\"\n ]\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "examples": { | ||||||
| "title": "Examples", | ||||||
| "description": "Links to example data files", | ||||||
| "type": "array", | ||||||
| "minItems": 0, | ||||||
| "items": { | ||||||
| "title": "Example", | ||||||
| "description": "Link to an example data file", | ||||||
| "type": "object", | ||||||
| "properties": { | ||||||
| "title": { | ||||||
| "title": "Title", | ||||||
| "description": "A human-readable title.", | ||||||
| "type": "string", | ||||||
| "examples": [ | ||||||
| "{\n \"title\": \"My Package Title\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "path": { | ||||||
| "title": "Path", | ||||||
| "description": "A fully qualified URL, or a POSIX file path.", | ||||||
| "type": "string", | ||||||
| "pattern": "^((?=[^./~])(?!file:)((?!\\/\\.\\.\\/)(?!\\\\)(?!:\\/\\/).)*|(http|ftp)s?:\\/\\/.*)$", | ||||||
| "examples": [ | ||||||
| "{\n \"path\": \"file.csv\"\n}\n", | ||||||
| "{\n \"path\": \"http://example.com/file.csv\"\n}\n" | ||||||
| ], | ||||||
| "context": "Implementations need to negotiate the type of path provided, and dereference the data accordingly." | ||||||
| } | ||||||
| }, | ||||||
| "required": [ | ||||||
| "title", | ||||||
| "path" | ||||||
| ] | ||||||
| }, | ||||||
| "examples": [ | ||||||
| "{\n \"examples\": [\n {\n \"title\": \"Valid data\",\n \"path\": \"http://example.com/valid-data.csv\"\n }\n ]\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "created": { | ||||||
| "title": "Created", | ||||||
| "description": "The datetime on which this descriptor was created.", | ||||||
| "context": "The datetime must conform to the string formats for datetime as described in [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6)", | ||||||
| "type": "string", | ||||||
| "format": "date-time", | ||||||
| "examples": [ | ||||||
| "{\n \"created\": \"1985-04-12T23:20:50.52Z\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "version": { | ||||||
| "title": "Version", | ||||||
| "description": "A unique version number for this descriptor.", | ||||||
| "type": "string", | ||||||
| "examples": [ | ||||||
| "{\n \"version\": \"0.0.1\"\n}\n", | ||||||
| "{\n \"version\": \"1.0.1-beta\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "contributors": { | ||||||
| "title": "Contributors", | ||||||
| "description": "The contributors to this descriptor.", | ||||||
| "type": "array", | ||||||
| "minItems": 1, | ||||||
| "items": { | ||||||
| "title": "Contributor", | ||||||
| "description": "A contributor to this descriptor.", | ||||||
| "properties": { | ||||||
| "title": { | ||||||
| "title": "Title", | ||||||
| "description": "A human-readable title.", | ||||||
| "type": "string", | ||||||
| "examples": [ | ||||||
| "{\n \"title\": \"My Package Title\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "path": { | ||||||
| "title": "Path", | ||||||
| "description": "A fully qualified URL, or a POSIX file path.", | ||||||
| "type": "string", | ||||||
| "pattern": "^((?=[^./~])(?!file:)((?!\\/\\.\\.\\/)(?!\\\\)(?!:\\/\\/).)*|(http|ftp)s?:\\/\\/.*)$", | ||||||
| "examples": [ | ||||||
| "{\n \"path\": \"file.csv\"\n}\n", | ||||||
| "{\n \"path\": \"http://example.com/file.csv\"\n}\n" | ||||||
| ], | ||||||
| "context": "Implementations need to negotiate the type of path provided, and dereference the data accordingly." | ||||||
| }, | ||||||
| "email": { | ||||||
| "title": "Email", | ||||||
| "description": "An email address.", | ||||||
| "type": "string", | ||||||
| "format": "email", | ||||||
| "examples": [ | ||||||
| "{\n \"email\": \"example@example.com\"\n}\n" | ||||||
| ] | ||||||
| }, | ||||||
| "givenName": { | ||||||
| "type": "string" | ||||||
| }, | ||||||
| "familyName": { | ||||||
| "type": "string" | ||||||
| }, | ||||||
| "organization": { | ||||||
| "title": "Organization", | ||||||
| "description": "An organizational affiliation for this contributor.", | ||||||
| "type": "string" | ||||||
| }, | ||||||
| "roles": { | ||||||
| "type": "array", | ||||||
| "minItems": 1, | ||||||
| "items": { | ||||||
| "type": "string" | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "minProperties": 1, | ||||||
| "context": "Use of this property does not imply that the person was the original creator of, or a contributor to, the data in the descriptor, but refers to the composition of the descriptor itself." | ||||||
| }, | ||||||
| "examples": [ | ||||||
| "{\n \"contributors\": [\n {\n \"title\": \"Joe Bloggs\"\n }\n ]\n}\n", | ||||||
| "{\n \"contributors\": [\n {\n \"title\": \"Joe Bloggs\",\n \"email\": \"joe@example.com\",\n \"role\": \"author\"\n }\n ]\n}\n" | ||||||
| ] | ||||||
| } | ||||||
| }, | ||||||
| "examples": [ | ||||||
|
|
||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.