search

opengeospatial / ogcapi-features

An open standard for querying geospatial information on the web.
https://ogcapi.ogc.org/features
Other
334 stars 83 forks source link

Part 5: relating the Schema requirement class to Part 1 describedBy #928

Open rouault opened 3 months ago

rouault commented 3 months ago

Neither https://docs.ogc.org/DRAFTS/23-058.html#overview nor https://docs.ogc.org/DRAFTS/23-058.html#rc_schemas recall that in Part 1 there's already a way to associate a schema with a FeatureCollection by specifying a "rel": "describedBy" link in the FeatureCollection description. I don't know if that must be a requirement for Part 5, or just a note, but that would be worth recalling.

Hum actually looking at https://demo.ldproxy.net/daraa/collections/CulturePnt, I see a { "rel" : "http://www.opengis.net/def/rel/ogc/0.0/schema", "title" : "Schema of features in 'Cultural (Points)'", "href" : "https://demo.ldproxy.net/daraa/collections/CulturePnt/schema" }, where the rel value relates to the one mentioned in https://docs.ogc.org/DRAFTS/23-058.html#_additional_link_relation_types

but no describedBy. So this raises the question: is describedBy deprecated?

cportele commented 3 months ago

Good point, thank you for raising this.

The reason why Part 5 adds the "schema" link relation type and does no reference the "descibedby" link relation type is that JSON Schema recommends the "describedby" link relation type for linking to the JSON Schema from a JSON instance.

The issue is that while the schema as specified in Part 5 describes the feature properties, it cannot be used directly to validate a GeoJSON or JSON-FG instance using a JSON Schema validator. See this discussion.

Based on the recommendation in JSON Schema, it was our assumption that most software that sees a "describedby" link from a JSON document to a resource with media type application/schema+json would expect that the schema can be used to validate the instance. To avoid this, we decided to mint and use specific media types for the link to the Part 5 schemas.

"describedby" is not deprecated, but it should be used in links from a JSON document to a JSON Schema that can be used to validate the JSON document.

We should make this clearer in Part 5 and also in Part 1.

Does this make sense?

rouault commented 3 months ago

Does this make sense?

yes, thanks, that makes sense.

We should make this clearer in Part 5 and also in Part 1.

+1 as the difference between the "physical" schema of describedBy and the "logical" schema of Part 5 is quite subtle when you are not aware of it.

cportele commented 3 months ago

Thanks, I will work on a pull request.

cportele commented 2 months ago

Meeting 2024-07-01: Agreed, we should clarify this.