Cross Version Embedding

[azaroth42]

A master issue to try and describe the overall pain points.

When dealing with resources, there are two possible structures:

• embed: the representation is embedded, as is, into the current document. For example, auth service information into a manifest or info.json, or an info.json into a manifest. The representation may not exist separately, such as for auth services where the URI of the (e.g.) login service is the URI where the human logs in. In these cases, the data must be embedded.
• reference: only critical information is included, along with the URI of the other document, so that it can be dereferenced.

When dealing with resources that were designed to work together, embed is no problem as the resulting structure is consistent. Across versions, however, and the differences are glaringly obvious. This occurs primarily within the service property, as the join point between APIs. The other issue is Presentation API including the Annotation context, with some comparatively minor incompatibilities.

With the transition to v3 (or v2 for search & auth), and its more sweeping changes compared to v2, the big issues:

• All: profile is different per version per API :(
• All: id will be either @id in v2 or id in v3.
• All: type will be either @type in v2 or type in v3.
• All: service will always be a list in v3, and the above are the major properties of services.
• All: @context is used to determine major version and reset the mappings. In v3 we use scoped context definitions (as compaction cannot re-embed the context references in the right places) and type is used to determine major version.
• Prezi, Auth: label will be a string, object or list in v2, and a different sort of object in v3
• Prezi, Image: attribution in v2 as a string, object or list, to be renamed as a different object in v3.
• Prezi, Image: license is renamed to rights, and is always a list
• Prezi, Image: logo is always a list
• Prezi, Search: annotations is defined by both, differently.
• Prezi, Search: Search v1 assumes the v2 Prezi API and OA. v3 is the Web Annotation model.
• Prezi, Web Annotation: Label in Prezi3 is a language map, and a string in WADM. (value is okay, as the separation is easy to scope)

If the exact representation were always to be embedded, then scoped contexts plus some judicious term unsetting would allow some patterns to work, at the expense of inconsistent structures within a document.

Concrete examples:

Embedding with target context

{
  "id": "...",
  "type": "Manifest",
  "label": {"en": ["Example"]},
  "seeAlso": [{
    "id": "...",
    "type": "Dataset",
    "profile": "modsv3"
  }],
  "service": [{
    "@id": "...",
    "@type": "AuthCookieService1",
    "profile": "http://iiif.io/api/auth/1/login",
    "label": "Login"
  }]
}

In this case the Prezi3-based implementation needs to also process the previous versions of the other specifications, within the context of the Prezi3 document. Note also that the Auth spec does not define AuthCookieService1, but we need a type to scope the context to as the service property is used for all services.

Embedding in the v3 context

{
  "id": "...",
  "type": "Manifest",
  "label": {"en": ["Example"]},
  "seeAlso": [{
    "id": "...",
    "type": "Dataset",
    "profile": "modsv3"
  }],
  "service": [{
    "id": "...",
    "type": "AuthCookieService1",
    "profile": "login",
    "label": {"@none": ["Login"]}
  }]
}

However, while much more consistent, now the auth service description no longer conforms to the auth specification.

See: #1399, #1349, #1195, #1131, #1109, #1108, #1064 (--> #1301), #590, #518

[azaroth42]

Eds call 02/14: Prefer the first version with target API's context in place, as the code will need to deal with it anyway. Can move towards consistency with v3 Image and v2 Auth & Search over time.

[azaroth42]

:( The proposal in the comment above works for services, where we can retroactively define types and use JSON-LD 1.1 scoped contexts to ensure that the mappings are localized only to the right block ... however it does NOT work for a v3 Collection that references both v2 and v3 Manifests. Should the v2 Manifest have id or @id, type or @type, and a string label or language map?

The precedent of service would be that it should be consistent with the target document, meaning @id, @type and strings not language maps ... but there's no way to distinguish without having Manifest2 and Manifest3 types on which to do the scoping.

[zimeon]

Fixed by #1408