Requirements for core Annotation properties

[azaroth42]

In 4.0, we are importing the annotation properties to IIIF as the 3d work requires a lot of extensions and processing rules.

This means that we need to define the requirements for relationships like body, target, motivation, source, and so on. Some are easy, but these four are very inconsistent in the way they're used in Annotation documents.

The consistent route for their values would be:

body and target MUST be an array of JSON objects. Each item MUST have the type property.
source MUST be a JSON object with id and type.
motivation MUST be an array of strings.

Following the "if it can ever have multiple values then it is always an array" rule, and similarly that if it can ever be a JSON object then it should always be a JSON object rather than a shortcut to the object's id as a string.

However this will break almost all 3.0 Manifests, especially for target.

There are several routes forward:

1. We can remain completely lax with the definitions and allow whatever comes (string, object, array of strings and/or objects)
2. We can make the consistent way SHOULD with a note that a future version will make it MUST
3. We can make it MUST with a note to client implementers to please be lenient in accepting other values
4. We can just make a clean break and say MUST

[azaroth42]

My preference is 4 -- Stop the rot by making it MUST for new implementations. Clients and libraries will make the transition easier, but having to wait for 5.0 before it's an unqualified requirement seems too lenient when it's encoding a consistent option that was already one of the possible options.

[edited to change up from 3, based on discussion below and in slack]

[tomcrane]

1 and 2 and 3(ish) mean that most existing Presentation 3 manifests become valid Presentation 4 manifests simply by giving them a version 4 @context. While 4 is clean, it prevents this.

But - so what? This seemed important to me earlier, but I'm not sure why I felt it was important. Maybe to encourage adoption or to ease the path... "now all our manifests are P4 simply by changing one line in some transformation code, we can start doing 3D gradually, slipping in Manifests with Scenes without having an official policy of supporting 2 different API versions".

With 4 and 3 (ideally) you'd have more work to do, more complex transforms (though not exactly hard), and republishing.

[glenrobson]

Having edited a lot of demo manifests and also to make the transistion easier from 3 to 4 I would vote for:

body and target MUST be an array of JSON objects. Each item MUST have the type property.

• To make consistent with v3 implementations body + target be objects if 1 value but array if multiple.

source MUST be a JSON object with id and type.

• Agree with this one. I haven't come across a source with only an id and without resolving the id its difficult to know what it references if you have to go through the manifest looking for a matching id.

motivation MUST be an array of strings.

• Less worried about this than body and target but would make it more consistent with v3 if a string for a single value was allowed.

For info the validator draft currently requires arrays for motivation, body and target and I've had to change almost every example to fit that pattern.

Also note the changes Stephen highlighted for the cookbook IIIF/cookbook-recipes#598 are all body, target, motivation array issues.

[stephenwf]

For annotation.target there may be an argument for having it as MUST be a single object. In the annotation model it states:

While it is possible to annotate multiple targets, the meaning of that annotation is that each Body applies independently to each of the Targets.

https://www.w3.org/TR/annotation-model/#h-sets-of-bodies-and-targets

So in a way we could say that has to be explicit, so instead of:

"target": [
  "http://example.com/page1",
  "http://example.org/page6",
  "http://example.net/page4"
]

You would have to explicitly say which class of list it is:

target": {
  "type": "Independents",
  "items": [
    {"id": "http://example.com/page1", "type": "Canvas"},
    {"id": "http://example.com/page6", "type": "Canvas"},
    {"id": "http://example.com/page4", "type": "Canvas"}
  ]
}

If target was always an object then it would be less breaking and the change. However, I think there might be a case for allowing URI syntax for targets.

The other thing is the common pattern for annotation targets:

"target": "http://example.com/page1#xywh=0,100,200,300"

Which under 4.0 as it is written now could be expanded validly as:

"target": [{
  "id": "http://example.com/page1#xywh=0,100,200,300",
  "type": "Canvas"
}]

Which I don't think is strictly right. It would instead be:

"target": [{
  "type": "SpecificResource",
  "source": {
     "id": "http://example.com/page1",
     "type": "Canvas",
  },
  "selector": [{
     "type": "FragmentSelector",
     "value": "xywh=0,100,200,300"
  }]
}]

Which in my opinion complicates the fairly basic support that many IIIF-based annotation tools currently have for:

"target": "http://example.com/page1#xywh=0,100,200,300"

Also these rules I guess wouldn't apply to externally linked annotations - so implementations would have to handle both ways potentially anyway. Although I don't know how much of a factor that would be.

IMO:

• Body being a must array is good.
• Target being an array - I think instead enforcing it be an object always would be less breaking, and clearer when you are dealing with a list (and what was meant by the list).
• Targets having {id,type} shape - good for clarity, especially with different types of containers.. but losing the shorthand that is very popular would affect compatibility.

[stephenwf]

Just a quick thought. Presentation 3.0 was designed as a clean break so further updates were minimal and mostly compatible. Additionally, this doesn't address external annotation lists which aren't bound by these rules and servers like Eluciate that are still in use won't apply the new ones. Consequently, the further IIIF annotations diverge from W3C standards the more confusing it will become in my opinion.

[azaroth42]

If we're using the constructions for multiple targets, it would be more consistent and likely easier to also use the same constructions for multiple bodies. Especially noting that multiple for either is pretty rare.

Regarding divergence, we're not incompatible with the W3C spec (apart from label), we're creating an application profile that constrains which of the possible constructions are expected in the IIIF use of annotations.

[mathewjordan]

There are several routes forward:

1. We can remain completely lax with the definitions and allow whatever comes (string, object, array of strings and/or objects)

2. We can make the consistent way **SHOULD** with a note that a future version will make it **MUST**

3. We can make it **MUST** with a note to client implementers to please be lenient in accepting other values

4. We can just make a clean break and say **MUST**

Being a major version, I believe it is absolutely fine for it to be a MUST as an array. But if a MUST, option 3 above is the likely the route that client implementers will take either way. Many of the viewers in the cookbook have leniency for wide aspects of the spec as it stands now for 3.0. Open in viewers a presentation 3.0 manifest with a "label": "My manifest title" and it will likely render.

[mikeapp]

(Moving from the editor's chat) I'm 👍 to MUST (option 4). This will push publishers to change, even if many clients perform 3->4 conversions. I could imagine that some developers adapting or creating 3D-specific clients might choose to adhere to the v4 spec and ignore past variations.

Also 👍 @stephenwf 's suggestion of using https://www.w3.org/TR/annotation-model/#sets-of-bodies-and-targets.

[robcast]

If we're using the constructions for multiple targets, it would be more consistent and likely easier to also use the same constructions for multiple bodies. Especially noting that multiple for either is pretty rare.

I think Mirador 3 creates two targets for every Annotation using the Annotation plugin. One with the SVGSelector and one with a fragment-URI of the bounding box which makes it kind of backwards compatible.

As for multiple bodies there is the use case of tagging with a URI and an additional human-readable text https://iiif.io/api/cookbook/recipe/0258-tagging-external-resource/ could that be "Independents"? The other use case of multiple languages the-WebAnno-way can use a "Choice" https://iiif.io/api/cookbook/recipe/0346-multilingual-annotation-body/

[azaroth42]

A preview branch with Composite, List and Independents, and always a single JSON object for body and target.

https://preview.iiif.io/api/p4-composite/presentation/4.0/#use-case-9-interactive-3d-light-switch

This is the only time we use multiple bodies or targets in the spec at the moment.

I think it's significantly cleaner compared to requiring a list for every body and target when 99.99% of the time there's only a single resource.