From 195f4291674e66d0b73ccf128a3e4e9054919449 Mon Sep 17 00:00:00 2001 From: Jerome St-Louis Date: Tue, 24 Sep 2024 08:29:32 -0400 Subject: [PATCH] schemas: Changes to sync OGC API - Common review - The main change relates to the ability to describe meaning of enum values related to https://github.com/opengeospatial/ogcapi-coverages/issues/173#issuecomment-1941601783 using a combination of `anyOf` with `const` + `title` as described in https://stackoverflow.com/questions/64233370/in-json-schema-how-to-define-an-enum-with-description-of-each-elements-in-the-e - Changes also introduce a new `x-ogc-nilValues` keyword for identifying nil values - Other changes are gramamr fixes and minor clarifications - Changing indirect dependency to QUDT in general as opposed to QUDT units since QUDT can also used for semantic definitions (not only QUDT units) - Clarified that JSON Schema keywords can also include additional keywords in section below --- .../schemas/standard/clause_3_references.adoc | 2 +- .../schemas/standard/clause_7_schemas.adoc | 68 +++++++++++++++---- 2 files changed, 57 insertions(+), 13 deletions(-) diff --git a/extensions/schemas/standard/clause_3_references.adoc b/extensions/schemas/standard/clause_3_references.adoc index 7a721ccc..2c6a99dd 100644 --- a/extensions/schemas/standard/clause_3_references.adoc +++ b/extensions/schemas/standard/clause_3_references.adoc @@ -9,7 +9,7 @@ The following normative documents contain provisions that, through reference in * [[ogc06_103r4]] Open Geospatial Consortium (OGC). OGC 06-103r4: **OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture**. Edited by J. Herring. 2011. Available at http://portal.opengeospatial.org/files/?artifact_id=25355 -* [[qudtunits]] QUDT.org. **QUDT Units Vocabulary 2.1**. Edited by R. Hodgson. 2024. Available at https://www.qudt.org/doc/DOC_VOCAB-UNITS.html. +* [[qudt]] QUDT.org. **QUDT Ontologies, derived models and vocabularies 2.1**. Edited by R. Hodgson. 2024. Available at https://www.qudt.org/. * [[ucum]] Regenstrief Institute, Inc. **The Unified Code for Units of Measure**. Edited by G. Schadow, .C J. McDonald. 2017. Available at https://ucum.org/ucum. diff --git a/extensions/schemas/standard/clause_7_schemas.adoc b/extensions/schemas/standard/clause_7_schemas.adoc index 4accbafb..4fbc1b71 100644 --- a/extensions/schemas/standard/clause_7_schemas.adoc +++ b/extensions/schemas/standard/clause_7_schemas.adoc @@ -12,7 +12,7 @@ The Requirements Class "Schemas" specifies basic provisions for schemas of items |Indirect Dependency |<> |Indirect Dependency |<> |Indirect Dependency |<> -|Indirect Dependency |<> +|Indirect Dependency |<> |=== [#schema-representation] @@ -27,7 +27,7 @@ The Requirements Class "Schemas" specifies basic provisions for schemas of items ^|B |The schema SHALL have the following characteristics: * "$schema" is "\https://json-schema.org/draft/2020-12/schema"; -* "$id" is a HTTP(S) URI without query parameters that returns the schema, if requested with the header "Accept: application/schema+json"; and +* "$id" is a HTTP(S) URI without query parameters that returns the schema, if requested with the header "Accept: application/schema+json"; and * "type" is "object". |=== @@ -58,12 +58,13 @@ The following recommendations are intended to simplify parsing a schema and to h ^|C |Properties that represent a URI SHOULD be represented as a string with format "uri" or "uri-reference". ^|D |Properties that represent a URI template SHOULD be represented as a string with format "uri-template". ^|E |Properties that represent a UUID SHOULD be represented as a string with format "uuid". -^|F |For string properties that are, "minLength", "maxLength", "enum" and/or "pattern" SHOULD be provided, where applicable. +^|F |For string properties, "minLength", "maxLength", "enum" and/or "pattern" SHOULD be provided, where applicable. ^|G |For numeric properties, "multipleOf", "minimum", "exclusiveMinimum", "maximum", "exclusiveMaximum" SHOULD be provided, where applicable. -^|H |For integer properties that represent enumerated values, "enum" SHOULD be provided. -^|I |For array properties, the property SHOULD consist of items that are strings or numbers. -^|J |Required properties SHOULD be included in "required". -^|K |The JSON Schema keywords SHOULD be constrained to the those mentioned in this recommendation and requirement `/req/{req-class}/properties`. +^|H |For integer properties that represent enumerated values without providing a description for each, "enum" SHOULD be provided. +^|I |For integer properties that represent enumerated values while providing a description for each, "anyOf" with a combination of "const" and "title" for each entry SHOULD be provided. +^|J |For array properties, the property SHOULD consist of items that are strings or numbers. +^|K |Required properties SHOULD be included in "required". +^|L |The JSON Schema keywords SHOULD be constrained to those mentioned in this recommendation, requirement `/req/{req-class}/properties` and requirements in the _additional keywords_ section below. |=== [#additional-keywords] @@ -79,7 +80,7 @@ In order to be able to map the logical schema to a format-specific schema, exten ^|A |Additional keywords SHALL start with "x-ogc-". |=== -CAUTION: The next version of JSON Schema will likely restrict the use of additional keywords. As a result, this Standard may need to change the prefix or change the way as to how the vocabulary is extended. +CAUTION: The next version of JSON Schema will likely restrict the use of additional keywords. As a result, this Standard may need to change the prefix or change how the vocabulary is extended. :req: role [#{req-class}_{req}] @@ -122,9 +123,9 @@ In geospatial data, numeric property values often represent a measurement and ha ^|A |The keyword "x-ogc-unit" SHALL be used to declare the unit of measure of the property. ^|B |The value of the keyword "x-ogc-unit" SHALL be a string representing the unit of measure. ^|C |The value of the keyword "x-ogc-unit" SHALL be the case sensitive UCUM representation ("c/s") unless a different language / register for units is identified in keyword "x-ogc-unitLang". -^|D |The value for UCUM, if explicitly declared as the language for units in keyword "x-ogc-unitLang", SHALL be "UCUM". -^|E |The value for the QUDT Units Vocabulary, if declared as the language for units in keyword "x-ogc-unitLang", SHALL be "QUDT". -^|F |The value of the keyword "x-ogc-unit" SHALL be the URI of the unit for values from the QUDT Units Vocabulary. +^|D |The value for UCUM, if explicitly declared as the language for units in keyword "x-ogc-unitLang", SHALL be "UCUM". +^|E |For specifying a unit from QUDT Units Vocabulary, "x-ogc-unitLang", SHALL be "QUDT". +^|F |For specifying a unit from QUDT Units Vocabulary, the value of the keyword "x-ogc-unit" SHALL be the URI of the unit. |=== Communities or other OGC Standards can specify additional values for other unit languages, e.g., https://www.opengis.net/def/uom[units registered in the OGC Rainbow]. For each language it must be specified how units have to be represented in the "x-ogc-unit" value. @@ -142,12 +143,21 @@ NOTE: For example, the value for hectopascal is `hPa` in UCUM and `\https://qudt ^|B |The value of the keyword "x-ogc-definition" SHALL be a URI. |=== +:req: nilvalues +[#{req-class}_{req}] +[width="90%",cols="2,7a"] +|=== +^|*Requirement {counter:req-num}* |/req/{req-class}/{req} +^|A |The keyword "x-ogc-nilValues" SHALL be used to identify the values considered nil. +^|B |The value of the keyword "x-ogc-nilValues" SHALL be an array of objects, each including a mandatory "const" value and an optional "title" explanation of the meaning of that particular nil value. +|=== + === Examples The following example is the schema of a feature type representing cultural entities. The schema includes additional keywords that apply to feature data (specified in the next Clause). [[example_7_1]] -.Schema of a "Cultural (Points)" feature type +.Schema of a "Cultural (Points)" feature type ==== [source,JSON] ---- @@ -201,6 +211,9 @@ The following example is the schema of a feature type representing cultural enti "ZI037_REL" : { "title" : "Religious Designation", "enum" : [ -999999, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 ], + "x-ogc-nilValues": [ + { "const": -999999, "title": "unknown" } + ], "type" : "integer", "x-ogc-propertySeq": 8 }, @@ -263,3 +276,34 @@ The next example is the schema of a feature type representing observations of at } ---- ==== + +The next example is the schema of a land cover collection. + +[[example_7_3]] +.Schema of a land cover collection +==== +[source,JSON] +---- +{ + "$schema" : "https://json-schema.org/draft/2020-12/schema", + "$id" : "https://example.com/ogcapi/collections/landcover/schema", + "title" : "Land Cover", + "type" : "object", + "properties" : { "LC" : { + "title" : "Land Cover", + "type" : "integer", + "x-ogc-propertySeq" : 1, + "anyOf": [ + { "const": 0 }, + { "const": 1, "title": "vegetation" }, + { "const": 2, "title": "bare soils" }, + { "const": 3, "title": "water" }, + { "const": 4, "title": "clouds" }, + ], + "x-ogc-nilValues": [ + { "const": 0, "title": "no data" } + ] + } +} +---- +====