IIIF/discovery

Comments on Discovery 0.3

Closed this issue · 8 comments

aisaac commented

Here are some comments on https://iiif.io/api/discovery/0.3/ Mostly editorial!

  • (1) In the light of the recent developments in the "IIIF Discovery for humans" stream, I find that the intro of 1 could still be a bit confusing about what kind of searching/finding/discovering happens in the spec. At this stage I feel that it's too early to wordsmith the doc while the CG is still not launched. Maybe we could just add a Note for future work, like "This introduction will be further refined to indicate the difference between the Change Discovery specification and the work of the "IIIF Discovery for humans" Community Group. editorial

  • (2) In the intro of 2 it would be good to have a mention of the IIIF Image API to really make the focus on Presentation API resources crystal clear, when we reference 'content'. It could be just adding "in the sense of the IIIF Image API" at the end of "The focus on IIIF Collections and Manifests is because these are the main access points to published content" (and then the part that starts with "however Activities describing" could be turned into a separate sentence). editorial

  • (3) The mention of "list" in the headings of 2.1 does not flow very well, as the examples that are shown are not about lists. Perhaps a reference to the 'real' example of list could be enough... Here's my suggestion for 2.1.1:

    • have the "example level 0 activity" just after the sentence "Starting with the IIIF resource URIs, we add an “Update” Activity wrapper around them.".
    • before "The order of the resources in the resulting list is unimportant" add "The idea is then to list these activities in pages, following the pattern presented in 2.2". I think the transition would still be ok with the next sentence "The order of the resources in the resulting list is unimportant".
      An alternative is to present, just after "example level 0 activity" (in the new suggested position) a full example of a page of Update activities, but maybe this is not needed. editorial

  • (4) The same point could be said about the notion of collections of pages, which is needed to understand 2.2 but not presented before. Not a big deal as it's the next section, but still I'd suggest to add a forward reference to 2.3 in 2.2, like "Pages reference the previous and next pages in that set, and the overall collection of pages (see following section) of which they are part." editorial

  • (5) In 3.2 the "Complete Ordered Collection Page Example" could include some kind of editorial trick in the orderedItems element to indicate that it's expected to contain 20 items. It's not a big deal but it would help readers to make sense of the startIndex set to 20. add: that the first page is expected to have 20 entries.editorial

  • (6) In 3.3 is the example of seeAlso for object really ok? The id there is expected to be a description of the object of the manifest and it may be strange to see the type "dataset" in there. I realize that the Presentation API also uses Dataset in its seeAlso for a manifest (https://iiif.io/api/presentation/3.0/#seealso) but somehow I sense that "our" datasets (the seeAlsos on collections) are a bit different and we should avoid confusion if possible.
    edit: Add note that Presentation API datasets include individual records, not just sets of data. editorial

  • (7) In 3.3 I feel that in order not to make implementers afraid, we could add a note next to the "Complete Activity Example", reminding that this is for a full-blown activity, and it's still possible to implement much simpler activities. Something like "Note that many of these elements are not required in the most basic levels of this specification, as shown in section 2.1.1." editorial

  • (8) In 3.4.1 we should add an editor's note saying that "http://iiif.io/api/discovery/0/context.json" is not going to be the final URI. Just in case a reviewer of a draft would feel about asking... discuss

  • (9) In 4.1 I think "it has been deleted and therefore remove it from its index" should be "it has been deleted and therefore remove it from their index" (as clients is plural earlier). editorial

  • (10) The intro of 3.5 could be extended by "This specification does not specify what use ("processing") should be made of the available information, though it gives an example (indexing) and some indication to tackle it (see section 3.5.3)". This would help situate "process" that is repeated in various parts (algorithms) of 3.5 but never really introduced. editorial

  • (11) The separation between indexing and general processing concerns in 3.5.3 is really neat. I
    m wondering however whether we could express a bit better how these things can work together. I.e. it's not clear that 'indexing' is one of the processing that can happen in step 4.3 in the Page Algorithm. editorial

  • (12) I am still puzzled about the approach to negotiable resources across the board. I understand the group has decided to enforce the use of representation-URI (issue #46). I don't like this being mandatory, but can abide, especially if there's an option to indicate canonical resource URIs (#48).
    Still I am wondering whether what is said in 4.2 needs to apply to all resources, including for example seeAlso for dataset URIs (in section 3.1).
    Again I do not like that it's all about representation-URIs. But if the group supports that approach, then I think it should be clear in 4.2, as 4.2 is written with a strong focus on the resources that are the primary object of activities. And if the group is open to using non-information-resource URIs in some places, then it should be clear in 4.2 too :-) editorial

aisaac commented

@azaroth42 is this something that could be actioned on before Ann Arbor?

azaroth42 commented

In 3.2 the "Complete Ordered Collection Page Example" could include some kind of editorial trick in the orderedItems element to indicate that it's expected to contain 20 items.

Well, that doesn't necessarily follow. There could be 52 items in this page, as page size doesn't need to be consistent. Have added that as a normative, if negative, assertion in 3.2

In 3.3 is the example of seeAlso for object really ok?

Yes, clarified that Dataset is used to mean "data" as opposed to "human readable document".
See: https://iiif.io/api/presentation/3.0/#seealso

In 3.4.1 we should add an editor's note saying that "http://iiif.io/api/discovery/0/context.json" is not going to be the final URI.

I changed it to be .../1/context.json so that it's the real URI.
Why? Because contexts aren't semantically versioned. So we can change /1/ to be whatever is in /1/. This also means we won't have the same issue that we do with Auth /0/ being used in several places, years after /1/ became the official version.

The reason for conneg as it is written is that there is likely to be multiple major versions of the same manifest available at institutions, and they will not necessarily be kept in sync. Thus a change to a manifest that has audio or video resources in v3, but only has image resources in v2 would only change if the a/v resources were affected.

It also avoids the "but did the resource change or just the representation??" question ... it's always, only about representations. A new whitespace character is a new representation but clearly no change was made on the non information resource. (Not that I would expect anyone to record whitespace changes as significant... but it shouldn't be forbidden either)

aisaac commented

OK thanks for the answers!
This makes sense. Though I'm still a bit worried about discouraging the use of non-representation URIs in seeAlso. It's going to make it harder to encourage the use of say a URI for a dataset or a book across the board, if the URLs of representations are still needed.

aisaac commented

@azaroth42 where would you like me to review all other items? I see that you have ticked many of them. I guess I would need to produce a HTML diff between 0.3 and the new draft of 0.4 at IIIF/api#1879 ?

aisaac commented

@azaroth42 I've reviewed all items (after having numbered them, by the way), here's the outcome. Almost everything is handled, great work!

1 -> not dealt with. Do you really feel against creating such note? I reckon it's not ideal as the CG is not created. Should we create a new editorial issue then, specifically to make a reference to (and distinguish from) the work of the CG.
2 -> ok
3 -> my suggestion has not been implemented, but there are some good changes. Replacing the mention of 'list' by 'reference' in headings 2.1.1, 2.1.2 and 2.1.3, and adding a clarification on the order of content of sub-sections in the intro of 2.1, make the situation better. However, I still feel the flow is odd whenever 'list' is mentioned in these sub-sections, such as in 2.1.1 "The order of the resources in the resulting list is unimportant, but each should only appear once. In terms of optimization, this approach provides no additional benefit over any other simpler list format, but is compatible with the following levels which introduce significant benefits"
4 -> ok
5 -> ok (as per the above comment)
6 -> ok (as per the above comment)
7 -> ok
8 -> ok (as per the above comment)
9 -> ok
10 -> ok
11 -> ok
12 -> ok (as per the above comment)

For the record I have worked based on the diff at https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fiiif.io%2Fapi%2Fdiscovery%2F0.3%2F&doc2=https%3A%2F%2Fpreview.iiif.io%2Fapi%2Fdiscovery-04%2Fapi%2Fdiscovery%2F0.4%2F

azaroth42 commented

Thanks Antoine, I was just about to work on that! :)

  1. I changed the second paragraph of the Introduction to be clearer about the scope. Given that the CG should be created next week (🤞) or otherwise very soon, creating a note doesn't seem worthwhile right now. It would be at best speculative and need changing as soon as anything became formalized. The CG will need to create a space for profiles to be recorded, at which time we should reference that from the spec ... but I wouldn't put into a spec the details of the process by which the community is dealing with the division of labor. If the process isn't working, that would be something to solve, but not via notes in specs.

  2. I agree with the sentiment, and thus the changes, but had issues with the exact proposed edits. Having text then example then text often makes the following text hard to find and read. We've followed the text plus example pattern in all the specs, so I would be very reluctant to change it here. Also forward references are to be avoided if possible, as they don't make sense until you get to them. Sometimes they're impossible to avoid, but I think we don't need it here, as I added to the introduction of 2.1 that the following section describes how to put them into lists.

I'll add a little more prose in the second para of 2.1.1 to try and help the transition.

aisaac commented

  1. I agree. The idea of the note was not really about the community process, but to have something like "for a whole category of discovery topics that are not covered by this spec, the work of this other (coming) CG can be relevant". But as said I can create a new editorial issue for later action.

  2. (is in fact (3)) ok I'll wait!

aisaac commented

Just to note that the last issue (2 in the last comment) has been tackled.