From 2414f698ab4825a8cb8a26581d6a7d6225f80e41 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 23 Feb 2024 16:28:03 +0000 Subject: [PATCH 01/19] Added `resources` heading --- content/docs/specifications/data-package.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index 000550a4..d15ba09f 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -138,6 +138,8 @@ Packaged data resources are described in the `resources` property of the package #### Required Properties +##### `resources` + The `resources` property is `REQUIRED`, with at least one resource. #### Recommended Properties From 13228d32c2424ed8fc69a99ddeca21ca070434b1 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 23 Feb 2024 17:22:18 +0000 Subject: [PATCH 02/19] Added $schema --- content/docs/specifications/data-package.md | 39 ++++++++++----------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index d15ba09f..59e456a9 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -146,6 +146,25 @@ The `resources` property is `REQUIRED`, with at least one resource. In addition to the required properties, the following properties `SHOULD` be included in every package descriptor: +##### `$schema` + +A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` be an URL with default value `https://datapackage.org/schemas/datapackage-1.0.json`. + +The `$schema` property is both used as a Data Package version identifier and the location of a JSON Schema file against which this Data Package `MUST` be valid. + +The `$schema` property `MUST`: + +- be exactly `https://datapackage.json/schemas/datapackage-X.Y.json` where `X` and `Y` are major and minor Data Package Standard versions OR +- ends with `/EXTENSION-datapackage-X.Y.json` where `EXTENSION` is a name of an extension limited to the `[a-z0-9]` characters subset, and `X` and `Y` are major and minor extension versions. + +For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`. + +If the `$schema` property indicates an extension, a data consumer `MUST` retrieve a Data Package version from the extension JSON Schema according the rules described in the [Extensions](../extensions) specification. + +:::note[Backward Compatibility] +If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. +::: + ##### `name` The name is a simple name or identifier to be used for this package in relation to any registry in which this package will be deposited. @@ -201,26 +220,6 @@ Here is an example: [semver]: http://semver.org [url-or-path]: /data-resource/#url-or-path -##### `profile` - -A string identifying the [profile][] of this descriptor as per the [profiles][profile] specification. - -[profile]: /profiles/ - -Examples: - -```javascript -{ - "profile": "tabular-data-package" -} -``` - -```javascript -{ - "profile": "http://example.com/my-profiles-json-schema.json" -} -``` - #### Optional Properties The following are commonly used properties that the package descriptor `MAY` contain: From 114933857968cd40e9e22796029956004d8f7fce Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 23 Feb 2024 18:15:07 +0000 Subject: [PATCH 03/19] Updated urls --- content/docs/specifications/data-package.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index 59e456a9..b45ce478 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -148,13 +148,13 @@ In addition to the required properties, the following properties `SHOULD` be inc ##### `$schema` -A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` be an URL with default value `https://datapackage.org/schemas/datapackage-1.0.json`. +A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` be an URL with default value `https://datapackage.org/profiles/datapackage-1.0.json`. -The `$schema` property is both used as a Data Package version identifier and the location of a JSON Schema file against which this Data Package `MUST` be valid. +The `$schema` property is both used as a Data Package version identifier and the location of a [JSON Schema file](../glossary/#metadata-profile) against which this Data Package `MUST` be valid. The `$schema` property `MUST`: -- be exactly `https://datapackage.json/schemas/datapackage-X.Y.json` where `X` and `Y` are major and minor Data Package Standard versions OR +- be exactly `https://datapackage.json/profiles/datapackage-X.Y.json` where `X` and `Y` are major and minor Data Package Standard versions OR - ends with `/EXTENSION-datapackage-X.Y.json` where `EXTENSION` is a name of an extension limited to the `[a-z0-9]` characters subset, and `X` and `Y` are major and minor extension versions. For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`. From ae3e62c8334ba765a09166c68152e7fd8c8a8488 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 08:51:44 +0100 Subject: [PATCH 04/19] Removed `package.profile` --- content/docs/specifications/data-package.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index 4b5554cb..eaa2a570 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -195,24 +195,6 @@ Here is an example: - `path`: A [URL or Path](../glossary/#url-or-path) string, that is a fully qualified HTTP address, or a relative POSIX path. - `title`: A human-readable title. -### `profile` - -A string identifying the profile of this descriptor as per the [profiles](https://specs.frictionlessdata.io/profiles/) specification. - -Examples: - -```json -{ - "profile": "tabular-data-package" -} -``` - -```json -{ - "profile": "http://example.com/my-profiles-json-schema.json" -} -``` - ### `title` A `string` providing a title or one sentence description for this package From 45fa44d34ce536f4161bca76eaec29789cec8e05 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 09:04:53 +0100 Subject: [PATCH 05/19] Updated $schema --- content/docs/specifications/data-package.md | 13 +------------ content/docs/specifications/extensions.md | 6 +++--- content/docs/specifications/glossary.md | 13 +++++++++++++ 3 files changed, 17 insertions(+), 15 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index eaa2a570..b6a30820 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -126,18 +126,7 @@ Packaged data resources are described in the `resources` property of the package ### `$schema` -A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` be an URL with default value `https://datapackage.org/profiles/datapackage-1.0.json`. - -The `$schema` property is both used as a Data Package version identifier and the location of a [JSON Schema file](../glossary/#metadata-profile) against which this Data Package `MUST` be valid. - -The `$schema` property `MUST`: - -- be exactly `https://datapackage.json/profiles/datapackage-X.Y.json` where `X` and `Y` are major and minor Data Package Standard versions OR -- ends with `/EXTENSION-datapackage-X.Y.json` where `EXTENSION` is a name of an extension limited to the `[a-z0-9]` characters subset, and `X` and `Y` are major and minor extension versions. - -For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`. - -If the `$schema` property indicates an extension, a data consumer `MUST` retrieve a Data Package version from the extension JSON Schema according the rules described in the [Extensions](../extensions) specification. +A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 6434a2c1..8a5635e1 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -12,6 +12,6 @@ sidebar: -:::caution -This section is under development -::: +For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`. + +If the `$schema` property indicates an extension, a data consumer `MUST` retrieve a Data Package version from the extension JSON Schema according the rules described in the [Extensions](../extensions) specification. diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index f8479900..6b91f3b8 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -19,6 +19,19 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S ## Definitions +### Profile + +A profile is a URL that `MUST`: + +- resolves to a valid JSON Schema descriptor +- be versioned and idempotent i.e. once published under some version it cannot be changed + +A profile is both used as a metadata version identifier and the location of a JSON Schema against which this metadata `MUST` be valid and `MUST` be validated. + +:::note[Implementation Note] +It is recommended to cache profiles using their URL as a unique key. +::: + ### URL or Path A `URL or Path` is a `string` with the following additional constraints: From 7c584a7968ab533c094ecbdc1346372b6edc6b1f Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 10:16:51 +0100 Subject: [PATCH 06/19] Started extensions --- content/docs/specifications/data-package.md | 2 +- content/docs/specifications/data-resource.md | 20 ++++----------- content/docs/specifications/extensions.md | 26 +++++++++++++++++--- content/docs/specifications/glossary.md | 2 +- content/docs/specifications/table-dialect.md | 4 +++ content/docs/specifications/table-schema.md | 6 ++++- 6 files changed, 38 insertions(+), 22 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index b6a30820..de183101 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -126,7 +126,7 @@ Packaged data resources are described in the `resources` property of the package ### `$schema` -A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. +A Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/data-resource.md b/content/docs/specifications/data-resource.md index 1bd2ba5c..0e08621d 100644 --- a/content/docs/specifications/data-resource.md +++ b/content/docs/specifications/data-resource.md @@ -161,23 +161,13 @@ Or inline CSV: Prior to release 1.0.0-beta.18 (Nov 17 2016) there was a `url` property distinct from `path`. In order to support backwards compatibility, implementors `MAY` want to automatically convert a `url` property to a `path` property and issue a warning. ::: -### `profile` +### `$schema` -A string identifying the profile of this descriptor as per the [profiles](https://specs.frictionlessdata.io/profiles/) specification. +A Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. -Examples: - -```json -{ - "profile": "tabular-data-resource" -} -``` - -```json -{ - "profile": "http://example.com/my-profiles-json-schema.json" -} -``` +:::note[Backward Compatibility] +If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. +::: ### `title` diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 8a5635e1..b0931d48 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -1,17 +1,35 @@ --- title: Extensions sidebar: - hidden: true order: 5 --- - +
AuthorsRufus Pollock, Paul Walsh, Evgeny Karev, Peter DesmetRufus Pollock, Paul Walsh, Adam Kariv, Evgeny Karev, Peter Desmet
-For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`. +Data Package Standard provides rich extensibility features for domain-specific needs. -If the `$schema` property indicates an extension, a data consumer `MUST` retrieve a Data Package version from the extension JSON Schema according the rules described in the [Extensions](../extensions) specification. +## Language + +The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`, `MAY`, and `OPTIONAL` in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + +## Introduction + +Data Package Standard provides a rich set of metadata and data features for general applications. At the same time, Data Package Standard at its core is domain-agnostic and does not provide any built-in features to describe metadata in specific knowledge areas such as biology or medicine. + +A domain-specific extension is the way to enrich Data Package's metadata to meet specific needs of a knowledge domain. For example, there are some prominent Data Package extensions: + +- [Camera Trap Data Package](https://camtrap-dp.tdwg.org/) +- [Fiscal Data Package](https://fiscal.datapackage.org) + +## Extension + +Data Package Standard has a simple yet powerful extension mechanism based on the [Profile](../glossary/#profile) concept. + +A custom profile can be provided as a `$schema` property in a descriptor for each of the core specifications: Data Package, Data Resource, Table Dialect, and Table Schema. Having a profile instructs implementation to validate a descriptor using JSON Schema rules from the profile. This system empowers rich metadata extensibility features that can be used in many domain-specific applications. + +Usually, diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index 6b91f3b8..a6af6dbd 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -26,7 +26,7 @@ A profile is a URL that `MUST`: - resolves to a valid JSON Schema descriptor - be versioned and idempotent i.e. once published under some version it cannot be changed -A profile is both used as a metadata version identifier and the location of a JSON Schema against which this metadata `MUST` be valid and `MUST` be validated. +A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. :::note[Implementation Note] It is recommended to cache profiles using their URL as a unique key. diff --git a/content/docs/specifications/table-dialect.md b/content/docs/specifications/table-dialect.md index e6bce3fb..949b65f8 100644 --- a/content/docs/specifications/table-dialect.md +++ b/content/docs/specifications/table-dialect.md @@ -68,6 +68,10 @@ id,name General properties are format-agnostic. Usually, there are useful for defining dialects for delimiter-based and spreadsheet-based formats like CSV or Excel. +#### `$schema` + +A Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. + #### `header` A Table Dialect descriptor `MAY` have the `header` property that `MUST` be boolean with default value `true`. This property indicates whether the file includes a header row. If `true` the first row in the file `MUST` be interpreted as a header row, not data. diff --git a/content/docs/specifications/table-schema.md b/content/docs/specifications/table-schema.md index 7f7de2b6..1ed2db0b 100644 --- a/content/docs/specifications/table-schema.md +++ b/content/docs/specifications/table-schema.md @@ -107,7 +107,11 @@ A Table Schema descriptor `MAY` contain these standard properties: A Table Schema descriptor `MUST` contain a property `fields`. `fields` `MUST` be an array where each entry in the array is a [field descriptor](#field) as defined below. -The way Table Schema `fields` are mapped onto the data source fields are defined by the `fieldsMatch` property. By default, the most strict approach is applied, i.e. fields in the data source `MUST` completely match the elements in the `fields` array, both in number and order. Using different options below, a data producer can relax requirements for the data source. +The way Table Schema `fields` are mapped onto the data source fields are defined by the `fieldsMatch` property. By default, the most strict approach is applied, i.e. fields in the data source `MUST` completely match the elements in the `fields` array, both in number and order. Using different options of the `fieldsMatch` property, a data producer can relax requirements for the data source. + +#### `$schema` + +A Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. #### `fieldsMatch` From 37652599ccd4d0b543cc3756bea5934dad4b1d70 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 11:51:51 +0100 Subject: [PATCH 07/19] Finished extensions --- content/docs/specifications/data-package.md | 2 +- content/docs/specifications/data-resource.md | 2 +- content/docs/specifications/extensions.md | 88 ++++++++++++++++++-- content/docs/specifications/glossary.md | 2 +- content/docs/specifications/table-dialect.md | 2 +- content/docs/specifications/table-schema.md | 2 +- 6 files changed, 88 insertions(+), 10 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index de183101..6d949f01 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -126,7 +126,7 @@ Packaged data resources are described in the `resources` property of the package ### `$schema` -A Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. +A Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/data-resource.md b/content/docs/specifications/data-resource.md index 0e08621d..0fac7726 100644 --- a/content/docs/specifications/data-resource.md +++ b/content/docs/specifications/data-resource.md @@ -163,7 +163,7 @@ Prior to release 1.0.0-beta.18 (Nov 17 2016) there was a `url` property distinct ### `$schema` -A Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. +A Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index b0931d48..b2329f0e 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -11,7 +11,7 @@ sidebar: -Data Package Standard provides rich extensibility features for domain-specific needs. +Data Package Standard extensibility features for domain-specific needs. ## Language @@ -19,7 +19,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S ## Introduction -Data Package Standard provides a rich set of metadata and data features for general applications. At the same time, Data Package Standard at its core is domain-agnostic and does not provide any built-in features to describe metadata in specific knowledge areas such as biology or medicine. +Data Package Standard provides a rich set of metadata and data features for general applications. At the same time, Data Package Standard at its core is domain-agnostic and does not provide any builtin means to describe metadata in specific knowledge areas such as biology or medicine. A domain-specific extension is the way to enrich Data Package's metadata to meet specific needs of a knowledge domain. For example, there are some prominent Data Package extensions: @@ -28,8 +28,86 @@ A domain-specific extension is the way to enrich Data Package's metadata to meet ## Extension -Data Package Standard has a simple yet powerful extension mechanism based on the [Profile](../glossary/#profile) concept. +Data Package Standard has a simple yet powerful extension mechanism based on the [Profile](../glossary/#profile) concept. An extension is, generally speaking, a project that provides one or more domain-specific profiles to the Data Package Standard specifications. -A custom profile can be provided as a `$schema` property in a descriptor for each of the core specifications: Data Package, Data Resource, Table Dialect, and Table Schema. Having a profile instructs implementation to validate a descriptor using JSON Schema rules from the profile. This system empowers rich metadata extensibility features that can be used in many domain-specific applications. +From user-perspective, a custom profile can be provided as a `$schema` property in a corresponding specification [Descriptor](../glossary/#descriptor). Having a profile instructs implementation to validate a descriptor using JSON Schema rules of the profile. -Usually, +Usually, Data Package is the specification that is extended. As a container format, it is the most natural target for metadata enrichment. At the same time, technically any of the core specifications can be extended. For example, if you build a Table Schema catalog, it is possible to extend a Table Schema specification using the same approach as described below. + +Note, that the Data Package Standard's extension system completely relies on JSON Schema without extending its builtin features in any way. It makes the system highly robust and provides rich tooling support such as [text editor validation](https://code.visualstudio.com/docs/languages/json#_mapping-in-the-json). + +Combining modern JSON Schema features with an ability to provide profiles to any of the core Data Package Standard specification descriptors, allows to achieve almost any of metadata enrichment goals including but not limited to: + +- introducing custom properties on any metadata level +- requiring a resource list to comply with an extension rules +- ensuring tabular data rules restricting it to a specific Table Schema +- modularity with combination of custom profiles on different metadata levels +- combining existent profiles as a part of a high-level extension + +## Example + +For example, we will create a Spatial Data Package that requires a `geopoint` marker to be provided for each resource consisting a Data Package and . + +### Profile + +First of all, we need to create a Data Package profile. Note that it includes a default data package profile as per the [specification requirement](../data-package/#schema): + +```json +{ + "$schema": "http://json-schema.org/draft/2020-12/schema", + "title": "Spatial Data Package Profile", + "type": "object", + "allOf": [ + { "$ref": "https://datapackage.org/profiles/2.0/datapackage.json" }, + { "$ref": "#/definitions/spatialMixin" } + ], + "definitions": { + "spatialMixin": { + "type": "object", + "properties": { + "resources": { + "type": "array", + "item": { + "type": "object", + "properties": { + "geopoint": { + "type": "object", + "properties": { + "lon": { "type": "number" }, + "lat": { "type": "number" }, + "additionalProperties": false + } + } + } + } + } + } + } + } +} +``` + +### Descriptor + +Consider that the profile above is published at `https://spatial.datapackage.org/profiles/1.0/datapackage.json`. In this case, a Data Package descriptor compatible to exemplar Spatial Data Package (v1) will look as below: + +```json +{ + "$schema": "https://spatial.datapackage.org/profiles/1.0/datapackage.json", + "title": "Spatial Data Package Descriptor", + "resources": [ + { + "name": "expedition-1", + "path": "expedition-1.csv", + "geopoint": { + "lon": 90, + "lat": 90 + } + } + ] +} +``` + +### Software + +On the software level, all the Data Package implementations, even though they are not aware of this extension, will now be validating any Spatial Data Package descriptors from above according to the introduced domain-specific rules. At the same time, we encourage extensions authors to build on top of Data Package implementations to support domain-specific properties on the programming models level as well. diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index a6af6dbd..312b7b32 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -23,7 +23,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S A profile is a URL that `MUST`: -- resolves to a valid JSON Schema descriptor +- resolves to a valid JSON Schema descriptor with version `2019-09` or `2020-12` - be versioned and idempotent i.e. once published under some version it cannot be changed A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. diff --git a/content/docs/specifications/table-dialect.md b/content/docs/specifications/table-dialect.md index 949b65f8..2c113233 100644 --- a/content/docs/specifications/table-dialect.md +++ b/content/docs/specifications/table-dialect.md @@ -70,7 +70,7 @@ General properties are format-agnostic. Usually, there are useful for defining d #### `$schema` -A Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. +A Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. #### `header` diff --git a/content/docs/specifications/table-schema.md b/content/docs/specifications/table-schema.md index 1ed2db0b..bfb8ef33 100644 --- a/content/docs/specifications/table-schema.md +++ b/content/docs/specifications/table-schema.md @@ -111,7 +111,7 @@ The way Table Schema `fields` are mapped onto the data source fields are defined #### `$schema` -A Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition and `MUST` include all the metadata constraints required by this specification. +A Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. #### `fieldsMatch` From f2fd6cb7e9090895e07cce1078b19c80586781cf Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 11:53:58 +0100 Subject: [PATCH 08/19] Updated wording --- content/docs/specifications/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index 312b7b32..d86586e2 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -23,7 +23,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S A profile is a URL that `MUST`: -- resolves to a valid JSON Schema descriptor with version `2019-09` or `2020-12` +- resolves to a valid JSON Schema descriptor under version `2019-09` or `2020-12` - be versioned and idempotent i.e. once published under some version it cannot be changed A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. From 8b8a724552311c13de5ed38065e6f85313baf117 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 12:02:03 +0100 Subject: [PATCH 09/19] Updated JSONSchema version --- content/docs/specifications/glossary.md | 2 +- profiles/data-package.json | 2 +- profiles/data-resource.json | 2 +- profiles/dictionary/profile.yaml | 7 ------- profiles/metadata-profile.json | 4 ---- profiles/table-dialect.json | 2 +- profiles/table-schema.json | 2 +- 7 files changed, 5 insertions(+), 16 deletions(-) delete mode 100644 profiles/dictionary/profile.yaml delete mode 100644 profiles/metadata-profile.json diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index d86586e2..d4ccb2c3 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -23,7 +23,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S A profile is a URL that `MUST`: -- resolves to a valid JSON Schema descriptor under version `2019-09` or `2020-12` +- resolves to a valid JSON Schema descriptor under the `draft-07` version - be versioned and idempotent i.e. once published under some version it cannot be changed A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. diff --git a/profiles/data-package.json b/profiles/data-package.json index b03f1a88..0db1c069 100644 --- a/profiles/data-package.json +++ b/profiles/data-package.json @@ -1,4 +1,4 @@ { - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$ref": "build/profiles/dictionary.json#/definitions/dataPackage" } diff --git a/profiles/data-resource.json b/profiles/data-resource.json index 871fde4f..8d5c7b2d 100644 --- a/profiles/data-resource.json +++ b/profiles/data-resource.json @@ -1,4 +1,4 @@ { - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$ref": "build/profiles/dictionary.json#/definitions/dataResource" } diff --git a/profiles/dictionary/profile.yaml b/profiles/dictionary/profile.yaml deleted file mode 100644 index 4da2e117..00000000 --- a/profiles/dictionary/profile.yaml +++ /dev/null @@ -1,7 +0,0 @@ -metadataProfile: - title: Metadata Profile - description: Metadata Profile - type: object - properties: - title: - type: string diff --git a/profiles/metadata-profile.json b/profiles/metadata-profile.json deleted file mode 100644 index b394a16c..00000000 --- a/profiles/metadata-profile.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-04/schema#", - "$ref": "build/profiles/dictionary.json#/definitions/metadataProfile" -} diff --git a/profiles/table-dialect.json b/profiles/table-dialect.json index 2f72f42c..c6308f66 100644 --- a/profiles/table-dialect.json +++ b/profiles/table-dialect.json @@ -1,4 +1,4 @@ { - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$ref": "build/profiles/dictionary.json#/definitions/tableDialect" } diff --git a/profiles/table-schema.json b/profiles/table-schema.json index 9cb00389..bced7c5c 100644 --- a/profiles/table-schema.json +++ b/profiles/table-schema.json @@ -1,4 +1,4 @@ { - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "$ref": "build/profiles/dictionary.json#/definitions/tableSchema" } From de87b03f3f9b6c21c798f142235f9751b4a51f28 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 12:08:46 +0100 Subject: [PATCH 10/19] Added extensions note --- content/docs/specifications/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index d4ccb2c3..78750ac2 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -26,7 +26,7 @@ A profile is a URL that `MUST`: - resolves to a valid JSON Schema descriptor under the `draft-07` version - be versioned and idempotent i.e. once published under some version it cannot be changed -A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. +A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. Profiles is the mechanism for creating Data Package Standard [Extensions](../extensions). :::note[Implementation Note] It is recommended to cache profiles using their URL as a unique key. From 15ae3e5ceeef8adcdb4b8128b3aed08bc744608f Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 14:53:00 +0100 Subject: [PATCH 11/19] Fixed recursivity --- content/docs/specifications/data-package.md | 2 +- content/docs/specifications/data-resource.md | 2 +- content/docs/specifications/extensions.md | 4 ++-- content/docs/specifications/glossary.md | 6 +++++- content/docs/specifications/table-dialect.md | 2 +- content/docs/specifications/table-schema.md | 2 +- 6 files changed, 11 insertions(+), 7 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index 6d949f01..acd18637 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -126,7 +126,7 @@ Packaged data resources are described in the `resources` property of the package ### `$schema` -A Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0./datapackage.json`. +A root level Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/datapackage.json` and the recommended value is `https://datapackage.org/profiles/2.0/datapackage.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/data-resource.md b/content/docs/specifications/data-resource.md index 0fac7726..cc1b52a4 100644 --- a/content/docs/specifications/data-resource.md +++ b/content/docs/specifications/data-resource.md @@ -163,7 +163,7 @@ Prior to release 1.0.0-beta.18 (Nov 17 2016) there was a `url` property distinct ### `$schema` -A Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. +A root level Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/dataresource.json` and the recommended value is `https://datapackage.org/profiles/2.0/dataresource.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index b2329f0e..9dc03e7f 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -34,15 +34,15 @@ From user-perspective, a custom profile can be provided as a `$schema` property Usually, Data Package is the specification that is extended. As a container format, it is the most natural target for metadata enrichment. At the same time, technically any of the core specifications can be extended. For example, if you build a Table Schema catalog, it is possible to extend a Table Schema specification using the same approach as described below. -Note, that the Data Package Standard's extension system completely relies on JSON Schema without extending its builtin features in any way. It makes the system highly robust and provides rich tooling support such as [text editor validation](https://code.visualstudio.com/docs/languages/json#_mapping-in-the-json). +Note, that the Data Package Standard's extension system completely relies on the JSON Schema Standard without extending its builtin features in any way. It makes the system robust and provides rich tooling support such as [text editor validation](https://code.visualstudio.com/docs/languages/json#_mapping-in-the-json). Combining modern JSON Schema features with an ability to provide profiles to any of the core Data Package Standard specification descriptors, allows to achieve almost any of metadata enrichment goals including but not limited to: - introducing custom properties on any metadata level - requiring a resource list to comply with an extension rules - ensuring tabular data rules restricting it to a specific Table Schema -- modularity with combination of custom profiles on different metadata levels - combining existent profiles as a part of a high-level extension +- creating domain-specific dialect and schema catalogues ## Example diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index 78750ac2..3e6011f2 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -26,7 +26,11 @@ A profile is a URL that `MUST`: - resolves to a valid JSON Schema descriptor under the `draft-07` version - be versioned and idempotent i.e. once published under some version it cannot be changed -A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a `$schema` property `MUST` be valid and `MUST` be validated. Profiles is the mechanism for creating Data Package Standard [Extensions](../extensions). +A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a root level `$schema` property `MUST` be valid and `MUST` be validated. + +Similarly to [JSON Schema](https://json-schema.org/understanding-json-schema/reference/schema#schema), the `$schema` property has effect only on the root level of a descriptor. For example, if a Table Dialect is published as a file it can include a `$schema` property that affects its validation. If the same dialect is an object inlined into a Data Package descriptor, the dialect's `$schema` property `MUST` be ignored and the descriptor as whole `MUST` be validated against a root level `$schema` property provided by the package. + +Data Package Standard employes profiles as a mechanism for creating extensions as per [Extensions](../extensions) specification. :::note[Implementation Note] It is recommended to cache profiles using their URL as a unique key. diff --git a/content/docs/specifications/table-dialect.md b/content/docs/specifications/table-dialect.md index 2c113233..8918302c 100644 --- a/content/docs/specifications/table-dialect.md +++ b/content/docs/specifications/table-dialect.md @@ -70,7 +70,7 @@ General properties are format-agnostic. Usually, there are useful for defining d #### `$schema` -A Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. +A root level Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/tabledialect.json` and the recommended value is `https://datapackage.org/profiles/2.0/tabledialect.json`. #### `header` diff --git a/content/docs/specifications/table-schema.md b/content/docs/specifications/table-schema.md index bfb8ef33..15976cd1 100644 --- a/content/docs/specifications/table-schema.md +++ b/content/docs/specifications/table-schema.md @@ -111,7 +111,7 @@ The way Table Schema `fields` are mapped onto the data source fields are defined #### `$schema` -A Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. +A root level Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/tableschema.json` and the recommended value is `https://datapackage.org/profiles/2.0/tableschema.json`. #### `fieldsMatch` From db589f82a3ea5f693c6586582efeae741d3dcf3b Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 14:58:04 +0100 Subject: [PATCH 12/19] Updated sections --- content/docs/specifications/data-package.md | 4 +++- content/docs/specifications/data-resource.md | 4 +++- content/docs/specifications/table-dialect.md | 4 +++- content/docs/specifications/table-schema.md | 4 +++- 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/content/docs/specifications/data-package.md b/content/docs/specifications/data-package.md index acd18637..12491fc2 100644 --- a/content/docs/specifications/data-package.md +++ b/content/docs/specifications/data-package.md @@ -126,7 +126,9 @@ Packaged data resources are described in the `resources` property of the package ### `$schema` -A root level Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/datapackage.json` and the recommended value is `https://datapackage.org/profiles/2.0/datapackage.json`. +A root level Data Package descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. + +The default value is `https://datapackage.org/profiles/1.0/datapackage.json` and the recommended value is `https://datapackage.org/profiles/2.0/datapackage.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/data-resource.md b/content/docs/specifications/data-resource.md index cc1b52a4..b4a7dd0d 100644 --- a/content/docs/specifications/data-resource.md +++ b/content/docs/specifications/data-resource.md @@ -163,7 +163,9 @@ Prior to release 1.0.0-beta.18 (Nov 17 2016) there was a `url` property distinct ### `$schema` -A root level Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/dataresource.json` and the recommended value is `https://datapackage.org/profiles/2.0/dataresource.json`. +A root level Data Resource descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. + +The default value is `https://datapackage.org/profiles/1.0/dataresource.json` and the recommended value is `https://datapackage.org/profiles/2.0/dataresource.json`. :::note[Backward Compatibility] If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification. diff --git a/content/docs/specifications/table-dialect.md b/content/docs/specifications/table-dialect.md index 8918302c..97074686 100644 --- a/content/docs/specifications/table-dialect.md +++ b/content/docs/specifications/table-dialect.md @@ -70,7 +70,9 @@ General properties are format-agnostic. Usually, there are useful for defining d #### `$schema` -A root level Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/tabledialect.json` and the recommended value is `https://datapackage.org/profiles/2.0/tabledialect.json`. +A root level Table Dialect descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. + +The default value is `https://datapackage.org/profiles/1.0/tabledialect.json` and the recommended value is `https://datapackage.org/profiles/2.0/tabledialect.json`. #### `header` diff --git a/content/docs/specifications/table-schema.md b/content/docs/specifications/table-schema.md index 15976cd1..bd6d127f 100644 --- a/content/docs/specifications/table-schema.md +++ b/content/docs/specifications/table-schema.md @@ -111,7 +111,9 @@ The way Table Schema `fields` are mapped onto the data source fields are defined #### `$schema` -A root level Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. The default value is `https://datapackage.org/profiles/1.0/tableschema.json` and the recommended value is `https://datapackage.org/profiles/2.0/tableschema.json`. +A root level Table Schema descriptor `MAY` have a `$schema` property that `MUST` point to a profile as per [Profile](../glossary/#profile) definition that `MUST` include all the metadata constraints required by this specification. + +The default value is `https://datapackage.org/profiles/1.0/tableschema.json` and the recommended value is `https://datapackage.org/profiles/2.0/tableschema.json`. #### `fieldsMatch` From 91f70df24b2b928a1f1ea0d40d2a9ebde7a91229 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 15:03:04 +0100 Subject: [PATCH 13/19] Fixed extension example --- content/docs/specifications/extensions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 9dc03e7f..11ef9eea 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -69,6 +69,7 @@ First of all, we need to create a Data Package profile. Note that it includes a "type": "array", "item": { "type": "object", + "required": ["geopoint"], "properties": { "geopoint": { "type": "object", From 086683e29c621fcc97e6e9c27635694d074f3726 Mon Sep 17 00:00:00 2001 From: roll Date: Fri, 5 Apr 2024 15:08:21 +0100 Subject: [PATCH 14/19] Updated JSON Schema version --- content/docs/specifications/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 11ef9eea..4d23e799 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -54,7 +54,7 @@ First of all, we need to create a Data Package profile. Note that it includes a ```json { - "$schema": "http://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "title": "Spatial Data Package Profile", "type": "object", "allOf": [ From 144d52b5624b3572d19bc9b4e9761d0236af2a52 Mon Sep 17 00:00:00 2001 From: roll Date: Wed, 10 Apr 2024 09:31:27 +0100 Subject: [PATCH 15/19] Updated extensions features list --- content/docs/specifications/extensions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 4d23e799..c17d50c3 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -38,9 +38,10 @@ Note, that the Data Package Standard's extension system completely relies on the Combining modern JSON Schema features with an ability to provide profiles to any of the core Data Package Standard specification descriptors, allows to achieve almost any of metadata enrichment goals including but not limited to: -- introducing custom properties on any metadata level -- requiring a resource list to comply with an extension rules -- ensuring tabular data rules restricting it to a specific Table Schema +- adding new domain-specific properties +- requiring existing properties to comply with certain requirements +- defining what resources are expected +- requiring resources to meet certain dialect or schema requirements - combining existent profiles as a part of a high-level extension - creating domain-specific dialect and schema catalogues From 97969f8e7f39e0c10c4847d6b0488f61befd8b6c Mon Sep 17 00:00:00 2001 From: roll Date: Wed, 10 Apr 2024 09:32:59 +0100 Subject: [PATCH 16/19] Fixed unfinished sentence --- content/docs/specifications/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index c17d50c3..f6373c25 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -47,7 +47,7 @@ Combining modern JSON Schema features with an ability to provide profiles to any ## Example -For example, we will create a Spatial Data Package that requires a `geopoint` marker to be provided for each resource consisting a Data Package and . +For example, we will create a Spatial Data Package that requires a `geopoint` marker to be provided for each resource consisting a Data Package. ### Profile From 78516b66ca2b5b710e72aedc2a77284be469557e Mon Sep 17 00:00:00 2001 From: roll Date: Wed, 10 Apr 2024 09:34:10 +0100 Subject: [PATCH 17/19] Replace idempotent -> immutable --- content/docs/specifications/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/glossary.md b/content/docs/specifications/glossary.md index 3e6011f2..95ea0237 100644 --- a/content/docs/specifications/glossary.md +++ b/content/docs/specifications/glossary.md @@ -24,7 +24,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S A profile is a URL that `MUST`: - resolves to a valid JSON Schema descriptor under the `draft-07` version -- be versioned and idempotent i.e. once published under some version it cannot be changed +- be versioned and immutable i.e. once published under some version it cannot be changed A profile is both used as a metadata version identifier and the location of a JSON Schema against which a descriptor having it as a root level `$schema` property `MUST` be valid and `MUST` be validated. From 8daa0c872404eaca8cbcfc9ab3880181120905d4 Mon Sep 17 00:00:00 2001 From: roll Date: Wed, 10 Apr 2024 09:42:17 +0100 Subject: [PATCH 18/19] Update content/docs/specifications/extensions.md Co-authored-by: Peter Desmet --- content/docs/specifications/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index f6373c25..7ddc7b13 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -112,4 +112,4 @@ Consider that the profile above is published at `https://spatial.datapackage.org ### Software -On the software level, all the Data Package implementations, even though they are not aware of this extension, will now be validating any Spatial Data Package descriptors from above according to the introduced domain-specific rules. At the same time, we encourage extensions authors to build on top of Data Package implementations to support domain-specific properties on the programming models level as well. +Even though they are not aware of the extension, any Data Package software implementation will be validating a Spatial Data Package out of the box: both the domain-specific properties as well as the general Data Package properties. We do encourage extensions authors however to build on top of existing software to support domain-specific properties on the programming models level as well. From 1488b718fc2762004dab993779da23b7a2b09211 Mon Sep 17 00:00:00 2001 From: roll Date: Wed, 10 Apr 2024 10:33:30 +0100 Subject: [PATCH 19/19] Improved grammar --- content/docs/specifications/extensions.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/docs/specifications/extensions.md b/content/docs/specifications/extensions.md index 7ddc7b13..b2fdfdb0 100644 --- a/content/docs/specifications/extensions.md +++ b/content/docs/specifications/extensions.md @@ -11,7 +11,7 @@ sidebar: -Data Package Standard extensibility features for domain-specific needs. +The Data Package Standard extensibility features for domain-specific needs. ## Language @@ -19,7 +19,7 @@ The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `S ## Introduction -Data Package Standard provides a rich set of metadata and data features for general applications. At the same time, Data Package Standard at its core is domain-agnostic and does not provide any builtin means to describe metadata in specific knowledge areas such as biology or medicine. +The Data Package Standard provides a rich set of metadata and data features for general applications. At the same time, the Data Package Standard at its core is domain-agnostic and does not provide any builtin means to describe metadata in specific knowledge areas such as biology or medicine. A domain-specific extension is the way to enrich Data Package's metadata to meet specific needs of a knowledge domain. For example, there are some prominent Data Package extensions: @@ -28,7 +28,7 @@ A domain-specific extension is the way to enrich Data Package's metadata to meet ## Extension -Data Package Standard has a simple yet powerful extension mechanism based on the [Profile](../glossary/#profile) concept. An extension is, generally speaking, a project that provides one or more domain-specific profiles to the Data Package Standard specifications. +The Data Package Standard has a simple yet powerful extension mechanism based on the [Profile](../glossary/#profile) concept. An extension is, generally speaking, a project that provides one or more domain-specific profiles to the Data Package Standard specifications. From user-perspective, a custom profile can be provided as a `$schema` property in a corresponding specification [Descriptor](../glossary/#descriptor). Having a profile instructs implementation to validate a descriptor using JSON Schema rules of the profile. @@ -38,12 +38,12 @@ Note, that the Data Package Standard's extension system completely relies on the Combining modern JSON Schema features with an ability to provide profiles to any of the core Data Package Standard specification descriptors, allows to achieve almost any of metadata enrichment goals including but not limited to: -- adding new domain-specific properties -- requiring existing properties to comply with certain requirements -- defining what resources are expected -- requiring resources to meet certain dialect or schema requirements -- combining existent profiles as a part of a high-level extension -- creating domain-specific dialect and schema catalogues +- Adding new domain-specific properties. +- Requiring existing properties to comply with certain requirements. +- Defining what resources are expected. +- Requiring resources to meet certain dialect or schema requirements. +- Combining existent profiles as a part of a high-level extension. +- Creating domain-specific dialect and schema catalogues. ## Example