Add semantic references

[edwinvandenbelt]

It would be very convenient for consuming parties to get an idea of the meaning concepts/attributes in the APIs (Features/Processes etc.). I'd like to propose a generic extension on all classes & attributes (properties) in the spec, making it possible to refer to e.g. existing vocabs or agreed conceptual ontology on the web.

something like this:

x-semantics:
- url: external url to ttl, rdf, html
- url: other external url to ttl, rdf, html

Example would be (collection - reference to DCAT). I'm still puzzling how to shape it. It could also be a list of URIs, referring to ttl, rdf or just plain HTML website-anchors.

collection:
      type: object
      x-semantics:
      - url: https://www.w3.org/ns/dcat3.ttl#dataset
      required:
        - id
        - links
      properties:
        id:
          description: identifier of the collection used, for example, in URIs
          type: string
          example: address
          x-semantics:
          - url: http://purl.org/dc/terms/identifier
        title:
          description: human readable title of the collection
          type: string
          example: address
           x-semantics:
           - url: http://purl.org/dc/terms/title

If we do this on generic OGC level, it would be easier for implementing parties to adhere this approach also on their side, just extending the x-semantics list with a more precise reference.

For instance, an implementation could add to the GET /collection/road-segments/items and x-semantics part like this:

paths:
     /collection/road-segments/items:
       get:
         operationId: getRoadSegments
         responses:
             '200':
                $ref: "#/components/responses/segmentResponse"

responses:
   segmentResponse:
      content:
          application/json:
              schema:
                 type: object
                 x-semantics: 
                 - url: https://github.com/INSPIRE-MIF/technical-guidelines/blob/main/data/tn/dataspecification_tn.adoc#542115-roadlink

[cportele]

Part 5 specifies x-ogc-definition for this purpose.

[edwinvandenbelt]

That's something, but it shouldn't be just one. There could be a lot of semantic references, to facilitate interoperability. A 'person' could reference e.g. to https://schema.org/Person, http://xmlns.com/foaf/spec/#term_Person, etc.

[edwinvandenbelt]

And it only applies to properties (or do I misinterpret this one?). It's also only in JSON schema, not in the OpenAPI spec (/api). The semantic references must also be applicable on parameters (actually, this one is a requirement for OGC API Processes, to orchestrate multiple processes).

[cportele]

Meeting 2025-09-22:

• There should be only one definition. If there are multiple, which one wins? We think that a single definition URI is correct.
• Part 5 only documents the use of the keyword on properties, but we do not see why it could not be applied to other components or in an OpenAPI schema (which in OpenAPI v3.1 is JSON Schema anyhow).