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

Author: jerstlouis

extensions/schemas/standard/annex_bibliography.adoc

@@ -11,6 +11,8 @@
 
 [[OpenAPI]] OpenAPI Initiative (OAI). **OpenAPI Specification 3.0** [online, viewed 2023-10-14]. 2020. Available at http://spec.openapis.org/oas/v3.0.3
 
+[[qudt]] QUDT.org. **QUDT Ontologies, derived models and vocabularies 2.1**. Edited by R. Hodgson. 2024. Available at https://www.qudt.org/
+
 [[rfc6906]] Internet Engineering Task Force (IETF). RFC 6906: **The 'profile' Link Relation Type**. Edited by E. Wilde. 2013. Available at https://www.rfc-editor.org/rfc/rfc6906.html
 
 [[rfc8288]] Internet Engineering Task Force (IETF). RFC 8288: **Web Linking**. Edited by M. Nottingham. 2017. Available at https://www.rfc-editor.org/rfc/rfc8288.html

extensions/schemas/standard/clause_7_schemas.adoc

@@ -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".
 |===
 
@@ -60,11 +60,11 @@ The following recommendations are intended to simplify parsing a schema and to h
 ^|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, "enum" SHOULD be provided.
+^|H |For integer properties that represent enumerated values (except for codelist values), "enum" SHOULD be provided.
 ^|I |For string or integer properties that represent codelist values, one of the profiles "codelist-inline" or "codelist-ref" (see <<rc_profile-codelists>>) SHOULD be applied.
 ^|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 the those mentioned in this recommendation and requirement `/req/{req-class}/properties`.
+^|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]
@@ -80,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}]
@@ -123,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.
@@ -143,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]
 ----
@@ -202,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
     },
@@ -264,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" }
+      ]
+   }
+}
+----
+====