Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

schemas: Changes to sync OGC API - Common review #953

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

schemas: Changes to sync OGC API - Common review #953

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion extensions/schemas/standard/clause_3_references.adoc
View file
Open in desktop
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/.
Copy link
Member

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.

Copy link
Member

@cportele cportele Oct 7, 2024 •
edited
Loading

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.

* [[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.
68 changes: 56 additions & 12 deletions extensions/schemas/standard/clause_7_schemas.adoc
View file
Open in desktop
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>>
Copy link
Member

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 normatively referenced from provisions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meeting 2024-10-07: Same as above, this should be reversed.

|===

[#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, "oneOf" with a combination of "const" and "title" for each entry SHOULD be provided.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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]
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,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
.Schema of a "Cultural (Points)" feature type
====
[source,JSON]
----
Expand Down Expand Up @@ -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
},
Expand Down Expand Up @@ -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" }
]
}
}
----
====