search

netwerk-digitaal-erfgoed / requirements-datasets

Requirements for datasets
https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/
1 stars 0 forks source link

Recommend schema:usageInfo for all data APIs #64

Closed ddeboer closed 1 year ago

ddeboer commented 2 years ago

Currently the spec says:

If the distribution is a non-standard API, publishers MUST publish human-readable documentation on how to use that API and link to the documentation URL in the schema:usageInfo attribute.

However, it may help to disambiguate distributions if we recommend to use schema:usageInfo more widely, or even require it for all data APIs (but not for dumps), with a selection of predefined values:

coret commented 1 year ago

Suggested change to specification of schema:usageInfo:

Publishers SHOULD link to documentation URLs via the schema:usageInfo attribute. For datadumps this should be documentation about the data model. For API's this should be documentation about the specific capabilities of the API (like content-type support) AND the generic specification of the protocol which also 'types' the distribution.

Recommended URI's for typing: Protocol URI specification
OAI-PMH http://www.openarchives.org/pmh/
SPARQL https://www.w3.org/TR/sparql11-query/
TPF https://linkeddatafragments.org/specification/triple-pattern-fragments/ (unofficial draft!!)
REST https://developers.arcgis.com/rest/
WMS http://www.opengeospatial.org/standards/wms
GraphQL https://spec.graphql.org/

Note: Currently the fact that the spec says "if non-standard API and MUST publish" we cannot make the property required (in spec and SHACL). The suggested change says SHOULD, indicating a recommendation which leads to a warning if ommited (and not an error).