schemas: Changes to sync OGC API - Common review #953
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,7 +12,7 @@ The Requirements Class "Schemas" specifies basic provisions for schemas of items | |
| |Indirect Dependency |<<json-schema-validation,JSON Schema Validation: A Vocabulary for Structural Validation of JSON>> | ||
| |Indirect Dependency |<<ogc06_103r4,Simple feature access - Part 1: Common architecture>> | ||
| |Indirect Dependency |<<ucum,The Unified Code for Units of Measure>> | ||
| |Indirect Dependency |<<qudt,QUDT Ontologies, derived models and vocabularies>> | ||
|
There was a problem hiding this comment. This change is not correct. Only the QUDT Units Vocabulary is normatively referenced from provisions. There was a problem hiding this comment. Meeting 2024-10-07: Same as above, this should be reversed. |
||
| |=== | ||
|
|
||
| [#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 | ||
| * "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, "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 without providing a description for each, "enum" SHOULD be provided. | ||
| ^|I |For integer properties that represent enumerated values while providing a description for each, "oneOf" with a combination of "const" and "title" for each entry SHOULD be provided. | ||
|
There was a problem hiding this comment. Using "enum" for all lists of enumerated values is easier to parse and more predictable. "oneOf" is always more problematic as one never knows how complex the different options are. And "oneOf" is often not supported in tooling. Having descriptions for each enum could also be handled as an orthogonal capability. In ldproxy, for example, we support references to a dictionary/object that maps codes/values to titles (we call them codelists). An example: schema and a codelist. There was a problem hiding this comment. Meeting 2024-10-07: Both options are valid and they have their drawbacks. We need more time to think about this more and work this out. @cportele will document other options. |
||
| ^|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 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 |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. | ||
|
There was a problem hiding this comment. Same as above. Using "enum" seems to be cleaner. |
||
| |=== | ||
|
|
||
| === 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 | ||
| ==== | ||
| [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, | ||
| "oneOf": [ | ||
| { "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" } | ||
| ] | ||
| } | ||
| } | ||
| ---- | ||
| ==== | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change is not correct. Only the QUDT Units Vocabulary is a normative reference. The QUDT Ontologies could be added to the bibliography.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Meeting 2024-10-07: This change should be reversed. QUDT can be added to the bibliography.