Promote "Metadata in Table Schema" recipe to the specs.

content/docs/overview/changelog.md

@@ -6,6 +6,44 @@ sidebar:
 
 This document includes all meaningful changes made to the **Data Package standard**. It does not cover changes made to other documents like Recipes or Guides.
 
+## v2.1-draft
+
+##### `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
 
 > June 26, 2024

content/docs/standard/data-package.md

@@ -219,7 +219,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.

content/docs/standard/table-schema.md

@@ -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.
+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.
+  - `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)).
+
+#### `homepage`
+
+A URL for the home on the web that is related to 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.

profiles/source/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:

profiles/source/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:
     - |
       {
@@ -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

profiles/target/2.0/datapackage.json

@@ -57,7 +57,7 @@
     "homepage": {
       "propertyOrder": 60,
       "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 resource.",
       "type": "string",
       "format": "uri",
       "examples": [
@@ -153,7 +153,7 @@
     "keywords": {
       "propertyOrder": 90,
       "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": {
@@ -348,7 +348,7 @@
           "homepage": {
             "propertyOrder": 70,
             "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 resource.",
             "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\": \"[email protected]\"\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\": \"[email protected]\",\n      \"role\": \"author\"\n    }\n  ]\n}\n"
+                ]
               }
             },
             "examples": [