IIIF Search 2.0

[glenrobson]

Links

• Original Issue: Search 2.0 Issues - (13 closed)
• Pull Request: https://github.com/IIIF/api/pull/2005
• Preview: https://preview.iiif.io/api/search-v3-alignment/search/2.0/

Background and Summary

This release of Search v2.0 will align the Content Search specification with Image and Presentation v3.0. This means:

• Supporting Web Annotations
• Using v3 language maps
• Using the items property
• using id and type rather than straight Ids

Support for searching AV annotations will come in the next version of the Search API v3.0 so that the version numbers align with the Presentation and Image APIs and it will make it easier to spot compatible versions.

The extra features we hope to add to Search v3 are listed against the following Milestone:

https://github.com/IIIF/api/milestone/15

The search group would appreciate any comments and plus 1s for features you would like to be supported.

Proposed Solution

The Content Search TSG would like you to approve the release of Search 2.0.

[julsraemy]

Like in the Acknowledgements' Change Discovery API 1.0 , it would be great to thank the Content State TSG and their co-chairs in the Content Search API 2.0.

[kirschbombe]

@julsraemy Agreed! We discussed this and are considering how to account for editors, authors, and contributors. We'll take a look at the Change Discovery acknowledgements.

[digitaldogsbody]

NB: We also changed the JSON-LD context file to extend from the Presentation API context

[thehabes]

Sorry to take so long to look at this!

Here are constructive thoughts

• A wise choice I commend you. Now you are LD 1.1 compliant. > NB: We also changed the JSON-LD context file to extend from the Presentation API context
• I do not see the Search API context.json used as a value in any @context property, even in the JSON snippets specifically using the terms defined there. Is it not necessary when the presentation 3 context is the value of @context?
• I see the term TermPage used, but there is no entry for that term in the Search context.json.
• I see the term TermList defined in the Search context.json, but it is not used. It seems to have been replaced by TermPage per section 5.2.
• I see the terms match, count, terms and url defined in the Search context, but they are not used as a property and are not defined/used by the search API...is it more of a terminology term than a property (JSON key) or have these been deprecated?
• It took me a little bit to realize totals, first, last, next, prev, exact were defined by the https://www.w3.org/ns/anno.jsonld part of the prezi 3 context...not sure I have a suggestion it just took me a second and could be a user flaw.
• Will SearchService2 and AutoCompleteService2 be added to the Presentation API context?
• Double check capitalization around the words 'annotation' and 'annotations'. They are core to this API, so it is worth getting the capitalization correct to help the user know when you mean an AnnotationPage.items[{"type":"Annotation"]} vs a less serious use of the general noun that is 'annotation/s'.
• Be very careful with "Collection" so as not to confuse IIIF Collection vs Annotation Collection. One phrase in particular caught my attention : "The Annotation Collection may have a total property. The value is an integer, which is the total number of Annotations in the Collection, across all Annotation Pages."
• The label in the JSON snippet in section 4.2.3 is not a proper language map.

All of that said, I agree you pivoted towards existing Linked Data principles as other IIIF API pieces have been tending to do. It was understandable and I feel like I could pick it up and start using it quickly. None of the points above changed that, and so I am +1 and hope you take my comments into consideration when you put the final polish on it.

[regisrob]

Small suggestion for 4.2.2. Paging Results (2nd paragraph): avoid any possible confusion about the term "page" by putting "Annotation Page" explicitely ?

... a page query parameter to be appended to the URI to allow the server to track which page is being requested."

[regisrob]

The user parameter is meant to be A space separated list of URIs..., but there are two inconsistent examples:

• http://example.org/service/manifest/search?q=bird&user=myusername (4.2.4. Ignored Parameters)
• https://example.org/service/identifier/autocomplete?q=bir&user=wigglesworth (5.3. Extended Autocomplete Responses)

... whereas the example in "5.1. Autocomplete Request" gives a URI (https://example.org/service/identifier/autocomplete?q=bir&motivation=painting&user=http%3A%2F%2Fexample.com%2Fusers%2Fwigglesworth)

[glenrobson]

Issue 93 (IIIF Search 2.0)

+1: 21 [akrishnan15 cubap eliotjordan hadro ioanrichards irv jpadfield jtweed julsraemy kirschbombe ksclarke markpatton mikeapp mixterj nfreire omaeazusa regisrob thehabes tpendragon triplingual zimeon] 0: 0 [] -1: 0 [] Not TRC: 1 [mathewjordan] Ineligible: 6 [azaroth42 digitaldogsbody mattmcgrattan rsinghal scossu tomcrane]

Result: 21 / 21 = 1.00

Super majority is in favor, issue is approved

[digitaldogsbody]

Thanks for the feedback everyone. We discussed it in the Content Search TSG call on 2022-07-26 and some changes are pending.

I do not see the Search API context.json used as a value in any @context property, even in the JSON snippets specifically using the terms defined there. Is it not necessary when the presentation 3 context is the value of @context?

A slight oversight :sweat_smile: The Search context now extends the Prezi3 context, so the examples will be changed to use this instead.

I see the term TermPage used, but there is no entry for that term in the Search context.json. I see the term TermList defined in the Search context.json, but it is not used. It seems to have been replaced by TermPage per section 5.2.

Good spot - this will be corrected.

I see the terms match, count, terms and url defined in the Search context, but they are not used as a property and are not defined/used by the search API...is it more of a terminology term than a property (JSON key) or have these been deprecated?

count will become total, match may be redefined, terms and url are deprecated and will be removed.

Will SearchService2 and AutoCompleteService2 be added to the Presentation API context?

Yes, but this is outside the scope of the PR to approve Search 2. Now that it has been approved, these will be added when it is published.

The label in the JSON snippet in section 4.2.3 is not a proper language map.

Good spot, thank you! We will fix this.

Small suggestion for 4.2.2. Paging Results (2nd paragraph): avoid any possible confusion about the term "page" by putting "Annotation Page" explicitely ?

We agreed to this change in the TSG call, as a good increase to the clarity of the working.

The user parameter is meant to be A space separated list of URIs..., but there are two inconsistent examples:

Thanks, these will be corrected :)