diff --git a/jsonschema/definitions/Dataset.json b/jsonschema/definitions/Dataset.json index 8804948..f95accf 100644 --- a/jsonschema/definitions/Dataset.json +++ b/jsonschema/definitions/Dataset.json @@ -541,16 +541,7 @@ "identifier": { "title": "identifier", "description": "The unique identifier for the Dataset, e.g. the URI or other unique identifier in the context of the Catalog", - "anyOf": [ - { - "type": "null", - "title": "Null allowed when not required" - }, - { - "$ref": "/dcat-us/3.0.0/definitions/identifier", - "description": "inline description of Identifier" - } - ], + "$ref": "/dcat-us/3.0.0/definitions/identifier", "_oldDocs": { "uri": "dcterms:identifier", "range": "rdfs:Literal" diff --git a/jsonschema/docs/catalog.md b/jsonschema/docs/catalog.md index 49182e7..f75cf30 100644 --- a/jsonschema/docs/catalog.md +++ b/jsonschema/docs/catalog.md @@ -98,7 +98,7 @@ A curated collection of metadata about datasets, data services, or other resourc | [conformsTo](#conformsTo) | null or [Standard](./quality-governance.md#standard) | Recommended | Standard, schema, profile, or model that this catalog follows | | [homepage](#homepage) | null or [Document](./quality-governance.md#document) | Recommended | Main public web page for the catalog, usually an HTML page | | [issued](#issued) | null or object | Recommended | Date when the catalog was formally issued, such as its initial publication date | -| [language](#language) | More than one type | Recommended | Language codes used for catalog metadata text (such as titles and descriptions), using ISO 639-1 codes like en or es | +| [language](#language) | single Language code or array of Language codes | Recommended | Language codes used for catalog metadata text (such as titles and descriptions), using ISO 639-1 codes like en or es | | [modified](#modified) | null or object | Recommended | Most recent date when the catalog content changed, not just catalog-record metadata | | [rights](#rights) | null or array of string | Recommended | Rights statements about the catalog that are not already covered by license or accessRights, such as copyright or policy restrictions | | [spatial](#spatial) | null or array of [Location](./temporal-spatial-metrics.md#location) classes | Recommended | Geographic area covered by the catalog | @@ -191,7 +191,7 @@ Date when the catalog was formally issued, such as its initial publication date Language codes used for catalog metadata text (such as titles and descriptions), using ISO 639-1 codes like en or es -- **Type**: `combining` +- **Type**: single Language code or array of Language codes - **Additional properties**: Any type allowed **Examples:** diff --git a/jsonschema/docs/constraints-and-restrictions.md b/jsonschema/docs/constraints-and-restrictions.md index 9e54b81..81981fc 100644 --- a/jsonschema/docs/constraints-and-restrictions.md +++ b/jsonschema/docs/constraints-and-restrictions.md @@ -22,13 +22,13 @@ Rules or indicators that describe who can access a resource } ``` -| Property | Type | Requirement Level | Title/Description | -| -------------------------------------------- | ------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [restrictionStatus](#access-restriction--restrictionStatus) | object | Mandatory | The indication of whether or not there are access restrictions on the item, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/access-restriction-status | -| [specificRestriction](#access-restriction--specificRestriction) | null or [Concept](./identifiers-and-relationships.md#concept) | Recommended | Authority, code list entry, or policy reference that defines the specific access restriction; consider using a controlled vocabulary such as the NARA https://www.archives.gov/research/catalog/lcdrg/authority-lists/specific-access-restriction | -| [@id](#access-restriction--@id) | string | Optional | | -| [@type](#access-restriction--@type) | string | Optional | | -| [restrictionNote](#access-restriction--restrictionNote) | null or string | Optional | A note related to the access restriction | +| Property | Type | Requirement Level | Title/Description | +| -------------------------------------------- | ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [restrictionStatus](#access-restriction--restrictionStatus) | string or [Concept](./identifiers-and-relationships.md#concept) object | Mandatory | The indication of whether or not there are access restrictions on the item, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/access-restriction-status | +| [specificRestriction](#access-restriction--specificRestriction) | null or [Concept](./identifiers-and-relationships.md#concept) | Recommended | Authority, code list entry, or policy reference that defines the specific access restriction; consider using a controlled vocabulary such as the NARA https://www.archives.gov/research/catalog/lcdrg/authority-lists/specific-access-restriction | +| [@id](#access-restriction--@id) | string | Optional | | +| [@type](#access-restriction--@type) | string | Optional | | +| [restrictionNote](#access-restriction--restrictionNote) | null or string | Optional | A note related to the access restriction | ## `AccessRestriction > restrictionStatus` [#](#access-restriction--restrictionStatus) @@ -36,7 +36,7 @@ Rules or indicators that describe who can access a resource The indication of whether or not there are access restrictions on the item, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/access-restriction-status -- **Type**: `combining` +- **Type**: string or [Concept](./identifiers-and-relationships.md#concept) object - **Required**: Yes - **Additional properties**: Any type allowed - **Defined in**: [Concept](./identifiers-and-relationships.md#concept) @@ -232,13 +232,13 @@ Rules or legal limits on how a resource may be used } ``` -| Property | Type | Requirement Level | Title/Description | -| -------------------------------------------- | ------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [restrictionStatus](#use-restriction--restrictionStatus) | object | Mandatory | Indication of whether or not there are use restrictions on the archival materials, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/use-restriction-status | -| [specificRestriction](#use-restriction--specificRestriction) | null or [Concept](./identifiers-and-relationships.md#concept) | Recommended | Authority, code list entry, or policy reference that defines the specific use restriction; consider using a controlled vocabulary such as the NARA https://www.archives.gov/research/catalog/lcdrg/authority-lists/specific-use-restriction | -| [@id](#use-restriction--@id) | string | Optional | | -| [@type](#use-restriction--@type) | string | Optional | | -| [restrictionNote](#use-restriction--restrictionNote) | null or string | Optional | Significant information pertaining to the use or reproduction of the data | +| Property | Type | Requirement Level | Title/Description | +| -------------------------------------------- | ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [restrictionStatus](#use-restriction--restrictionStatus) | string or [Concept](./identifiers-and-relationships.md#concept) object | Mandatory | Indication of whether or not there are use restrictions on the archival materials, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/use-restriction-status | +| [specificRestriction](#use-restriction--specificRestriction) | null or [Concept](./identifiers-and-relationships.md#concept) | Recommended | Authority, code list entry, or policy reference that defines the specific use restriction; consider using a controlled vocabulary such as the NARA https://www.archives.gov/research/catalog/lcdrg/authority-lists/specific-use-restriction | +| [@id](#use-restriction--@id) | string | Optional | | +| [@type](#use-restriction--@type) | string | Optional | | +| [restrictionNote](#use-restriction--restrictionNote) | null or string | Optional | Significant information pertaining to the use or reproduction of the data | ## `UseRestriction > restrictionStatus` [#](#use-restriction--restrictionStatus) @@ -246,7 +246,7 @@ Rules or legal limits on how a resource may be used Indication of whether or not there are use restrictions on the archival materials, consider using a controlled vocabulary such as https://www.archives.gov/research/catalog/lcdrg/authority-lists/use-restriction-status -- **Type**: `combining` +- **Type**: string or [Concept](./identifiers-and-relationships.md#concept) object - **Required**: Yes - **Additional properties**: Any type allowed - **Defined in**: [Concept](./identifiers-and-relationships.md#concept) diff --git a/jsonschema/docs/dataset.md b/jsonschema/docs/dataset.md index 0bc0228..8cee28f 100644 --- a/jsonschema/docs/dataset.md +++ b/jsonschema/docs/dataset.md @@ -96,70 +96,70 @@ A collection of data published or curated by one provider } ``` -| Property | Type | Requirement Level | Title/Description | -| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [contactPoint](#contactPoint) | More than one type | Mandatory | A contact point for questions about the Dataset (single contact or list). Include an email address that is continuously monitored | -| [description](#description) | string | Mandatory | Plain-language summary of the dataset | -| [identifier](#identifier) | null or [Identifier](./identifiers-and-relationships.md#identifier) | Mandatory | The unique identifier for the Dataset, e.g. the URI or other unique identifier in the context of the Catalog | -| [title](#title) | string | Mandatory | Human-readable title of the dataset | -| [accessRestriction](#accessRestriction) | null or array of [AccessRestriction](./constraints-and-restrictions.md#access-restriction) classes | Recommended | List of access restrictions related to the dataset | -| [cuiRestriction](#cuiRestriction) | null or [CUIRestriction](./constraints-and-restrictions.md#cui-restriction) | Recommended | Controlled Unclassified Information restriction related to the dataset | -| [describedBy](#describedBy) | null or [Distribution](./distribution.md#root) | Recommended | A distribution describing the Data Dictionary for this dataset | -| [distribution](#distribution) | null or array of [Distribution](./distribution.md#root) classes | Recommended | List of available distributions for the dataset. This can be omitted when no distribution is available yet. | -| [inventoried](#inventoried) | null or object | Recommended | Date on which the dataset was added to the catalog. This may differ from the publication/release date. | -| [keyword](#keyword) | null or array of string | Recommended | List of keywords or tags describing the dataset | -| [landingPage](#landingPage) | null or [Document](./quality-governance.md#document) | Recommended | A web page from the original data provider that gives access to the Dataset, its Distributions, and related information | -| [license](#license) | null or string | Recommended | License that governs how the dataset can be used or reused | -| [modified](#modified) | null or object | Recommended | Most recent date when the dataset's actual data changed, not just metadata | -| [publisher](#publisher) | null or [Organization](./agents.md#organization) | Recommended | Organization responsible for publishing and making the dataset available | -| [rights](#rights) | null or array of string | Recommended | Rights statements not already covered by license or accessRights, such as copyright or policy restrictions | -| [spatial](#spatial) | More than one type | Recommended | A geographic region or regions that are covered by the Dataset | -| [temporal](#temporal) | null or array of [PeriodOfTime](./temporal-spatial-metrics.md#period-of-time) classes | Recommended | Time periods covered by the dataset | -| [theme](#theme) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Recommended | List of themes or categories for the dataset | -| [useRestriction](#useRestriction) | null or array of [UseRestriction](./constraints-and-restrictions.md#use-restriction) classes | Recommended | List of use restrictions related to the dataset | -| [@id](#@id) | string | Optional | | -| [@type](#@type) | string | Optional | | -| [accessRights](#accessRights) | null or string | Optional | Information about whether the dataset is publicly accessible, restricted, or not public | -| [accrualPeriodicity](#accrualPeriodicity) | More than one type | Optional | The frequency at which the Dataset is updated | -| [category](#category) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Optional | List of high-level categories for the dataset | -| [conformsTo](#conformsTo) | null or array of [Standard](./quality-governance.md#standard) classes | Optional | List of standards, schemas, or profiles the dataset follows | -| [contributor](#contributor) | null or array of [Agent](./agents.md#agent) classes | Optional | List of agents contributing to the Dataset | -| [created](#created) | null or object | Optional | The date on which the Dataset was first created | -| [creator](#creator) | null or [Agent](./agents.md#agent) | Optional | Person or organization responsible for creating the dataset | -| [first](#first) | null or [Dataset](./dataset.md#root) | Optional | the first item of the sequence the dataset belongs to | -| [hasCurrentVersion](#hasCurrentVersion) | null or [Dataset](./dataset.md#root) | Optional | reference to the current (latest) version of a dataset | -| [hasPart](#hasPart) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related datasets that are part of the described dataset | -| [hasQualityMeasurement](#hasQualityMeasurement) | null or array of [QualityMeasurement](./temporal-spatial-metrics.md#quality-measurement) classes | Optional | List of quality measurements for the dataset (for example, completeness, accuracy, or timeliness) beyond spatial or temporal resolution | -| [hasVersion](#hasVersion) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related Datasets that are a version, edition, or adaptation of the described Dataset | -| [image](#image) | null or string | Optional | Thumbnail image illustrating the dataset, especially useful for visual data such as maps, photos, or video | -| [isReferencedBy](#isReferencedBy) | null or array of string | Optional | List of links to related resources, such as publications, that reference, cite, or otherwise point to the Dataset | -| [issued](#issued) | null or object | Optional | Date when the dataset was first published. If the exact publication date is unknown, use the date it was first referenced in the catalog. | -| [language](#language) | More than one type | Optional | ISO 639-1 language code values used in the dataset text or metadata, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | -| [liabilityStatement](#liabilityStatement) | null or string | Optional | A liability statement about the dataset that may clarify limitations of responsibility, qualifications on the accuracy, reliability, and completeness of the data, or absence of endorsement by the data publisher or provider, among other considerations | -| [metadataDistribution](#metadataDistribution) | null or array of [Distribution](./distribution.md#root) classes | Optional | Distribution of the original metadata document this dataset was derived from | -| [otherIdentifier](#otherIdentifier) | null or array of [Identifier](./identifiers-and-relationships.md#identifier) classes | Optional | Additional identifiers for the dataset besides the main identifier, such as a DOI or other persistent ID | -| [page](#page) | null or array of [Document](./quality-governance.md#document) classes | Optional | List of pages or documents about this dataset | -| [previousVersion](#previousVersion) | null or [Dataset](./dataset.md#root) | Optional | reference to the previous dataset version | -| [provenance](#provenance) | null or array of string | Optional | List of statements about the lineage of a Dataset, including any changes in its ownership or custody since its creation that may be significant for its authenticity, integrity, or interpretation | -| [purpose](#purpose) | null or string | Optional | The purpose of the dataset | -| [qualifiedAttribution](#qualifiedAttribution) | null or array of [Attribution](./quality-governance.md#attribution) classes | Optional | List of agents with specific responsibilities for the dataset | -| [qualifiedRelation](#qualifiedRelation) | null or array of [Relationship](./identifiers-and-relationships.md#relationship) classes | Optional | Detailed relationship between the dataset and another resource, including the role of that relationship | -| [relation](#relation) | null or array of string | Optional | List of links to related resources when the relationship is not otherwise specified | -| [replaces](#replaces) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of Datasets replaced by this Dataset | -| [rightsHolder](#rightsHolder) | null or array of [Organization](./agents.md#organization) classes | Optional | List of agents (organizations) holding rights on the Dataset | -| [sample](#sample) | null or array of [Distribution](./distribution.md#root) classes | Optional | List of sample distributions for the dataset | -| [scopeNote](#scopeNote) | null or string | Optional | usage note for the dataset | -| [source](#source) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related Datasets from which the described Dataset is derived | -| [spatialResolutionInMeters](#spatialResolutionInMeters) | null or string | Optional | Smallest spatial distance between data points, in meters, represented as a single value | -| [status](#status) | null or [Concept](./identifiers-and-relationships.md#concept) | Optional | Lifecycle status of the dataset, such as completed, deprecated, under development, or withdrawn | -| [subject](#subject) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Optional | List of primary subjects for the dataset, usually narrower than broad theme categories | -| [supportedSchema](#supportedSchema) | null or [Dataset](./dataset.md#root) | Optional | supported schema for this dataset | -| [temporalResolution](#temporalResolution) | null or string | Optional | Smallest time interval between data points, using xsd:duration format (for example, P1D) | -| [version](#version) | null or string | Optional | The version indicator (name or identifier) of a resource | -| [versionNotes](#versionNotes) | null or string | Optional | Notes describing how this version differs from earlier versions of the dataset | -| [wasAttributedTo](#wasAttributedTo) | null or array of [Agent](./agents.md#agent) classes | Optional | List of agents attributed to this dataset | -| [wasGeneratedBy](#wasGeneratedBy) | null or array of [Activity](./temporal-spatial-metrics.md#activity) classes | Optional | List of activities that generated, or provide the business context for the creation of the dataset | -| [wasUsedBy](#wasUsedBy) | null or array of [Activity](./temporal-spatial-metrics.md#activity) classes | Optional | List of activities that used the Dataset | +| Property | Type | Requirement Level | Title/Description | +| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [contactPoint](#contactPoint) | single [Kind](./agents.md#kind) object or array of [Kind](./agents.md#kind) objects | Mandatory | A contact point for questions about the Dataset (single contact or list). Include an email address that is continuously monitored | +| [description](#description) | string | Mandatory | Plain-language summary of the dataset | +| [identifier](#identifier) | string or [Identifier](./identifiers-and-relationships.md#identifier) object | Mandatory | The unique identifier for the Dataset, e.g. the URI or other unique identifier in the context of the Catalog | +| [title](#title) | string | Mandatory | Human-readable title of the dataset | +| [accessRestriction](#accessRestriction) | null or array of [AccessRestriction](./constraints-and-restrictions.md#access-restriction) classes | Recommended | List of access restrictions related to the dataset | +| [cuiRestriction](#cuiRestriction) | null or [CUIRestriction](./constraints-and-restrictions.md#cui-restriction) | Recommended | Controlled Unclassified Information restriction related to the dataset | +| [describedBy](#describedBy) | null or [Distribution](./distribution.md#root) | Recommended | A distribution describing the Data Dictionary for this dataset | +| [distribution](#distribution) | null or array of [Distribution](./distribution.md#root) classes | Recommended | List of available distributions for the dataset. This can be omitted when no distribution is available yet. | +| [inventoried](#inventoried) | null or object | Recommended | Date on which the dataset was added to the catalog. This may differ from the publication/release date. | +| [keyword](#keyword) | null or array of string | Recommended | List of keywords or tags describing the dataset | +| [landingPage](#landingPage) | null or [Document](./quality-governance.md#document) | Recommended | A web page from the original data provider that gives access to the Dataset, its Distributions, and related information | +| [license](#license) | null or string | Recommended | License that governs how the dataset can be used or reused | +| [modified](#modified) | null or object | Recommended | Most recent date when the dataset's actual data changed, not just metadata | +| [publisher](#publisher) | null or [Organization](./agents.md#organization) | Recommended | Organization responsible for publishing and making the dataset available | +| [rights](#rights) | null or array of string | Recommended | Rights statements not already covered by license or accessRights, such as copyright or policy restrictions | +| [spatial](#spatial) | single [Location](./temporal-spatial-metrics.md#location) object or array of [Location](./temporal-spatial-metrics.md#location) objects | Recommended | A geographic region or regions that are covered by the Dataset | +| [temporal](#temporal) | null or array of [PeriodOfTime](./temporal-spatial-metrics.md#period-of-time) classes | Recommended | Time periods covered by the dataset | +| [theme](#theme) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Recommended | List of themes or categories for the dataset | +| [useRestriction](#useRestriction) | null or array of [UseRestriction](./constraints-and-restrictions.md#use-restriction) classes | Recommended | List of use restrictions related to the dataset | +| [@id](#@id) | string | Optional | | +| [@type](#@type) | string | Optional | | +| [accessRights](#accessRights) | null or string | Optional | Information about whether the dataset is publicly accessible, restricted, or not public | +| [accrualPeriodicity](#accrualPeriodicity) | More than one type | Optional | The frequency at which the Dataset is updated | +| [category](#category) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Optional | List of high-level categories for the dataset | +| [conformsTo](#conformsTo) | null or array of [Standard](./quality-governance.md#standard) classes | Optional | List of standards, schemas, or profiles the dataset follows | +| [contributor](#contributor) | null or array of [Agent](./agents.md#agent) classes | Optional | List of agents contributing to the Dataset | +| [created](#created) | null or object | Optional | The date on which the Dataset was first created | +| [creator](#creator) | null or [Agent](./agents.md#agent) | Optional | Person or organization responsible for creating the dataset | +| [first](#first) | null or [Dataset](./dataset.md#root) | Optional | the first item of the sequence the dataset belongs to | +| [hasCurrentVersion](#hasCurrentVersion) | null or [Dataset](./dataset.md#root) | Optional | reference to the current (latest) version of a dataset | +| [hasPart](#hasPart) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related datasets that are part of the described dataset | +| [hasQualityMeasurement](#hasQualityMeasurement) | null or array of [QualityMeasurement](./temporal-spatial-metrics.md#quality-measurement) classes | Optional | List of quality measurements for the dataset (for example, completeness, accuracy, or timeliness) beyond spatial or temporal resolution | +| [hasVersion](#hasVersion) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related Datasets that are a version, edition, or adaptation of the described Dataset | +| [image](#image) | null or string | Optional | Thumbnail image illustrating the dataset, especially useful for visual data such as maps, photos, or video | +| [isReferencedBy](#isReferencedBy) | null or array of string | Optional | List of links to related resources, such as publications, that reference, cite, or otherwise point to the Dataset | +| [issued](#issued) | null or object | Optional | Date when the dataset was first published. If the exact publication date is unknown, use the date it was first referenced in the catalog. | +| [language](#language) | single Language code or array of Language codes | Optional | ISO 639-1 language code values used in the dataset text or metadata, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | +| [liabilityStatement](#liabilityStatement) | null or string | Optional | A liability statement about the dataset that may clarify limitations of responsibility, qualifications on the accuracy, reliability, and completeness of the data, or absence of endorsement by the data publisher or provider, among other considerations | +| [metadataDistribution](#metadataDistribution) | null or array of [Distribution](./distribution.md#root) classes | Optional | Distribution of the original metadata document this dataset was derived from | +| [otherIdentifier](#otherIdentifier) | null or array of [Identifier](./identifiers-and-relationships.md#identifier) classes | Optional | Additional identifiers for the dataset besides the main identifier, such as a DOI or other persistent ID | +| [page](#page) | null or array of [Document](./quality-governance.md#document) classes | Optional | List of pages or documents about this dataset | +| [previousVersion](#previousVersion) | null or [Dataset](./dataset.md#root) | Optional | reference to the previous dataset version | +| [provenance](#provenance) | null or array of string | Optional | List of statements about the lineage of a Dataset, including any changes in its ownership or custody since its creation that may be significant for its authenticity, integrity, or interpretation | +| [purpose](#purpose) | null or string | Optional | The purpose of the dataset | +| [qualifiedAttribution](#qualifiedAttribution) | null or array of [Attribution](./quality-governance.md#attribution) classes | Optional | List of agents with specific responsibilities for the dataset | +| [qualifiedRelation](#qualifiedRelation) | null or array of [Relationship](./identifiers-and-relationships.md#relationship) classes | Optional | Detailed relationship between the dataset and another resource, including the role of that relationship | +| [relation](#relation) | null or array of string | Optional | List of links to related resources when the relationship is not otherwise specified | +| [replaces](#replaces) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of Datasets replaced by this Dataset | +| [rightsHolder](#rightsHolder) | null or array of [Organization](./agents.md#organization) classes | Optional | List of agents (organizations) holding rights on the Dataset | +| [sample](#sample) | null or array of [Distribution](./distribution.md#root) classes | Optional | List of sample distributions for the dataset | +| [scopeNote](#scopeNote) | null or string | Optional | usage note for the dataset | +| [source](#source) | null or array of [Dataset](./dataset.md#root) classes | Optional | List of related Datasets from which the described Dataset is derived | +| [spatialResolutionInMeters](#spatialResolutionInMeters) | null or string | Optional | Smallest spatial distance between data points, in meters, represented as a single value | +| [status](#status) | null or [Concept](./identifiers-and-relationships.md#concept) | Optional | Lifecycle status of the dataset, such as completed, deprecated, under development, or withdrawn | +| [subject](#subject) | null or array of [Concept](./identifiers-and-relationships.md#concept) classes | Optional | List of primary subjects for the dataset, usually narrower than broad theme categories | +| [supportedSchema](#supportedSchema) | null or [Dataset](./dataset.md#root) | Optional | supported schema for this dataset | +| [temporalResolution](#temporalResolution) | null or string | Optional | Smallest time interval between data points, using xsd:duration format (for example, P1D) | +| [version](#version) | null or string | Optional | The version indicator (name or identifier) of a resource | +| [versionNotes](#versionNotes) | null or string | Optional | Notes describing how this version differs from earlier versions of the dataset | +| [wasAttributedTo](#wasAttributedTo) | null or array of [Agent](./agents.md#agent) classes | Optional | List of agents attributed to this dataset | +| [wasGeneratedBy](#wasGeneratedBy) | null or array of [Activity](./temporal-spatial-metrics.md#activity) classes | Optional | List of activities that generated, or provide the business context for the creation of the dataset | +| [wasUsedBy](#wasUsedBy) | null or array of [Activity](./temporal-spatial-metrics.md#activity) classes | Optional | List of activities that used the Dataset | ## `Dataset > contactPoint` [#](#contactPoint) @@ -167,7 +167,7 @@ A collection of data published or curated by one provider A contact point for questions about the Dataset (single contact or list). Include an email address that is continuously monitored -- **Type**: `combining` +- **Type**: single [Kind](./agents.md#kind) object or array of [Kind](./agents.md#kind) objects - **Required**: Yes - **Additional properties**: Any type allowed @@ -215,8 +215,10 @@ Plain-language summary of the dataset The unique identifier for the Dataset, e.g. the URI or other unique identifier in the context of the Catalog -- **Type**: null or [Identifier](./identifiers-and-relationships.md#identifier) +- **Type**: string or [Identifier](./identifiers-and-relationships.md#identifier) object - **Required**: Yes +- **Additional properties**: Any type allowed +- **Defined in**: [Identifier](./identifiers-and-relationships.md#identifier) ## `Dataset > title` [#](#title) @@ -447,7 +449,7 @@ Full text of a statement of rights A geographic region or regions that are covered by the Dataset -- **Type**: `combining` +- **Type**: single [Location](./temporal-spatial-metrics.md#location) object or array of [Location](./temporal-spatial-metrics.md#location) objects - **Additional properties**: Any type allowed **Any of:** @@ -820,7 +822,7 @@ Date when the dataset was first published. If the exact publication date is unkn ISO 639-1 language code values used in the dataset text or metadata, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html -- **Type**: `combining` +- **Type**: single Language code or array of Language codes - **Additional properties**: Any type allowed **Example:** diff --git a/jsonschema/docs/distribution.md b/jsonschema/docs/distribution.md index 60158c6..16ff443 100644 --- a/jsonschema/docs/distribution.md +++ b/jsonschema/docs/distribution.md @@ -64,7 +64,7 @@ A specific representation of a dataset, such as a file, feed, or API response | [image](#image) | null or string | Optional | A link to a thumbnail picture illustrating the content of the distribution | | [inventoried](#inventoried) | null or object | Optional | Date on which the distribution was added to the catalog. This may differ from the publication/release date. | | [issued](#issued) | null or object | Optional | The date of formal issuance (e.g., publication) of the Distribution | -| [language](#language) | More than one type | Optional | ISO 639-1 language code values used in the distribution metadata text, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | +| [language](#language) | single Language code or array of Language codes | Optional | ISO 639-1 language code values used in the distribution metadata text, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | | [mediaType](#mediaType) | null or string | Optional | MIME type of the Distribution (for example, text/csv or application/json), from the IANA media types registry: https://www.iana.org/assignments/media-types/media-types.xhtml | | [otherIdentifier](#otherIdentifier) | null or array of [Identifier](./identifiers-and-relationships.md#identifier) classes | Optional | A list of identifiers for the Distribution besides the main identifier, e.g. the URI or other unique identifiers in the context of the Catalog | | [packageFormat](#packageFormat) | null or string | Optional | The format of the file in which one or more data files are grouped together, e.g. to enable a set of related files to be downloaded together | @@ -480,7 +480,7 @@ The date of formal issuance (e.g., publication) of the Distribution ISO 639-1 language code values used in the distribution metadata text, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html -- **Type**: `combining` +- **Type**: single Language code or array of Language codes - **Additional properties**: Any type allowed **Examples:** diff --git a/jsonschema/docs/identifiers-and-relationships.md b/jsonschema/docs/identifiers-and-relationships.md index 3d6baca..b4c4812 100644 --- a/jsonschema/docs/identifiers-and-relationships.md +++ b/jsonschema/docs/identifiers-and-relationships.md @@ -8,7 +8,7 @@ Supporting classes for identifiers, relationships, checksums, and controlled con A unique identifier and optionally it's scheme and other relevant information -- **Type**: `combining` +- **Type**: string or [Identifier](./identifiers-and-relationships.md#identifier) object - **Additional properties**: Any type allowed **Any of:** @@ -266,7 +266,7 @@ A lower case hexadecimal encoded digest value produced using a specific algorith A controlled term or label, optionally drawn from a concept scheme -- **Type**: `combining` +- **Type**: string or [Concept](./identifiers-and-relationships.md#concept) object - **Additional properties**: Any type allowed **Examples:** diff --git a/jsonschema/docs/quality-governance.md b/jsonschema/docs/quality-governance.md index b32fdde..54baaf3 100644 --- a/jsonschema/docs/quality-governance.md +++ b/jsonschema/docs/quality-governance.md @@ -547,7 +547,7 @@ A record in a catalog, describing the registration of a single resource | [@type](#catalog-record--@type) | string | Optional | | | [description](#catalog-record--description) | null or array of string | Optional | A list of free-text accounts of the catalog record | | [issued](#catalog-record--issued) | null or array of object | Optional | List of dates on which the catalog record was included in the catalog | -| [language](#catalog-record--language) | More than one type | Optional | Language code used in catalog record metadata text, using ISO 639-1 values such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | +| [language](#catalog-record--language) | single Language code or array of Language codes | Optional | Language code used in catalog record metadata text, using ISO 639-1 values such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | | [source](#catalog-record--source) | null or string | Optional | The original metadata that was used in creating metadata for the items in the catalog record, either a URL referencing the source metadata or a string of the source metadata itself | | [title](#catalog-record--title) | null or string | Optional | A name given to the Catalog Record | @@ -784,7 +784,7 @@ A year and month in YYYY-MM format Language code used in catalog record metadata text, using ISO 639-1 values such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html -- **Type**: `combining` +- **Type**: single Language code or array of Language codes - **Additional properties**: Any type allowed **Examples:** @@ -946,7 +946,7 @@ A service that provides access to data or data processing functions | [identifier](#data-service--identifier) | null or [Identifier](./identifiers-and-relationships.md#identifier) | Optional | The unique identifier for the Data Service, e.g. the URI or other unique identifier in the context of the Catalog | | [inventoried](#data-service--inventoried) | null or object | Optional | Date on which the data service was added to the catalog. This may differ from the publication/release date. | | [keyword](#data-service--keyword) | null or array of string | Optional | List of keywords or tags describing the data service | -| [language](#data-service--language) | More than one type | Optional | ISO 639-1 language code values supported by the data service, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | +| [language](#data-service--language) | single Language code or array of Language codes | Optional | ISO 639-1 language code values supported by the data service, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html | | [modified](#data-service--modified) | null or object | Optional | The most recent date on which the Data Service was changed or modified | | [otherIdentifier](#data-service--otherIdentifier) | null or array of [Identifier](./identifiers-and-relationships.md#identifier) classes | Optional | A list of identifiers for the Data Service besides the main identifier, e.g. the URI or other unique identifiers in the context of the Catalog | | [qualifiedAttribution](#data-service--qualifiedAttribution) | null or array of [Attribution](./quality-governance.md#attribution) classes | Optional | List of agents with specific responsibilities for the data service | @@ -1309,7 +1309,7 @@ List of keywords or tags describing the data service ISO 639-1 language code values supported by the data service, such as en or es, full list can be seen at https://id.loc.gov/vocabulary/iso639-1.html -- **Type**: `combining` +- **Type**: single Language code or array of Language codes - **Additional properties**: Any type allowed **Examples:** diff --git a/jsonschema/generate_schema_docs.py b/jsonschema/generate_schema_docs.py index e0458f1..57b017d 100644 --- a/jsonschema/generate_schema_docs.py +++ b/jsonschema/generate_schema_docs.py @@ -293,6 +293,32 @@ def _canonical_class_doc_link(schema_node): return None +def _canonical_class_display_name(schema_node): + if schema_node is None: + return None + + candidates = [schema_node, schema_node.refers_to, schema_node.refers_to_merged] + for candidate in candidates: + if candidate is None: + continue + + class_name = None + if getattr(candidate, "ref_path", None): + class_name = candidate.ref_path.split("/")[-1] + elif getattr(candidate, "definition_name", None): + class_name = candidate.definition_name + + if not class_name: + continue + + normalized_name = class_name.lower() + display_name = CLASS_DISPLAY_NAME_MAP.get(normalized_name) + if display_name: + return display_name + + return None + + def _rewrite_class_doc_links(content): def _replace(match): label = match.group(1) @@ -611,6 +637,168 @@ def _simple_type_label(schema): return type_name or None +def _combining_schema(schema): + candidates = [schema, schema.refers_to_merged, schema.refers_to] + for candidate in candidates: + if candidate and jinja_filters.is_combining(candidate): + return candidate + + return None + + +def _combining_branches(schema): + combining_schema = _combining_schema(schema) + if combining_schema is None: + return [] + + for keyword_name in ("kw_any_of", "kw_one_of", "kw_all_of"): + keyword_node = getattr(combining_schema, keyword_name, None) + if keyword_node: + return list(keyword_node.array_items or []) + + return [] + + +def _meaningful_combining_branches(schema): + return [ + branch + for branch in _combining_branches(schema) + if getattr(branch, "type_name", "") != "null" + ] + + +def _single_branch_class(branch): + class_link = _canonical_class_doc_link(branch) + class_name = _canonical_class_display_name(branch) + if class_link and class_name: + return class_name.lower(), class_link + + return None, None + + +def _array_branch_class(branch): + array_item = getattr(branch, "array_items_def", None) + if array_item is None: + return None, None + + class_link = _canonical_class_doc_link(array_item) + class_name = _canonical_class_display_name(array_item) + if class_link and class_name: + return class_name.lower(), class_link + + return None, None + + +def _pluralize_label(label): + if not label: + return label + + parts = label.split(" ") + last_word = parts[-1] + + if re.search(r"[^aeiou]y$", last_word, re.IGNORECASE): + parts[-1] = f"{last_word[:-1]}ies" + elif re.search(r"(s|x|z|ch|sh)$", last_word, re.IGNORECASE): + parts[-1] = f"{last_word}es" + else: + parts[-1] = f"{last_word}s" + + return " ".join(parts) + + +def _branch_descriptor(branch): + class_key, class_link = _single_branch_class(branch) + if class_key and class_link: + return {"kind": "class", "key": class_key, "label": class_link} + + title = getattr(branch, "title", None) + if title and not re.fullmatch(r"item\s+\d+", title, re.IGNORECASE): + return { + "kind": "label", + "key": _normalize_label(title), + "label": title, + } + + type_name = getattr(branch, "type_name", None) + if type_name: + return {"kind": "label", "key": type_name, "label": type_name} + + return None + + +def _array_item_descriptor(branch): + array_item = getattr(branch, "array_items_def", None) + if array_item is None: + return None + + return _branch_descriptor(array_item) + + +def _descriptive_combining_type_label(schema): + branches = _meaningful_combining_branches(schema) + if len(branches) != 2: + return None + + non_array_branch = None + array_branch = None + primitive_branch = None + object_branch = None + + for branch in branches: + branch_type = getattr(branch, "type_name", "") + if getattr(branch, "array_items_def", None) is not None: + array_branch = branch + else: + non_array_branch = branch + + if branch_type in {"string", "integer", "number", "boolean"}: + primitive_branch = branch + + if branch_type == "object": + object_branch = branch + + if non_array_branch and array_branch: + single_class_key, single_class_link = _single_branch_class(non_array_branch) + array_class_key, array_class_link = _array_branch_class(array_branch) + if ( + single_class_key + and array_class_key + and single_class_key == array_class_key + and single_class_link + and array_class_link + ): + return ( + f"single {single_class_link} object or array of " + f"{array_class_link} objects" + ) + + single_descriptor = _branch_descriptor(non_array_branch) + array_item_descriptor = _array_item_descriptor(array_branch) + if ( + single_descriptor + and array_item_descriptor + and single_descriptor["key"] == array_item_descriptor["key"] + and single_descriptor["kind"] == "label" + and array_item_descriptor["kind"] == "label" + ): + singular_label = single_descriptor["label"] + plural_label = _pluralize_label(array_item_descriptor["label"]) + return f"single {singular_label} or array of {plural_label}" + + if primitive_branch and object_branch: + primitive_type = getattr(primitive_branch, "type_name", None) + class_link = _canonical_class_doc_link(schema) or _canonical_class_doc_link( + object_branch + ) + class_name = _canonical_class_display_name(schema) or _canonical_class_display_name( + object_branch + ) + if primitive_type and class_link and class_name: + return f"{primitive_type} or {class_link} object" + + return None + + def _collapsed_nullable_branch(schema): for keyword_name in ("kw_any_of", "kw_one_of"): keyword_node = getattr(schema, keyword_name, None) @@ -639,6 +827,10 @@ def has_collapsed_nullable_branch(schema): def _display_type_label(schema): + descriptive_combining_label = _descriptive_combining_type_label(schema) + if descriptive_combining_label: + return descriptive_combining_label + array_item = getattr(schema, "array_items_def", None) tuple_items = getattr(schema, "tuple_validation_items", None) or [] if array_item and not tuple_items: @@ -793,9 +985,6 @@ def type_info_table_wrap(type_info_list, schema): line[1] = f"[{class_name.title()}](./{class_name.title()}.md)" elif line_label == "Same definition as" and canonical_link: line[1] = canonical_link - elif "`combining`" in line: - # replace combining with something better - line[line.index("`combining`")] = "More than one type" # remove lines def _remove_me(line):