Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

aligned the rest of Search with Prezi3 #2057

Merged
merged 2 commits into from
Oct 26, 2021
Merged

aligned the rest of Search with Prezi3 #2057

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8225ad
aligned the rest of Search with Prezi3
Oct 12, 2021
0502a24
added TSG changes
Oct 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions source/_includes/links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@
[org-w3c-webanno-protocol]: http://w3.org/TR/annotation-protocol/ "Web Annotation Protocol"
[org-w3c-webanno]: http://w3.org/TR/annotation-model/ "Web Annotation Model"
[org-w3c-webanno-motivation]: https://www.w3.org/TR/annotation-model/#motivation-and-purpose "Web Annotation Model - Motivation"
[org-w3c-webanno-TextQuoteSelector]: https://www.w3.org/TR/annotation-model/#text-quote-selector "Web Annotation Model - Text Quote Selector"
[org-w3c-webarch]: http://www.w3.org/TR/webarch/ "Architecture of the World Wide Web"
[org-w3c-xsd-datetime]: https://www.w3.org/TR/xmlschema11-2/#dateTime "XSD DateTime"
[org-wsgi-pep333]: https://www.python.org/dev/peps/pep-0333/ "PEP 0333"
Expand Down
72 changes: 39 additions & 33 deletions source/api/search/2.0/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,12 +128,13 @@ Common values for the motivation parameter are:

| Motivation | Definition |
| ---------- | ---------- |
| `painting` | Only annotations with the `sc:painting` motivation |
| `non-painting` | Annotations with any motivation other than `sc:painting` |
| `commenting` | Annotations with the `oa:commenting` motivation |
| `describing` | Annotations with the `oa:describing` motivation |
| `tagging` | Annotations with the `oa:tagging` motivation |
| `linking` | Annotations with the `oa:linking` motivation |
| `painting` | Only annotations with the `painting` motivation |
| `non-painting` | Annotations with any motivation other than `painting` |
| `commenting` | Annotations with the `commenting` motivation |
| `describing` | Annotations with the `describing` motivation |
| `tagging` | Annotations with the `tagging` motivation |
| `linking` | Annotations with the `linking` motivation |
| `supplementing`| Annotations with the `supplementing` motivation |
{: .api-table}

Other motivations are possible, and the full list from the [Web Annotation][webanno] specification _SHOULD_ be available by dropping the "oa:" prefix. Other, community specific motivations _SHOULD_ include a prefix or use their full URI.
Expand Down Expand Up @@ -222,10 +223,10 @@ And the responses for the Annotation Collection and the first page of annotation
"@context":"http://iiif.io/api/presentation/{{ site.presentation_api.stable.major }}/context.json",
"id":"http://example.org/service/manifest/search?q=bird&page=1",
"type":"AnnotationPage",

"partOf": "http://example.org/service/manifest/search?q=bird",
"next": "http://example.org/service/identifier/search?q=bird&page=2",

"items": [
{
"id": "http://example.org/identifier/annotation/anno-line",
Expand All @@ -252,7 +253,7 @@ This structure is called out explicitly as although it uses only properties from

``` json-doc
{
"@context":"http://iiif.io/api/search/{{ page.major }}/context.json",
"@context":"http://iiif.io/api/presentation/{{ site.presentation_api.stable.major }}/context.json",
"id":"http://example.org/service/manifest/search?q=bird&motivation=painting",
"type":"AnnotationPage",

Expand All @@ -271,7 +272,9 @@ This structure is called out explicitly as although it uses only properties from
"partOf": {
"id": "http://example.org/identifier/manifest",
"type": "Manifest",
"label": "Example Manifest"
"label": {
"en": "Example Manifest"
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the reason this @context and label were left as is is exactly because of the clash between label as defined by the WebAnno spec and label as defined for Prezi3. I will try to dig out the call notes where we discussed this, as I can't remember if we reached a decision about the best route forwards

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's scoped to the class that has the label. So if it's label on a Manifest, then it's a language map.

}
}
}
Expand All @@ -289,7 +292,7 @@ As these responses include Search specific information, the value of `@context`

To incrementally build upon existing solutions and provide graceful degradation for clients that do not support these features and retain compatibility with the Presentation API, the search API specific information is included in a second list within the annotation list called `hits`, other than the `ignored` property. Annotation lists _MAY_ have this property, and servers _MAY_ support these features.

If supported, each entry in the `hits` list is a `search:Hit` object. This type _MUST_ be included as the value of the `type` property. Hit objects reference one or more annotations that they provide additional information for, in a list as the value of the hit's `items` property. The reference is made to the value of the `id` property of the annotation, and thus annotations _MUST_ have a URI to enable this further information.
If supported, each entry in the `hits` list is a `Hit` object. This type _MUST_ be included as the value of the `type` property. Hit objects reference one or more annotations that they provide additional information for, in a list as the value of the hit's `items` property. The reference is made to the value of the `id` property of the annotation, and thus annotations _MUST_ have a URI to enable this further information.

The basic structure is:

Expand All @@ -316,7 +319,7 @@ The basic structure is:

"hits": [
{
"type": "search:Hit",
"type": "Hit",
"items": [
"http://example.org/identifier/annotation/anno1"
]
Expand Down Expand Up @@ -352,9 +355,9 @@ And the user parameter was ignored when processing the request, the response wou

"partOf": "http://example.org/service/manifest/search?q=bird",
"next": "http://example.org/service/identifier/search?q=bird&page=2",

"ignored": ["user"],

"items": [
// Annotations ...
]
Expand Down Expand Up @@ -385,13 +388,13 @@ That the server matches against the plural "birds":
"http://iiif.io/api/search/{{ page.major }}/context.json"
],
"id":"http://example.org/service/manifest/search?q=bird",
"type":"sc:AnnotationPage",
"type":"AnnotationPage",

"resources": [
{
"id": "http://example.org/identifier/annotation/anno-bird",
"type": "Annotation",
"motivation": "sc:painting",
"motivation": "painting",
"body": {
"type": "TextualBody",
"value": "birds",
Expand All @@ -404,7 +407,7 @@ That the server matches against the plural "birds":

"hits": [
{
"type": "search:Hit",
"type": "Hit",
"items": [
"http://example.org/identifier/annotation/anno-bird"
],
Expand All @@ -421,13 +424,13 @@ That the server matches against the plural "birds":

Many systems do not have full word-level coordinate information, and are restricted to line or paragraph level boundaries. In this case the most useful thing that the client can do is to display the entire annotation and highlight the hits within it. This is similar, but different, to the previous use case. Here the word will appear somewhere within the `body` property of the annotation, and the client needs to make it more prominent. In the previous situation, the word was the entire content of the annotation, and the information was convenient for presenting it in a list.

The client in this case needs to know the text that caused the service to create the hit, and enough information about where it occurs in the content to reliably highlight it and not highlight non-matches. To do this, the service can supply text before and after the matching term within the content of the annotation, via an [Open Annotation][oa-textquotesel] `TextQuoteSelector` object. TextQuoteSelectors have three properties: `exact` to record the exact text to look for, `prefix` with some text before the match, and `suffix` with some text after the match.
The client in this case needs to know the text that caused the service to create the hit, and enough information about where it occurs in the content to reliably highlight it and not highlight non-matches. To do this, the service can supply text before and after the matching term within the content of the annotation, via an [Web Annotation Data Model][webanno] `TextQuoteSelector` object. TextQuoteSelectors have three properties: `exact` to record the exact text to look for, `prefix` with some text before the match, and `suffix` with some text after the match.

This would look like:

``` json-doc
{
"selector": {
"selectors": {
Comment on lines -430 to +433
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this stay as the singular selector? That is how it appears in the WebAnno example I cribbed from when updating this section: https://www.w3.org/TR/annotation-model/#text-quote-selector

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No - selector would mean that the entity which has it is a SpecificResource, which is not what this is. I think there's a discussion to be had on how to translate Hit into a more connected environment, rather than just as a syntactic API affordance.

Copy link
Contributor

@mbennett-uoe mbennett-uoe Oct 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, that makes sense. Does this mean we would have to define/scope selectors in the Search context file? ETA: It's already there, oops!

"type": "TextQuoteSelector",
"exact": "birds",
"prefix": "There are two ",
Expand Down Expand Up @@ -471,7 +474,7 @@ The result might be:

"hits": [
{
"type": "search:Hit",
"type": "Hit",
"items": [
"http://example.org/identifier/annotation/anno-line"
],
Expand Down Expand Up @@ -542,7 +545,7 @@ In cases like this there are more annotations than hits as two or more annotatio

"hits": [
{
"type": "search:Hit",
"type": "Hit",
"items": [
"http://example.org/identifier/annotation/anno-bush",
"http://example.org/identifier/annotation/anno-are"
Expand All @@ -567,17 +570,17 @@ The autocomplete service returns terms that can be added into the `q` parameter

The autocomplete service is nested within the search service that it provides term completion for. This is to allow multiple search services, each with their own autocomplete service.

The autocomplete service _MUST_ have an `@id` property with the value of the URI where the service can be interacted with, and _MUST_ have a `profile` property with the value "http://iiif.io/api/search/{{ page.major }}/autocomplete" to distinguish it from other types of service.
The autocomplete service _MUST_ have an `id` property with the value of the URI where the service can be interacted with, and _MUST_ have a `profile` property with the value "http://iiif.io/api/search/{{ page.major }}/autocomplete" to distinguish it from other types of service.

``` json-doc
{
// Resource that the services are associated with ...
"service": {
"@context": "http://iiif.io/api/search/{{ page.major}}/context.json",
"@id": "http://example.org/services/identifier/search",
"id": "http://example.org/services/identifier/search",
"profile": "http://iiif.io/api/search/{{ page.major }}/search",
"service": {
"@id": "http://example.org/services/identifier/autocomplete",
"id": "http://example.org/services/identifier/autocomplete",
"profile": "http://iiif.io/api/search/{{ page.major }}/autocomplete"
}
}
Expand Down Expand Up @@ -615,11 +618,11 @@ http://example.org/service/identifier/autocomplete?q=bir&motivation=painting&use
### 4.3. Response
{: #response}

The response is a list (a "search:TermList") of simple objects that include the term, a link to the search for that term, and the number of matches that search will have. The number of terms provided in the list is determined by the server.
The response is a list (a "TermList") of simple objects that include the term, a link to the search for that term, and the number of matches that search will have. The number of terms provided in the list is determined by the server.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly, question as to what a TermList and Term is in a more connected environment. Can we map them to something more semantic?


Parameters that were not processed by the service _MUST_ be returned in the `ignored` property of the main "TermList" object. The value _MUST_ be an array of strings.

The objects in the list of terms are all of `type` "search:Term", and this _MAY_ be included explicitly but is not necessary. The Term object has a number of possible properties:
The objects in the list of terms are all of `type` "Term", and this _MAY_ be included explicitly but is not necessary. The Term object has a number of possible properties:

* The matching term is given as the value of the `match` property, and _MUST_ be present.
* The link to the search to perform is the value of the `url` property, and this _MUST_ be present.
Expand All @@ -634,8 +637,8 @@ The example request above might generate the following response:
``` json-doc
{
"@context": "http://iiif.io/api/search/{{ page.major }}/context.json",
"@id": "http://example.org/service/identifier/autocomplete?q=bir&motivation=painting",
"@type": "search:TermList",
"id": "http://example.org/service/identifier/autocomplete?q=bir&motivation=painting",
"type": "TermList",
"ignored": ["user"],
"terms": [
{
Expand Down Expand Up @@ -667,20 +670,24 @@ It is also possible to associate one or more `label`s to display to the user wit
``` json-doc
{
"@context": "http://iiif.io/api/search/{{ page.major }}/context.json",
"@id": "http://example.org/service/identifier/autocomplete?q=http%3A%2F%2Fsemtag.example.org%2Ftag%2Fb&motivation=tagging",
"id": "http://example.org/service/identifier/autocomplete?q=http%3A%2F%2Fsemtag.example.org%2Ftag%2Fb&motivation=tagging",
"ignored": ["user"],
"terms": [
{
"match": "http://semtag.example.org/tag/bird",
"url": "http://example.org/service/identifier/autocomplete?motivation=tagging&q=http%3A%2F%2Fsemtag.example.org%2Ftag%2Fbird",
"count": 15,
"label": "bird"
"label": {
"none": "bird"
}
},
{
"match": "http://semtag.example.org/tag/biro",
"url": "http://example.org/service/identifier/autocomplete?motivation=tagging&q=http%3A%2F%2Fsemtag.example.org%2Ftag%2Fbiro",
"count": 3,
"label": "biro"
"label": {
"none": "biro"
}
}
]
}
Expand Down Expand Up @@ -768,9 +775,8 @@ Many thanks to the members of the [IIIF][iiif-community] for their continuous en
[prezi-annocollection]: {{ site.url }}{{ site.baseurl }}/api/presentation/{{ site.presentation_api.stable.major }}.{{ site.presentation_api.stable.minor }}/#58-annotation-collection
[prezi-layer]: {{ site.url }}{{ site.baseurl }}/api/presentation/{{ site.presentation_api.stable.major }}.{{ site.presentation_api.stable.minor }}/#layer
[ignored-parameters]: #ignored-parameters
[oa-textquotesel]: http://www.openannotation.org/spec/core/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth adding a direct link to the TextQuoteSelector section of the WebAnno spec (https://www.w3.org/TR/annotation-model/#text-quote-selector) to replace this, rather than using the link to the whole spec?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think having the whole spec is valuable -- the annotations are the core of the search, after all.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I was thinking to have two links, one for webanno (because it's referenced in several other places) and a more specific webanno-textquote that could be used in L426 for linking directly to the relevant part of the spec when we talk about the TextQuoteSelector construct.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TSG call: Add this link as a convenience in line with usage of other anchor links in the spec

[webanno]: https://www.w3.org/TR/annotation-model/ "Web Annotation"

[org-w3c-webanno-TextQuoteSelector]: https://www.w3.org/TR/annotation-model/#text-quote-selector "Web Annotation Model - Text Quote Selector"
[icon-req]: {{ site.url }}{{ site.baseurl }}/img/metadata-api/required.png "Required"
[icon-rec]: {{ site.url }}{{ site.baseurl }}/img/metadata-api/recommended.png "Recommended"
[icon-opt]: {{ site.url }}{{ site.baseurl }}/img/metadata-api/optional.png "Optional"
Expand Down
5 changes: 3 additions & 2 deletions source/api/search/2/context.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
{
"@context": {
"search": "http://iiif.io/api/search/2#",

"ignored": {"@id": "search:ignored", "@container": "@set"},
"match": {"@id": "search:match"},
"before": {"@id": "search:before"},
"after": {"@id": "search:after"},
"count": {"@id": "search:count"},

"Hit": {"@id": "search:Hit"},
"TermList": {"@id": "search:TermList"},
"Term": {"@id": "search:Term"},
"hits": {"@id": "search:hasHitList", "@container": "@list", "@type": "@id"},
"terms": {"@id": "search:hasTermList", "@container": "@list", "@type": "@id"},
"annotations": {"@id": "search:refines", "@container": "@set", "@type": "@id"},
Expand Down