Good practice to refer to schema/documentation explaining the semantics

[sgrellet]

From the webinar discussions it seems that some of us are currently exploring how to provide a reference to the schema/documentation describing the semantics used in the GeoJSON properties.
Example from Armin :
ms:json-schema_0.7_idhttps://geoportal.trier.de/trier/config/jsonschema/pois.json</ms:json-schema_0.7_id>

To avoid each of us re-inventing his own wheel could we agree on a pattern/naming to follow ?

Quick food for thoughts try

"schema":{
"type":"application/schema+json",
"url":"link to the schema/documentation"
}
}

I'm not so sure "schema" is the better choice but, I was wiling to broaden the use to something else that json schema.

?

[cportele]

Schema support is under discussion in the OGC API groups. OGC API Features currently distinguishes three different schemas:

• the schema of the features in the response ("returnables", "response schema")
• the queryable properties of the features that can be used in filter expressions ("queryables")
• the schema of the features in a create/update transaction ("mutation schema")

The current plan is to provide all of them as JSON Schema as resources in the API under the collection resource (e.g. /collections/{collectionId}/queryables). There will also be links to the resources from the collection resource, the link relation types are tbd.

We have implemented the current proposal to see how it would look like and added a description in the OGC API Features GitHub issue.

A link to the response schema can of course also be added to the feature/feature collection responses just like any other link.

[sgrellet]

Thanks Clemens, good to know that it's being discussed. I'll take a look and try to see how we can test this.

[sgrellet]

Going to the link provided I feel only 1 use case is covered but we see 2 use cases (currently discussing this in the O&M SWG)

• A°/ client accessing the collection through the API -> will access the queryable : seems to work fine
• B°/ client accessing ONE feature representation (say GeoJSON ) through that Feature URI (in OGC API F terms doing ....collections/collectionId/items/itemId) : according to the approach described, in the payload you won't have the semantics/queryable described. This implies the following action on the client
  • 1°/ item -> collection
  • 2°/ client -> collection/queryable

Would that make sense to expose link to semantics/queryable in the item response payload ?

[cportele]

That is why wrote:

A link to the response schema can of course also be added to the feature/feature collection responses just like any other link.

JSON Schema recommends a describedby link in the http header: https://tools.ietf.org/html/draft-handrews-json-schema-02#section-11. That link could then also be added in the payload, but clients probably will / should look at the headers first, not the payload. In general, it is not common practice to identify the schema of a JSON document in the document itself and there is no mechanism in JSON Schema for this (i.e., there is no xsi:schemaLocation).

[sgrellet]

My bad, I went directly to the OGC API F work and forgot the last sentence.

"In general, it is not common practice to identify the schema of a JSON document in the document itself and there is no mechanism in JSON Schema for this (i.e., there is no xsi:schemaLocation)."

I'm getting bootstrapped on JSON schema. Better then go on the recommended approach and ensure it is implemented by server/client solutions

The only use case I see where I would still suggest adding a link in the payload would be when a person A passes a GeoJSON file to a person B instead of giving the API URL to person B.

[armin11]

In our case the approach was to find an automatic solution for many existing WFS in our SDI. I developed the proxy solution for WFS 1.1.0 and WFS 2.0.0. I was faced to 2 different problems:

1. We need a human readable HTML interface, that should automatically show human readable attribute titles and descriptions - in the best case with a multilingual approach. If the WFS DescribeFeaturetype operation would had json-schema as output format, it would have been possible to use this operation for the mapping of GML to the HTML representation (under some circumstances), but this is not the case. Also the use case, that consumers are able to build up there own HTML representation with the result of a single OGC API Features URI was intended. Example for a POI of the City of Trier: https://www.geoportal.rlp.de/spatial-objects/486/collections/ms:unesco_welterbe/items/unesco_welterbe.3730?f=html. This approach was the easiest way and the dataproviders like it ;-) . It is only a recommendation and should not be mandatory.

2. We need a possibility to add semantic information to each feature. Not only as json-ld but, also by adding RDFa to the HTML variants. I implemented this approach some years ago to the HTML-representations of our resource metadata (wms, wfs, layer, featuretype, dataset). To resolve this, I add a further attribute with an URI to a json-ld context file to our featuretype attributes. This allow the proxy to build up json-ld representations and the HTML variant with added semantic information. Google has published a new documentation with examples howto insert RDFA with the DCAT vocabulary: https://developers.google.com/search/docs/data-types/dataset

I also think, that sending a geojson file from one person to another is a realistic use case ;-) - maybe we should inject more metadata to the single objects - they may inherit this from their service metadata - this is only an idea - please think about maschine readable license information - I recommend the use of https://www.w3.org/TR/odrl-model/ - also for the metadata (services/datasets) itself ;-)