schemas: Changes to sync OGC API - Common review

- 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

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.
 

extensions/schemas/standard/clause_7_schemas.adoc

@@ -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]
@@ -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, "oneOf" 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,
+      "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" }
+      ]
+   }
+}
+----
+====