Review Georeference service design document

[GroovinChip]

66

[GroovinChip]

I have read this document. The annotations look good to me. Per my update for #72, though, I cannot use them yet.

[htpvu]

duplicate of #67

[jabrah]

Could we include some extra data to link the Pleiades URL to its associated JSON data? For example, an identifying URL in one of the annotations is http://pleiades.stoa.org/places/570527 and its JSON endpoint is http://pleiades.stoa.org/places/570527/json. We could add this as a seeAlso property on the annotation.

{
  "id": "https://rosetest.library.jhu.edu/rosademo/wa/homer/VA/VA035RN-0036/canvas/annotation",
  "type": "Annotation",
  "label": "Georeference data for Venetus A VA035RN-0036 text \"Oetylus\"",
  "creator": "https://recogito.pelagios.org/chiara-p",
  "seeAlso": [
    {
      "id": "http://pleiades.stoa.org/places/570527/json",
      "label": "Pleiades data for \"Oetylus\"",
      "type": "PleiadesJSON",
      "format": "application/json"
    }
  ],
  "body": [
    {
      "purpose": "identifying",
      "source": "http://pleiades.stoa.org/places/570527",
      "format": "text/html"
    }
  ],
  ...
}

Including this explicitly in the annotation would prevent the client from "just knowing" that the JSON endpoint exists. This may not be too big of an issue, though, since any component that uses this data would need customizations in order to parse the JSON.

[markpatton]

We could use seeAlso. It is part of the vocabulary with namespace http://www.w3.org/1999/02/22-rdf-syntax-ns# which is set in the IIIF context. If we followed our current pattern, we could just set it in our included context.

Another alternative is to use the service endpoint directly as the external resource id with a format of application/json. I'd be curious if @jacobwegner has any thoughts.

[jacobwegner]

I'm open to either approach, but I prefer the idea of using the service endpoint directly.

The "identifying url" supports content negotiation:

curl -L -H "Accept: application/json" https://pleiades.stoa.org/places/570527

So we might also consider:

"body": [
    ...
    {
        "purpose": "identifying",
        "source": "http://pleiades.stoa.org/places/570527",
        "format": "application/json"
    }
]

[markpatton]

@jacobwegner In fact we can model that the client should set an Accept header. See https://www.w3.org/TR/annotation-model/#request-header-state

[jacobwegner]

@markpatton I'm fine with either:

1) What you've deployed using request header state (great find by the way!)

"body": [
  {
  "purpose": "identifying",
  "source": "http://pleiades.stoa.org/places/550823",
  "state": {
      "type": "HttpRequestState",
      "value": "Accept: application/json"
  }
]

or

2) Multiple bodies

"body": [
    ...
    {
        "purpose": "identifying",
        "source": "http://pleiades.stoa.org/places/570527/json",
        "format": "application/json"
    },
    {
        "purpose": "identifying",
        "source": "http://pleiades.stoa.org/places/570527",
        "format": "text/html"
    }
]

HttpRequestState seems a better way to indicate how to retrieve the JSON content than in my previous content

To @jabrah's point, there is still some work for a client to parse the content, but using one or the other of the above implementations makes it clear what type of content is coming back.

[jacobwegner]

(whatever format we decide on, I'm happy to mirror it within the ATLAS Named Entity annotation for the Wikipedia URLs, as far as an HTML or JSON representation)

https://explorehomer-feature-na-4qbljt.herokuapp.com/wa/urn:cite2:hmt:msA.v1:12r/named-entities/0/compound/