Skip to content

Commit

Permalink
schemas: Changes to sync OGC API - Common review
Browse files Browse the repository at this point in the history
- The main change relates to the ability to describe meaning of enum values
  related to opengeospatial/ogcapi-coverages#173 (comment)
  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
  • Loading branch information
jerstlouis committed Sep 24, 2024
1 parent 0183c73 commit f006df1
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 12 deletions.
2 changes: 1 addition & 1 deletion extensions/schemas/standard/clause_3_references.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
32 changes: 21 additions & 11 deletions extensions/schemas/standard/clause_7_schemas.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 |<<qudtunits,QUDT Units Vocabulary>>
|Indirect Dependency |<<qudt,QUDT Ontologies, derived models and vocabularies>>
|===

[#schema-representation]
Expand All @@ -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".
|===
Expand Down Expand Up @@ -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]
Expand All @@ -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}]
Expand Down Expand Up @@ -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.
Expand All @@ -142,6 +143,15 @@ 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).
Expand Down

0 comments on commit f006df1

Please sign in to comment.