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

jerstlouis · 2024-09-24T12:44:33Z

The main change relates to the ability to describe meaning of enum values related to Fields for schema 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 ( see also v6 annotation: named enumerations json-schema-org/json-schema-spec#57 )
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

jerstlouis · 2024-09-24T20:41:23Z

It seems like the correct thing should be "oneOf" rather than "anyOf" to reflect the mutual exclusion.

There's a discussion in the S/O post (which suggested anyOf) about this. I'm leaning towards "oneOf" and thinking of fixing Common to use "oneOf".

cportele

See the specific comments.

On "anyOf" vs "oneOf": If used for validation, both will deliver the same result, if all options are mutually exclusive. With "oneOf" validation will take longer, but one could argue that it expresses the semantics more clearly. Anyhow, I really think we should avoid recommending the use of "anyOf" or "oneOf".

cportele · 2024-10-07T12:27:04Z

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/.


This change is not correct. Only the QUDT Units Vocabulary is a normative reference. The QUDT Ontologies could be added to the bibliography.

Meeting 2024-10-07: This change should be reversed. QUDT can be added to the bibliography.

cportele · 2024-10-07T12:28:16Z

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>>


This change is not correct. Only the QUDT Units Vocabulary is normatively referenced from provisions.

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

cportele · 2024-10-07T13:36:42Z

extensions/schemas/standard/clause_7_schemas.adoc

-^|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.


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.

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.

cportele · 2024-10-07T13:38:18Z

extensions/schemas/standard/clause_7_schemas.adoc

+|===
+^|*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.


Same as above. Using "enum" seems to be cleaner.

cportele · 2025-03-24T13:46:24Z

As discussed earlier in this PR, I have created examples for two options for representing properties with an enumerated list of values.

The first option has the advantage that all information is in the schema; no external information needs to be accessed.

The second option has the advantage that enum is easier to parse/handle than oneOf and that a separate resource for codelists may be useful for other purposes (in the API or separate from the API). A codelist URI may exist and the codelist may already be managed / published at the URI.

Using oneOf with each option with a const and optional title / description values.

Example, see properties ZI037_REL and F_CODE:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://demo.ldproxy.net/daraa/collections/CulturePnt/schema",
  "title": "Cultural (Points)",
  "type": "object",
  "required": [
    "geometry",
    "ZI001_SDV"
  ],
  "properties": {
    "ZI006_MEM": {
      "title": "Memorandum",
      "type": "string"
    },
    "FCSUBTYPE": {
      "title": "Feature Subtype Code",
      "type": "integer"
    },
    "ZI037_REL": {
      "title": "Religious Designation",
      "oneOf": [
        {
          "const": 1,
          "title": "Buddhism"
        },
        {
          "const": 2,
          "title": "Islam"
        },
        {
          "const": 3,
          "title": "Roman Catholic"
        },
        {
          "const": 5,
          "title": "Judaism"
        },
        {
          "const": 6,
          "title": "Orthodox"
        },
        {
          "const": 7,
          "title": "Protestant"
        },
        {
          "const": 8,
          "title": "Shinto"
        },
        {
          "const": 9,
          "title": "Hinduism"
        },
        {
          "const": 10,
          "title": "Shia"
        },
        {
          "const": 11,
          "title": "Sunni"
        },
        {
          "const": 12,
          "title": "Nestorian"
        },
        {
          "const": 13,
          "title": "Chaldean"
        },
        {
          "const": 14,
          "title": "Mixed and/or No Designation"
        },
        {
          "const": -999999,
          "title": "No Information"
        }
      ]
    },
    "ZI001_SDP": {
      "title": "Source Description",
      "type": "string"
    },
    "UFI": {
      "title": "Unique Entity Identifier",
      "type": "string"
    },
    "geometry": {
      "x-ogc-role": "primary-geometry",
      "format": "geometry-point"
    },
    "id": {
      "x-ogc-role": "id",
      "type": "integer"
    },
    "F_CODE": {
      "title": "Feature Type Code",
      "x-ogc-role": "type",
      "oneOf": [
        {
          "const": "AK121",
          "title": "Lookout"
        },
        {
          "const": "AL012",
          "title": "Archaeological Site"
        },
        {
          "const": "AL030",
          "title": "Cemetery"
        },
        {
          "const": "AL130",
          "title": "Memorial Monument"
        },
        {
          "const": "BH075",
          "title": "Fountain"
        }
      ]
    },
    "ZI001_SDV": {
      "title": "Last Change",
      "x-ogc-role": "primary-instant",
      "format": "date-time",
      "type": "string"
    },
    "ZI005_FNA": {
      "title": "Name",
      "type": "string"
    }
  }
}

Using enum and a separate codelist resource.

Same example (link):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://demo.ldproxy.net/daraa/collections/CulturePnt/schema",
  "title": "Cultural (Points)",
  "type": "object",
  "required": [
    "geometry",
    "ZI001_SDV"
  ],
  "properties": {
    "ZI006_MEM": {
      "title": "Memorandum",
      "type": "string"
    },
    "FCSUBTYPE": {
      "title": "Feature Subtype Code",
      "type": "integer"
    },
    "ZI037_REL": {
      "title": "Religious Designation",
      "x-ldproxy-codelistUri": "https://demo.ldproxy.net/daraa/codelists/daraa%2Frel",
      "enum": [
        -999999,
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14
      ],
      "type": "integer"
    },
    "ZI001_SDP": {
      "title": "Source Description",
      "type": "string"
    },
    "UFI": {
      "title": "Unique Entity Identifier",
      "type": "string"
    },
    "geometry": {
      "x-ogc-role": "primary-geometry",
      "format": "geometry-point"
    },
    "id": {
      "x-ogc-role": "id",
      "type": "integer"
    },
    "F_CODE": {
      "title": "Feature Type Code",
      "x-ldproxy-codelistUri": "https://demo.ldproxy.net/daraa/codelists/daraa%2Ff_code",
      "x-ogc-role": "type",
      "enum": [
        "AK121",
        "AL012",
        "AL030",
        "AL130",
        "BH075"
      ],
      "type": "string"
    },
    "ZI001_SDV": {
      "title": "Last Change",
      "x-ogc-role": "primary-instant",
      "format": "date-time",
      "type": "string"
    },
    "ZI005_FNA": {
      "title": "Name",
      "type": "string"
    }
  }
}

cportele · 2025-04-21T14:12:17Z

@jerstlouis - Now that we have merged #979, we probably need to close this PR and start from or at least update the pull request.

jerstlouis · 2025-04-21T20:24:54Z

Thanks @cportele . We will try to review this Thursday with @joanma747 and we'll update this PR.

- 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

jerstlouis · 2025-05-02T16:53:45Z

@cportele We started reviewing this together with @joanma747 today .
I rebased and updated the PR and addressed some of the concerns.

Because the document structure in the Common proposal is so different now, having split the requirements into separate files to follow the previous practice (which I personally find very cumbersome), we discussed how to proceed.

We would like to review/contribute directly in this Features repo / current document structure instead, but ensure that the document is agnostic of OGC API - Features. We added a new commit with some initial changes to that effect.
We will probably abandon the Common proposal document for now, trying to synchronize any important changes that was there.

There is still a concern about the potential for confusion for implementations of e.g., OGC API - Coverages to reference conformance URIs for an OGC API - Features extension. One potential solution is that we later produce a very simple Common - Part 3 document which simply references OGC API - Features - Part 5: Schemas as a dependency with no additional requirements.

This brings us to ask about the normative references including OGC API - Features - Part 1 in Part 5.

By the same logic why QUDT ontology should not have been a normative reference because it was not referenced in any of the requirements text, shoudn't Features - Part 1 also not be? There is no dependency on OGC API - Features - Part 1 in any of the requirement classes.

Considering that everything in the document would be agnostic of OGC API - Features, wouldn't the scope also be wrong in saying that it is an extension to OGC API - Features - Part 1: Core ?
It makes a lot more sense as an extension to OGC API - Common :)

One other thing we discussed was that the x-ogc-collectionId referencing a collection on the same server seems overly restrictive. Was this previously discussed and/or is there another mechanism to reference an arbitrary collection on any server?

Thanks!

cportele · 2025-05-04T12:30:18Z

@jerstlouis

The PR seems to be a mix of changes for which no issues exist. That makes it hard to review the PR and eventually accept it. My proposal is to close this PR and create issues for the different topics first (or where it is a simple editorial change, also a PR, but focussed on a single aspect). I can see at least the following unrelated topics in the current PR which should be discussed separately, not in a single PR:

Wording changes to replace "feature" by "data".
Wording changes related to units.
A capability to identify null values.

On replacing "feature" by "data": I agree that there are cases where we can reduce the use of "feature" in the document. In other cases, mainly the req classes "Core roles for features" and those about feature references, this is about feature data. At least all the normative and informative text have been driven by features as the resources. Maybe they can be generalized, but I don't think that simply replacing "feature" by "data" works or is the right thing to do. This could be a future task for the Common group.

This brings us to ask about the normative references including OGC API - Features - Part 1 in Part 5.

By the same logic why QUDT ontology should not have been a normative reference because it was not referenced in any of the requirements text, shoudn't Features - Part 1 also not be? There is no dependency on OGC API - Features - Part 1 in any of the requirement classes.

Correct, there is currently no dependency on Features Part 1 in any of the requirements classes - at least at the moment. If there is really no dependency, then this document reference has to be moved to the bibliography.

Considering that everything in the document would be agnostic of OGC API - Features, wouldn't the scope also be wrong in saying that it is an extension to OGC API - Features - Part 1: Core ?
It makes a lot more sense as an extension to OGC API - Common :)

Not in my view, see above.

One other thing we discussed was that the x-ogc-collectionId referencing a collection on the same server seems overly restrictive. Was this previously discussed and/or is there another mechanism to reference an arbitrary collection on any server?

Currently only the simple case of feature references in the same dataset and where all references target the same collection are considered. We have an issue to explore, if this is ok for now or if we should support additional requirements in v1.0, see #938.

We frequently have more complex cases and support them in ldproxy (references to external resources or references to varying collections), but when drafting the text we focussed on the main use case. It might be better to explore the more complex cases in a code sprint first and test options with running code (that is, after v1.0).

Edited to add: For this particular case, one can use "x-ogc-uriTemplate" instead of "x-ogc-collectionId" to reference a feature in a collection in another API.

jerstlouis force-pushed the master branch from f006df1 to 195f429 Compare September 24, 2024 12:56

jerstlouis mentioned this pull request Sep 24, 2024

Part 5: OGC API - Common - Part 2 "Schemas" req.class Syncing #954

Open

jerstlouis force-pushed the master branch from 195f429 to 036e9ba Compare September 24, 2024 20:46

cportele reviewed Oct 7, 2024

View reviewed changes

jerstlouis mentioned this pull request Dec 4, 2024

Fields for schema opengeospatial/ogcapi-coverages#173

Open

bpross-52n mentioned this pull request Mar 31, 2025

Is it possible to have descriptions for enumerated inputs? opengeospatial/ogcapi-processes#484

Closed

cportele mentioned this pull request Apr 2, 2025

Support for enumerated values with descriptions #978

Closed

jerstlouis force-pushed the master branch from 036e9ba to d854ce6 Compare May 2, 2025 15:30

jerstlouis force-pushed the master branch from d854ce6 to 8123f3a Compare May 2, 2025 15:33

schemas: Making roles not specific to features

af1ef89

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

jerstlouis commented Sep 24, 2024 •

edited

Loading

Uh oh!

jerstlouis commented Sep 24, 2024

Uh oh!

cportele left a comment

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele Oct 7, 2024 •

edited

Loading

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele Oct 7, 2024

Uh oh!

cportele commented Mar 24, 2025

Uh oh!

cportele commented Apr 21, 2025

Uh oh!

jerstlouis commented Apr 21, 2025

Uh oh!

jerstlouis commented May 2, 2025 •

edited

Loading

Uh oh!

cportele commented May 4, 2025 •

edited

Loading

Uh oh!

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

jerstlouis commented Sep 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jerstlouis commented Sep 24, 2024

Uh oh!

cportele left a comment

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele Oct 7, 2024

Choose a reason for hiding this comment

Uh oh!

cportele commented Mar 24, 2025

Uh oh!

cportele commented Apr 21, 2025

Uh oh!

jerstlouis commented Apr 21, 2025

Uh oh!

jerstlouis commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cportele commented May 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jerstlouis commented Sep 24, 2024 •

edited

Loading

cportele Oct 7, 2024 •

edited

Loading

jerstlouis commented May 2, 2025 •

edited

Loading

cportele commented May 4, 2025 •

edited

Loading