api icon indicating copy to clipboard operation
api copied to clipboard

Update services and services registry documentation

Open ksclarke opened this issue 2 years ago • 0 comments

The v3 presentation spec references the services registry documentation found at:

https://github.com/IIIF/api/blob/main/source/api/registry/services/index.md#31-image-information

The documentation on this page though is out of sync with the v3 presentation spec. For instance, the v3 spec requires a service to have a type but there is no mention of it on the services registry documentation page. The profile on the registry page also refers to using a level2.json value, while the v3 presentation spec now uses level2.

A second concern: there is documentation about how to handle older services that don't have a type at https://iiif.io/api/annex/services/#services but if one looks first at the other older specs (e.g. https://iiif.io/api/auth/1.0/#access-cookie-service) there is no mention of this, which might cause confusion depending on the direction from which the user approaches the services documentation (coming from the auth spec, for instance, one wouldn't know about the v3 presentation specs' requirements).

I think it would be useful to update the documentation for the older services to indicate that when they're used within the content of a v3 presentation manifest that type, for instance, must be supplied (and point to the v3 presentation spec for more details about those prescribed values, etc.)

ksclarke avatar Sep 17 '21 20:09 ksclarke