Clarify requirements/expectations for `services`

[zimeon]

While thinking about adding the palette service #1011, I looked at http://iiif.io/api/annex/services/ because when talking about this and other possible services we seem to stray into a language awkwardness in that we conflate the "extra data" services (lump of JSON-LD included, e.g physdim, geojson), with more dynamic ideas of service that return JSON-LD (parallel with inlined data) or simply related services that return other data or do something else (e.g. auth services or an image transform service). At the very least I think we need to clarify the service requirements:

Service information included in the API responses MUST be both valid JSON-LD, and include a service-specific @context. Services SHOULD have an @id that can be dereferenced, and if so, the representation retrieved from that URI SHOULD be JSON-LD. The service at the URI in @id MAY require additional parameters, generate representations other than JSON-LD, or have no JSON-LD representation at all.

Services SHOULD have a profile URI which can be used to determine the type of service, especially for services that do not provide a JSON-LD representation. The representation retrieved from the profile URI SHOULD be a human or machine readable description of the service. Services MAY have a label property to provide a human readable string to display to the user in the situation that the service has to be selected or manually linked to rather than automatically processed.

Services MAY be included either by reference or embedded within the response. The decision as to whether to embed or reference is left up to the implementer, however embedded descriptions should be kept as short as possible. If the only properties of the object are @context, @id, profile and/or label, then the client SHOULD retrieve the resource from the URI given in @id.

Considerations:

1. The implication of "SHOULD have an @id that can be dereferenced" and later "Services MAY be included either by reference or embedded within the response" suggests a model where one either includes JSON-LD or links to a service that returns the same JSON-LD (following standard LD practice) -- we don't have any examples that actually use that pattern as far as I know. In auth we explicitly use @id for something other than this. One solution would be to change auth to use something other than @id to point to the service endpoint; another would be to change service description to remove any expectation of dereferencing @id to get JSON-LD (certainly not without recognizing a profile).
2. For a pure service described by just an @id and a profile (and perhaps a label) that doesn't generate JSON-LD , why would we demand an extra service specific@context? One possible solution would be assuming profile and label defined consistently among all IIIF API and thus covered by enclosing @context; another would be to have a generic service @context.
3. There is an assumption that profile and label properties are not redefined or co-opted in some weird way by a service @context. Should we be specific about this?

[azaroth42]

Agreed. There's data extensions and there's actual online services, and currently it's a weird and inconsistent mix of the two. I think this is where @jpstroop gets the "service is the most generic sort of thing" perspective from.

The embed/not embed issue came from referencing the Image API service description (info.json) in the Presentation API so you didn't have to dereference it. As they have separate contexts, the Image API context does need to be present. Then once we had a bunch of data from the info.json in the service block that happened to be JSON-LD, it seemed like a reasonable thing to do to just put arbitrary JSON-LD there as well. In retrospect, it wasn't the right approach.

The Image API service URI (e.g. the base URL) doesn't necessarily respond with the info.json, but it SHOULD (Image API 2.1, Section 2). OTOH, I don't think that the dereffed version needs to return identical JSON-LD, but it shouldn't be in conflict.

Agree that we shouldn't require a context for non JSON-LD, and that we should be explicit about not redefining label or profile.

I think using the regular JSON-LD extension capabilities for including new contexts in the data is preferable for extensions, rather than the current service conflation. At which point I think that the data oriented services can then just use whatever keys they like to relate from the subject resource.

[jpstroop]

There's data extensions and there's actual online services, and currently it's a weird and inconsistent mix of the two. I think this is where @jpstroop gets the "service is the most generic sort of thing" perspective from.

Pretty much.

At which point I think that the data oriented services can then just use whatever keys they like to relate from the subject resource.

I think being able to link to semantic descriptive metadata, geospatial coordinates, additional tech metadata, etc. in a standard way is important, but I don't think they're services; maybe they're a set of subproperties of seeAlso?

We'd need to define the characteristics of each carefully, probably need to break up 3.4.

Agree that we shouldn't require a context for non JSON-LD, and that we should be explicit about not redefining label or profile.

:+1:

[workergnome]

In my head-canon, I think of seeAlso as being a reference to an external data resource, provided as a convenience for the human viewer to download and/or a robot crawling the site. It's not intended to be used by a software viewer attempting to render the manifest.

I've thought of services as being descriptive data, likely generated by an online service, that adds additional capabilities to the manifest that we assume MIGHT be used by the software viewer attempting to render the manifest.

This matches my understanding of the IIIF Image service, as well as the dims service, and my palette service. This is useful, because it allows us to have a mechanism for community extensions for IIIF that don't have to go through the IIIF approval process, but can be added to both manifests and software viewers by community consensus and use.

[azaroth42]

Propose to close in favor of #1269.

[tomcrane]

👍

[mikeapp]

👍

[zimeon]

:+1: