Promote "Metadata in Table Schema" recipe to the specs. (#961)

Co-authored-by: Peter Desmet <[email protected]> Co-authored-by: Peter Desmet <[email protected]> Co-authored-by: Pieter Huybrechts <[email protected]>
frictionlessdata · Jan 27, 2025 · 3bd8961 · 3bd8961
1 parent e1cae21
commit 3bd8961
Show file tree

Hide file tree

Showing 9 changed files with 637 additions and 11 deletions.
diff --git a/content/docs/overview/changelog.md b/content/docs/overview/changelog.md
@@ -12,6 +12,42 @@ This document includes all meaningful changes made to the **Data Package standar
 
 [fieldsMatch](/standard/table-schema/#fieldsMatch) has been corrected from array to string to match its definition ([#965](https://github.com/frictionlessdata/datapackage/issues/965)).
 
+##### `schema.name` (new)
+
+[`name`](/standard/table-schema/#name) allows to specify a name for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.title` (new)
+
+[`title`](/standard/table-schema/#title) allows to specify a title for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.description` (new)
+
+[`description`](/standard/table-schema/#description) allows to specify a description for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.homepage` (new)
+
+[`homepage`](/standard/table-schema/#homepage) allows to specify a homepage for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.version` (new)
+
+[`version`](/standard/table-schema/#version) allows to specify a version for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.created` (new)
+
+[`created`](/standard/table-schema/#created) allows to specify when a schema was created ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.keywords` (new)
+
+[`keywords`](/standard/table-schema/#keywords) allows to specify keywords for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.contributors` (new)
+
+[`contributors`](/standard/table-schema/#contributors) allows to specify contributors for a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
+##### `schema.examples` (new)
+
+[`examples`](/standard/table-schema/#examples) allows to specify a list of illustrative data resources that use a schema ([#961](https://github.com/frictionlessdata/datapackage/pull/961)).
+
 ## v2.0
 
 This release includes a rich set of specification improvements to make Data Package a finished product (see [announcement](https://frictionlessdata.io/blog/2023/11/15/frictionless-specs-update/)). All changes were reviewed and accepted by the Data Package Working Group.

diff --git a/content/docs/standard/data-package.mdx b/content/docs/standard/data-package.mdx
@@ -229,7 +229,7 @@ An Array of string keywords to assist users searching for the package in catalog
 
 ### `contributors`
 
-The people or organizations who contributed to this Data Package. It `MUST` be an array. Each entry is a Contributor and `MUST` be an `object`. A Contributor `MUST` have at least one property. A Contributor is `RECOMMENDED` to have `title` property and `MAY` contain `givenName`, `familyName`, `path`, `email`, `roles`, and `organization` properties:
+The people or organizations that contributed to this Data Package. It `MUST` be an array. Each entry is a Contributor and `MUST` be an `object`. A Contributor `MUST` have at least one property. A Contributor is `RECOMMENDED` to have `title` property and `MAY` contain `givenName`, `familyName`, `path`, `email`, `roles`, and `organization` properties:
 
 - `title`: A string containing a name of the contributor.
 - `givenName`: A string containing the name a person has been given, if the contributor is a person.

diff --git a/content/docs/standard/table-schema.mdx b/content/docs/standard/table-schema.mdx
@@ -202,14 +202,14 @@ 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.
+A foreign key is a reference where values in a field (or fields) of the table ('resource' in Data Package terminology) described by this Table Schema connect to values a field (or fields) of this or a separate table (resource). This concept is 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:
 
 - `fields` - `fields` is an array of strings specifying the field or fields on this resource that form the source part of the foreign 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.
+  - `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:
 
@@ -277,6 +277,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)).
+
+#### `homepage`
+
+A URL for the web page associated with the schema.
+
+#### `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.
+
+#### `created`
+
+The datetime on which the schema was created (cf. [Data Package](https://datapackage.org/standard/data-package/#created)).
+
+#### `keywords`
+
+An array of string keywords to assist users searching for the schema in catalogs.
+
+#### `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.
+
+#### `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.
+
 ### 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.

diff --git a/package-lock.json b/package-lock.json
diff --git a/profiles/dictionary/common.yaml b/profiles/dictionary/common.yaml
@@ -72,7 +72,7 @@ example:
       }
 homepage:
   title: Home Page
-  description: The home on the web that is related to this data package.
+  description: The home on the web that is related to this descriptor.
   type: string
   format: uri
   examples:
@@ -149,7 +149,7 @@ created:
       }
 keywords:
   title: Keywords
-  description: A list of keywords that describe this package.
+  description: A list of keywords that describe this descriptor.
   type: array
   minItems: 1
   items:

diff --git a/profiles/dictionary/schema.yaml b/profiles/dictionary/schema.yaml
@@ -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"
+    created:
+      "$ref": "#/definitions/created"
+    version:
+      "$ref": "#/definitions/version"
+    keywords:
+      "$ref": "#/definitions/keywords"
+    contributors:
+      "$ref": "#/definitions/contributors"
+    examples:
+      "$ref": "#/definitions/tableSchemaExamples"
   examples:
     - |
       {
@@ -262,6 +280,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