Merge pull request #133 from opengeospatial/issue-99

update type and license

09-AUG-2021: No objections to merging this PR.

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: |-

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/

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]]

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
 

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.
+|===

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 https://spdx.dev/ids[identifiers] from the <<SPDX,SPDX License List>> is recommended, where applicable. 
+^|C |If multiple licenses apply, it is recommended to use "various" as a special value.
+|===

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.
 |===

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.
+|===

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
 ----
 |===