aligned the rest of Search with Prezi3 #2057

mixterj · 2021-10-12T17:23:56Z

fixed the remaining alignment issues

created new issues to discuss and resolve in future branch:

created new issues that are resolved in this branch:

add classes Hit, TermList, and Term to Search2 context #2050 - fixed in this branch for Search 2.0
incorrect context in Search 1 section 3.3.3 #2056

mixterj · 2021-10-12T19:11:35Z

@mbennett-uoe pull request to finish up the alignment for Search API

mbennett-uoe

Thanks Jeff, I really appreciate the second pair of eyes over this, and the work to bring the Autocomplete section up to speed with the rest of the doc (my to-do list thanks you for that part as well!)

I've left a few comments about stuff I wasn't sure about - further feedback and explanations of the bits I didn't quite get my head around (from anyone) would be very welcome :)

mbennett-uoe · 2021-10-12T22:32:54Z

source/api/search/2.0/index.md

-  "selector": {
+  "selectors": {


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

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.

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!

mbennett-uoe · 2021-10-12T22:59:04Z

source/api/search/2.0/index.md

-| `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 |
 {: .api-table}


I got a bit confused when updating this section, as only painting and supplementing are defined explicitly in the Prezi3 context (since they are not part of the WebAnno spec), so my understanding was that Search2 implementations would still need to explicitly specify the oa: prefix in the motivation key for results that have one of the other values, as they are only referenced by the linked WebAnno context document.

One other thing I was unsure about, related to this section:

The Prezi2 context had a motivation block that linked to the OA spec:

"motivation": { "@type": "@id", "@id": "oa:motivatedBy" },

but nothing similar seems present in the Prezi3 context - is this because the whole Annotation object is just shunted out to the WebAnno spec, which includes the relevant definition for Motivation? (Sorry, my limited knowledge of JSON-LD is probably showing here!)

And a final thought - is it worth having extra text to explain in more detail that non-painting in the query string is expected to behave differently from all of the other possible values and/or having a discussion about whether this is the best way to implement this particular pattern? (e.g what if a client wishes to negate some other type of motivation instead? or perhaps specify a list of "acceptable" motivations?)

The context imports the Annotation context scoped to be valid only within the annotations. This is the JSON-LD 1.1 solution which solves the label: string vs label : language-map difference. So no need for the prefixes on them. Ditto for motivation.

Agree that non-painting is different -- it's an API affordance to avoid having a boolean operator to say NOT (painting) on the basis that painting annotations are a special case ... we need to consider non-supplementing as well now, and then whether there's use for non-* as a pattern.

Aha, the (scoped) penny drops - thanks Rob!

From TSG call: add supplementing to the common motivations list

mbennett-uoe · 2021-10-12T23:07:28Z

source/api/search/2.0/index.md

-          "label": "Example Manifest"
+          "label": {
+            "en": "Example Manifest"
+          }


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

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

mbennett-uoe · 2021-10-12T23:09:05Z

source/api/search/2.0/index.md

@@ -768,7 +770,6 @@ 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/


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?

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

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.

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

azaroth42 · 2021-10-13T19:08:11Z

source/api/search/2.0/index.md

-| `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 |
 {: .api-table}


The context imports the Annotation context scoped to be valid only within the annotations. This is the JSON-LD 1.1 solution which solves the label: string vs label : language-map difference. So no need for the prefixes on them. Ditto for motivation.

Agree that non-painting is different -- it's an API affordance to avoid having a boolean operator to say NOT (painting) on the basis that painting annotations are a special case ... we need to consider non-supplementing as well now, and then whether there's use for non-* as a pattern.

azaroth42 · 2021-10-13T19:09:25Z

source/api/search/2.0/index.md

-          "label": "Example Manifest"
+          "label": {
+            "en": "Example Manifest"
+          }


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

azaroth42 · 2021-10-13T19:11:51Z

source/api/search/2.0/index.md

-  "selector": {
+  "selectors": {


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.

azaroth42 · 2021-10-13T19:12:41Z

source/api/search/2.0/index.md

@@ -615,11 +617,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.  


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

azaroth42 · 2021-10-13T19:14:22Z

source/api/search/2.0/index.md

@@ -768,7 +770,6 @@ 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/


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

glenrobson · 2021-10-19T17:01:47Z

It might be worth adding a warning banner like we used to have for 3.0 before it reached beta and release. It was taken out of 3.0 here:

3178a02

aligned the rest of Search with Prezi3

d8225ad

mixterj requested review from azaroth42, jpstroop, kirschbombe, mcwhitaker, mikeapp, tomcrane and zimeon October 12, 2021 19:00

mbennett-uoe reviewed Oct 12, 2021

View reviewed changes

mbennett-uoe mentioned this pull request Oct 12, 2021

incorrect context in Search 1 section 3.3.3 #2056

Closed

azaroth42 reviewed Oct 13, 2021

View reviewed changes

added TSG changes

0502a24

mixterj merged commit 37a5f40 into search-v3-alignment Oct 26, 2021

azaroth42 deleted the search-v3-alignment-autocomplete branch February 24, 2023 17:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

aligned the rest of Search with Prezi3 #2057

aligned the rest of Search with Prezi3 #2057

mixterj commented Oct 12, 2021

mixterj commented Oct 12, 2021

mbennett-uoe left a comment

mbennett-uoe Oct 12, 2021

azaroth42 Oct 13, 2021

mbennett-uoe Oct 13, 2021 •

edited

Loading

mbennett-uoe Oct 12, 2021

mbennett-uoe Oct 12, 2021

mbennett-uoe Oct 12, 2021

azaroth42 Oct 13, 2021

mbennett-uoe Oct 13, 2021

mbennett-uoe Oct 19, 2021

mbennett-uoe Oct 12, 2021

azaroth42 Oct 13, 2021

mbennett-uoe Oct 12, 2021

azaroth42 Oct 13, 2021

mbennett-uoe Oct 13, 2021

mbennett-uoe Oct 19, 2021

azaroth42 Oct 13, 2021

azaroth42 Oct 13, 2021

azaroth42 Oct 13, 2021

azaroth42 Oct 13, 2021

azaroth42 Oct 13, 2021

glenrobson commented Oct 19, 2021

aligned the rest of Search with Prezi3 #2057

aligned the rest of Search with Prezi3 #2057

Conversation

mixterj commented Oct 12, 2021

mixterj commented Oct 12, 2021

mbennett-uoe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbennett-uoe Oct 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glenrobson commented Oct 19, 2021

mbennett-uoe Oct 13, 2021 •

edited

Loading