From 0b243269b96e2ca69b415ceeadb99bf17b261a8f Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Mon, 9 Aug 2021 11:51:23 +0200 Subject: [PATCH 1/2] update type and license closes #99 --- core/openapi/schemas/recordGeoJSON.yaml | 14 ++++++++++---- core/standard/clause_7_record_api.adoc | 2 ++ core/standard/clause_7_record_core.adoc | 11 +++++++++++ .../core/REC_query-param-type-definition.adoc | 6 ++++++ .../recommendations/core/REC_record-license.adoc | 8 ++++++++ .../recommendations/core/REC_record-links.adoc | 2 ++ .../recommendations/core/REC_record-type.adoc | 6 ++++++ .../core/REQ_query-param-type-definition.adoc | 3 ++- 8 files changed, 47 insertions(+), 5 deletions(-) create mode 100644 core/standard/recommendations/core/REC_query-param-type-definition.adoc create mode 100644 core/standard/recommendations/core/REC_record-license.adoc create mode 100644 core/standard/recommendations/core/REC_record-type.adoc diff --git a/core/openapi/schemas/recordGeoJSON.yaml b/core/openapi/schemas/recordGeoJSON.yaml index 3515055a..7429e9a7 100644 --- a/core/openapi/schemas/recordGeoJSON.yaml +++ b/core/openapi/schemas/recordGeoJSON.yaml @@ -35,8 +35,11 @@ properties: type: type: string description: |- - The nature or genre of the resource. - format: uri + The nature or genre of the resource. The value should be a code, + convenient for filtering the records. Where available, a link to + the canonical URI of the record type resource will be added to + the 'links' property. + maxLength: 64 title: type: string description: |- @@ -123,8 +126,11 @@ properties: license: type: string description: |- - A legal document under which the resource is made available. - format: uri + A legal document under which the resource is made available. + The value should be a code, convenient for filtering the records. + Where applicable, the use of the identifiers from the SPDX License List is recommended. If multiple licenses apply, it is recommended to use "various". + Where available, links to a URI of each applicable license should be added to the 'links' property. + maxLength: 64 rights: type: string description: |- diff --git a/core/standard/clause_7_record_api.adoc b/core/standard/clause_7_record_api.adoc index 0273110d..e04fa39f 100644 --- a/core/standard/clause_7_record_api.adoc +++ b/core/standard/clause_7_record_api.adoc @@ -128,6 +128,8 @@ include::requirements/core/REQ_query-param-q-response.adoc[] include::requirements/core/REQ_query-param-type-definition.adoc[] +include::recommendations/core/REC_query-param-type-definition.adoc[] + include::requirements/core/REQ_query-param-type-response.adoc[] [[core-query-parameters-externalid]] diff --git a/core/standard/clause_7_record_core.adoc b/core/standard/clause_7_record_core.adoc index 06232713..aa648dea 100644 --- a/core/standard/clause_7_record_core.adoc +++ b/core/standard/clause_7_record_core.adoc @@ -92,6 +92,17 @@ these properties in a record. include::recommendations/core/REC_record-keywords-themes.adoc[] +[[sc_type_and_licenses]] +==== Type and Licenses + +A record has one `properties.type` and one `properties.license` properties. The value of each property should be a code, convenient for filtering records. + +include::recommendations/core/REC_record-type.adoc[] + +include::recommendations/core/REC_record-license.adoc[] + +In addition, links to external resources representing the record type and the licenses are recommended, as described in the next section. + [[sc_associations_and_links]] ==== Associations and Links diff --git a/core/standard/recommendations/core/REC_query-param-type-definition.adoc b/core/standard/recommendations/core/REC_query-param-type-definition.adoc new file mode 100644 index 00000000..ad3f345b --- /dev/null +++ b/core/standard/recommendations/core/REC_query-param-type-definition.adoc @@ -0,0 +1,6 @@ +[[rec_core_param-type-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/core/param-type-definition* +^|A |The definition of the `type` parameter SHOULD be extended to enumerate the list of known record types. +|=== diff --git a/core/standard/recommendations/core/REC_record-license.adoc b/core/standard/recommendations/core/REC_record-license.adoc new file mode 100644 index 00000000..9f3b3bca --- /dev/null +++ b/core/standard/recommendations/core/REC_record-license.adoc @@ -0,0 +1,8 @@ +[[rec_record-license]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/core/record-license* +^|A |The list of codes that can occur in records of a catalog for the property `properties.license` SHOULD be listed as enum values in the API definition of the record schema. +^|B |The use of the identifiers from the SPDX License List is recommended, where applicable. +^|C |If multiple licenses apply, it is recommended to use "various" as a special value. +|=== diff --git a/core/standard/recommendations/core/REC_record-links.adoc b/core/standard/recommendations/core/REC_record-links.adoc index f58c070c..e74249ae 100644 --- a/core/standard/recommendations/core/REC_record-links.adoc +++ b/core/standard/recommendations/core/REC_record-links.adoc @@ -3,4 +3,6 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/core/record-links* ^|A |Implementations SHOULD use the record `links` property to provide hypermedia for navigation in the API (e.g. next record in a query response ) and alternate representations of the current record. +^|B |If a canonical URI is available for the record type that is the value of the core queryable _type_, a link with link relation type `type` to that canonical URI SHOULD be added to the `links` property. +^|C |If a canonical URI is available for a license that is a value of the core queryable _license_, a link with link relation type `license` to that canonical URI SHOULD be added to the `links` property. |=== diff --git a/core/standard/recommendations/core/REC_record-type.adoc b/core/standard/recommendations/core/REC_record-type.adoc new file mode 100644 index 00000000..4cacfd5b --- /dev/null +++ b/core/standard/recommendations/core/REC_record-type.adoc @@ -0,0 +1,6 @@ +[[rec_record-type]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/core/record-type* +^|A |The list of codes that can occur in records of a catalog for the property `properties.type` SHOULD be listed as enum values in the API definition of the record schema. +|=== diff --git a/core/standard/requirements/core/REQ_query-param-type-definition.adoc b/core/standard/requirements/core/REQ_query-param-type-definition.adoc index 9071be78..44c2fd23 100644 --- a/core/standard/requirements/core/REQ_query-param-type-definition.adoc +++ b/core/standard/requirements/core/REQ_query-param-type-definition.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/core/param-type-definition* ^|A |A Records API SHALL support the search by Type (type) parameter for the operation. -^|A |The `type` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): +^|B |The `type` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): [source,YAML] ---- @@ -14,6 +14,7 @@ schema: type: array items: type: string + maxLength: 64 explode: false ---- |=== From 666939eca4f8e08b94f5655ae7a370160aa756e3 Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Mon, 9 Aug 2021 15:38:31 +0200 Subject: [PATCH 2/2] add SPDX reference --- core/standard/annex_bibliography.adoc | 1 + core/standard/recommendations/core/REC_record-license.adoc | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/core/standard/annex_bibliography.adoc b/core/standard/annex_bibliography.adoc index db28d3be..dee1c893 100644 --- a/core/standard/annex_bibliography.adoc +++ b/core/standard/annex_bibliography.adoc @@ -7,3 +7,4 @@ * [[DWBP]] W3C: Data on the Web Best Practices, W3C Recommendation 31 January 2017, https://www.w3.org/TR/dwbp/ * [[DCAT]] W3C: Data Catalog Vocabulary, W3C Recommendation 16 January 2014, https://www.w3.org/TR/vocab-dcat/ * [[link-relations]] IANA: Link Relation Types, https://www.iana.org/assignments/link-relations/link-relations.xml +* [[SPDX]] Linux Foundation: SPDX License List, https://spdx.org/licenses/ \ No newline at end of file diff --git a/core/standard/recommendations/core/REC_record-license.adoc b/core/standard/recommendations/core/REC_record-license.adoc index 9f3b3bca..dc48a4f0 100644 --- a/core/standard/recommendations/core/REC_record-license.adoc +++ b/core/standard/recommendations/core/REC_record-license.adoc @@ -3,6 +3,6 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/core/record-license* ^|A |The list of codes that can occur in records of a catalog for the property `properties.license` SHOULD be listed as enum values in the API definition of the record schema. -^|B |The use of the identifiers from the SPDX License List is recommended, where applicable. +^|B |The use of the https://spdx.dev/ids[identifiers] from the <> is recommended, where applicable. ^|C |If multiple licenses apply, it is recommended to use "various" as a special value. |===