Notifications via WebMention

164 views
Skip to first unread message

Robert Sanderson

unread,
Jan 12, 2016, 1:29:37 PM1/12/16
to iiif-d...@googlegroups.com

At Ghent there was some after hours discussion about using WebMention to share notifications between systems, particularly when there is content such as annotations that refer to remotely hosted resources, or new structure to be added to a collection or manifest.

The W3C Social Web WG has just released a First Public Working Draft of WebMention:  http://w3.org/TR/webmention/

If there are any comments on it, please either let me know or reply here.  I'm a member of the WG and can relay any issues :)

Rob

--
Rob Sanderson
Information Standards Advocate
Digital Library Systems and Services
Stanford, CA 94305

Robert Sanderson

unread,
Jan 12, 2016, 6:03:26 PM1/12/16
to iiif-d...@googlegroups.com

Some further thinking about notifications and WebMention, in search of comments and discussion :)

Use Case 1:
  A scholar knows of images or other content that should be rendered as part of a canvas.  In order to maintain the annotations under her own control, she creates the links in her own publicly accessible annotation store.  She wants to notify the institution that hosts the manifest that she has created these annotations about the canvases.

Use Case 2:
  A scholar creates additional structural descriptions (ranges, layers etc) that the host manifest does not currently have.  He publishes them on a system he controls and wants to notify the institution that hosts the manifest that they exist and could be integrated.

How WebMention could play a role:

WebMention is about as simple a protocol as you can get.  It has two fields, which are form-encoded and POSTed to an endpoint.  The fields are source (the thing referring to something) and target (the thing being referred to).  Thus in UC1 about the annotation's URI would be the source and the Canvas's URI the target. In UC2, the Range and Manifest, respectively.  The same endpoint can thus be used for multiple resources for targets, rather than necessarily sending it to the target URI directly.

The receiving server then GETs the source URI and can do whatever it wants with the content.  Typically in the current implementations, it just creates a link saying that some user commented, but here more could be done.  

Some notes:

* It's not JSON-LD, and it's only marginally RESTful. 
* We could add a service link with the webmention endpoint in the manifest.
* It's going to change ... the first public working draft is the equivalent of a IIIF 0.x state ... but likely not very much.




Jeffrey C. Witt

unread,
Jan 14, 2016, 10:53:00 AM1/14/16
to IIIF Discuss
Rafael Schwimmer and I have been discussion a demo and below is a write up of some of the ways we are currently thinking about this. 

Let's say I'm going to be in the business of publishing "range lists" (or for that matter a "search within service" and the range list for the e-codices ms of William de Rothwell's Commentary on the Sentences is published at http://scta.info/iiif/wdr-wettf15/rangelist.

First, I think I need to wrap my "structures" array in an object that has a few other pieces of information. It seems like there should be an @id property corresponding to the actual de-referenced url, like: @id: "http://scta.info/iiif/wdr-wettf15/rangelist". But secondly, and most important for a successful a webmention, is a place to put the reference to another published manifest (or multiple manifests) to which this range might apply, like 'manifests': []. Finally, I think we also need to specify a @type so that the listening surface can figure of if this is a set of ranges (i.e.. structures object) or a search within service or something else. 

(See example below.)

Based on the examples of webmentions I see on the web, the manifest id would function like a link to an article that I placed in my blog post and that I want my webmention service to follow, parse to see if there is an available receiving webmention endpoint, and then send the POST notification to the discovered endpoint.

So using the ruby library https://github.com/indieweb/mention-client-ruby I should be able to run a manual webmention announcement with the command.

$ webmention http://scta.info/iiif/wdr-wettf15/rangelist

In the mention-client-ruby library, this command fires a script that will crawl http://scta.info/iiif/wdr-wettf15/rangelist for all absolute urls. It is then going to follow each of these links and try to see if their is a corresponding endpoint.

I have modified the script at this point so that it only follow links listed in the "manifest": []" array (because we don't want checks being sent to every url for every canvas). 

Finally, my service will need to know where in the manifest to look for the endpoint. I would expect this to be an external service property attached to the manifest object with an "@type" or "profile" of "webmention" or something like that. So, my script should be able to find this by parsing the manifest within something like "manifest["service"], and then filtering the results for the service with the "@type"/"profile": "webmention" property. 

Once, done the rest of the discovery should be completed automated. 

So here's example of the the rangelist I want to publish and which I want the e-codices listening service to be able to parse.

I have wrapped the "structures" property in an object called "supplment" (as in "supplement" to another manifest) and then added "@id", "@type" and "manifests" properties. 

For the moment I've just made up a type called "sc:rangelist". If I was announcing the existence of a search within service. I would probably use a type like: "sc:search". If the "sc:search" type was used the supplement object would not have a "structures" property, but what would have a "service" property that the e-codices listening service would know how to parse (again based on they specificed @type) and then place within its own manifest.

"supplement": {
"@type": "sc:rangelist"
"structures": [
    {
      "@type": "sc:Range",
      "label": "Commentary",
      "canvases": [
      ]
    },
    {
      "@type": "sc:Range",
      "label": "Librum I, Prologus",
      "canvases": [
      ]
    },
    {
      "@type": "sc:Range",
      "label": "Librum I, Distinctio 1",
      "canvases": [
      ]
    },
    {
      "@type": "sc:Range",
      "label": "Librum I, Distinctio 2",
      "canvases": [
      ]
    },
    {
      "@type": "sc:Range",
      "label": "Librum I, Distinctio 3",
      "canvases": [
      ]
    }
  ]
}

Rafael Schwemmer

unread,
Jan 16, 2016, 1:59:57 PM1/16/16
to IIIF Discuss
What Jeffrey and I are trying to implement as a proof of concept is Use Case 2 as described by Rob. I now have added the following service to all e-codices manifests at the top level of the manifest:

service: {
 @type: "webmention",
 label: "Webmention Receiver"
}

So we are linking to an external service as described here: http://iiif.io/api/annex/services/. The type is "webmention" and the endpoint is http://www.e-codices.unifr.ch/webmention/receive. This service accepts POST requests with two fields, source and target. The value for each field MUST be a URI. The service validates the request by checking that the required POST parameters are set, that the values are valid URIs and that the target exists on e-codices. If all criteria are met, it responds with an HTTP status code of 202 ("Accepted") and adds the webmention request to a queue. If the request is not valid, it responds with a 400 ("Bad Request") and a corresponding message such as "required parameters missing" or "target does not exist" etc.

The reason why the response code is 202 and not the standard 200 ("OK") is that webmention requests should be processed asynchronously to prevent DoS attacks as described here: https://github.com/converspace/webmention/. This is also why – upon receipt of the request – all I do is validating the target and adding them to a queue.

Does this make sense so far? If yes, please go ahead and send some requests to the webmention service.

The next steps to implement on our side then, I think, will be the following:
  • Notify admins of new webmention requests
  • Add a UI for admins to process the webmention requests
  • Illegitimate requests can be deleted from the queue without being processed – these are highly unlikely to occur as we only accept requests for valid targets (only manifests, for now)
  • The processing of each webmention request will be somehow triggered (automatically or manually) and the processing would look something like this:
    • GET the source of the webmention
    • Determine the type of the source (range, search within, annotation, etc.)
    • Check the type of the target (manifest or canvas)
    • Remove the webmention request from the queue and add a record to a DB table or JSON file etc. with source, target, source type, target type and a timestamp
    • Let admins approve the use (display) of the "supplement" (range list, annotation etc.) in the front-end UI
    • If an admin approved the use of the supplement, the front-end UI (e.g. the viewer) would display a range list as a table of contents or an annotation for a canvas or a search input field for a "search within" service
Another thing we could do with the "supplement" is adding it back (or linking it) to the original manifest, for example if it was a "search within" service, we could just add it as another service at manifest level. If we receive multiple range lists from different sources, however, it gets a bit complicated and I am not sure if it would make sense to put these back into the manifest. The advantage, if we added them, would be that when opening the manifest in a IIIF viewer such as Mirador the supplement data would be available in the form of a table of contents etc. I think if we were to link to these external "supplements" in the manifest, they should be clearly labelled as "external" or similar, so that clients could decide whether to show original content only or include external content.

Let me know what you think. All feedback is welcome!

Thanks,
Rafael

Simeon Warner

unread,
Jan 21, 2016, 3:08:18 PM1/21/16
to iiif-d...@googlegroups.com
Hi Rafael, Jeffrey,

This is cool! Having just read the webmention spec I wonder about the
use of an IIIF service to specify the endpoint, it seems a rather
IIIF-specific way to specify the endpoint. Maybe this is necessary
because the mechanisms specified [1] for conveying endpoint (HTTP Link
Header, <link> or <a>) are either HTML specific or rely on HTTP headers
(and I'm perpetually confused about when they will or won't be available
to JavaScript clients...). Perhaps a point of feedback for Rob to give
is the question of whether there should be other standard ways of
specifying endpoint in non-HTML sources, or is it just HTTP header?

Also, from long and sometimes painful experience with trackbacks on
arXiv.org, you might want to consider an automated check that the source
refers to the target. This has proved our most effective anti-spam check.

Cheers,
Simeon

[1]
https://www.w3.org/TR/webmention/#sender-discovers-receiver-webmention-endpoint

On 1/16/16 1:49 PM, Rafael Schwemmer wrote:
> What Jeffrey and I are trying to implement as a proof of concept is Use
> Case 2 as described by Rob. I now have added the following service to
> all e-codices manifests at the top level of the manifest:
>
> |
> service:{
> @context:"https://www.w3.org/TR/webmention/",
> @id:"http://www.e-codices.unifr.ch/webmention/receive",
> @type:"webmention",
> label:"Webmention Receiver"
> }
> |
>
> So we are linking to an external service as described here:
> http://iiif.io/api/annex/services/. The type is "webmention" and the
> endpoint is http://www.e-codices.unifr.ch/webmention/receive. This
> service accepts POST requests with two fields, /source/ and /target/.
> The value for each field MUST be a URI. The service validates the
> request by checking that the required POST parameters are set, that the
> values are valid URIs and that the target exists on e-codices. If all
> criteria are met, it responds with an HTTP status code of 202
> ("Accepted") and adds the webmention request to a queue. If the request
> is not valid, it responds with a 400 ("Bad Request") and a corresponding
> message such as "required parameters missing" or "target does not exist"
> etc.
>
> The reason why the response code is 202 and not the standard 200 ("OK")
> is that webmention requests should be processed asynchronously to
> prevent DoS attacks as described here:
> https://github.com/converspace/webmention/. This is also why – upon
> receipt of the request – all I do is validating the target and adding
> them to a queue.
>
> Does this make sense so far? If yes, please go ahead and send some
> requests to the webmention service.
>
> The next steps to implement on our side then, I think, will be the
> following:
>
> * Notify admins of new webmention requests
> * Add a UI for admins to process the webmention requests
> * Illegitimate requests can be deleted from the queue without being
> processed – these are highly unlikely to occur as we only accept
> requests for valid targets (only manifests, for now)
> * The processing of each webmention request will be somehow triggered
> (automatically or manually) and the processing would look something
> like this:
> o GET the source of the webmention
> o Determine the type of the source (range, search within,
> annotation, etc.)
> o Check the type of the target (manifest or canvas)
> o Remove the webmention request from the queue and add a record to
> a DB table or JSON file etc. with source, target, source type,
> target type and a timestamp
> o Let admins approve the use (display) of the "supplement" (range
> list, annotation etc.) in the front-end UI
> o If an admin approved the use of the supplement, the front-end UI
> (e.g. the viewer) would display a range list as a table of
> contents or an annotation for a canvas or a search input field
> for a "search within" service
>
> Another thing we could do with the "supplement" is adding it back (or
> linking it) to the original manifest, for example if it was a "search
> within" service, we could just add it as another service at manifest
> level. If we receive multiple range lists from different sources,
> however, it gets a bit complicated and I am not sure if it would make
> sense to put these back into the manifest. The advantage, if we added
> them, would be that when opening the manifest in a IIIF viewer such as
> Mirador the supplement data would be available in the form of a table of
> contents etc. I think if we were to link to these external "supplements"
> in the manifest, they should be clearly labelled as "external" or
> similar, so that clients could decide whether to show original content
> only or include external content.
>
> Let me know what you think. All feedback is welcome!
>
> Thanks,
> Rafael
>
> --
> -- You received this message because you are subscribed to the
> IIIF-Discuss Google group. To post to this group, send email to
> iiif-d...@googlegroups.com. To unsubscribe from this group, send
> email to iiif-discuss...@googlegroups.com. For more options,
> visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
> ---
> You received this message because you are subscribed to the Google
> Groups "IIIF Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to iiif-discuss...@googlegroups.com
> <mailto:iiif-discuss...@googlegroups.com>.
> For more options, visit https://groups.google.com/d/optout.

Mark A. Matienzo

unread,
Jan 22, 2016, 3:22:10 PM1/22/16
to iiif-d...@googlegroups.com
Hi all, 

I'm at IndieWebCamp NYC today, and had some good conversations about Webmention and their relation to these use cases for IIIF and other potential use cases for DPLA. There seems to be some potential interest or value in articulating extensions for Webmention for use cases related to cultural heritage. 

Per Simeon's comment: 

Also, from long and sometimes painful experience with trackbacks on arXiv.org, you might want to consider an automated check that the source refers to the target. This has proved our most effective anti-spam check.

The draft spec does provide some guidance here if I'm not mistaken (see [0] and [1]).

Cheers,
Mark

Antoine Isaac

unread,
Jan 24, 2016, 9:57:14 AM1/24/16
to iiif-d...@googlegroups.com
Hi everyone,

This could be interesting. However, as I've not been following at all this sort of developments, I'll dare asking the really stupid question: what is the difference between Webmention and (semantic) pingback?

Cheers,

Antoine
> Mark A. Matienzo <ma...@matienzo.org <mailto:ma...@matienzo.org>> | http://anarchivi.st/

Mark A. Matienzo

unread,
Jan 24, 2016, 2:35:36 PM1/24/16
to iiif-d...@googlegroups.com
Hi Antoine, 

My understanding is that the community behind Webmention intends it as a replacement for for Pingback, and are no longer actively recommending Pingback itself since its so spam-prone.

I hadn't come across Semantic Pingback previously, and it looks interesting, but there are some caveats since it's not clear to me how much AKSW is actively supporting it.

- The only implementation code I can really find has been by AKSW, and generally speak  doesn't seem to be too up to date
- The two public endpoints that are mentioned on the W3C wiki page [1] are no longer up

Nonetheless it seems like there has been some activity on this and related projects on AKSW's Github organization.

Mark




To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Antoine Isaac

unread,
Jan 24, 2016, 3:54:35 PM1/24/16
to iiif-d...@googlegroups.com
Hi Mark,

I was not claiming that semantic pingpack had a huge adoption, indeed. It's been a bit marginal, unfortunately.
But a long as you trust that the community developing Webmention could be indeed looking at these older specs when designing replacement for them, then your mail answers my question. Thanks!

Cheers,

Antoine

On 1/24/16 8:35 PM, Mark A. Matienzo wrote:
> Hi Antoine,
>
> My understanding is that the community behind Webmention intends it as a replacement for for Pingback, and are no longer actively recommending Pingback itself since its so spam-prone.
>
> I hadn't come across Semantic Pingback previously, and it looks interesting, but there are some caveats since it's not clear to me how much AKSW is actively supporting it.
>
> - The only implementation code I can really find has been by AKSW, and generally speak doesn't seem to be too up to date
> - The two public endpoints that are mentioned on the W3C wiki page [1] are no longer up
>
> Nonetheless it seems like there has been some activity on this and related projects on AKSW's Github organization.
>
> Mark
>
> [1] https://www.w3.org/wiki/Pingback#Semantic_Pingback
>
>
> --
> Mark A. Matienzo <ma...@matienzo.org <mailto:ma...@matienzo.org>> | http://anarchivi.st/
>
> On Sun, Jan 24, 2016 at 9:57 AM, Antoine Isaac <ais...@few.vu.nl <mailto:ais...@few.vu.nl>> wrote:
>
> Hi everyone,
>
> This could be interesting. However, as I've not been following at all this sort of developments, I'll dare asking the really stupid question: what is the difference between Webmention and (semantic) pingback?
>
> Cheers,
>
> Antoine
>
> On 1/22/16 9:21 PM, Mark A. Matienzo wrote:
>
> Hi all,
>
> I'm at IndieWebCamp NYC today, and had some good conversations about Webmention and their relation to these use cases for IIIF and other potential use cases for DPLA. There seems to be some potential interest or value in articulating extensions for Webmention for use cases related to cultural heritage.
>
> Per Simeon's comment:
>
> Also, from long and sometimes painful experience with trackbacks on arXiv.org, you might want to consider an automated check that the source refers to the target. This has proved our most effective anti-spam check.
>
>
> The draft spec does provide some guidance here if I'm not mistaken (see [0] and [1]).
>
> Cheers,
> Mark
>
> [0] https://www.w3.org/TR/webmention/#request-verification
> [1] https://www.w3.org/TR/webmention/#webmention-verification
>
> --
> Mark A. Matienzo <ma...@matienzo.org <mailto:ma...@matienzo.org> <mailto:ma...@matienzo.org <mailto:ma...@matienzo.org>>> | http://anarchivi.st/
>
>
> --
> -- You received this message because you are subscribed to the IIIF-Discuss Google group. To post to this group, send email to iiif-d...@googlegroups.com <mailto:iiif-d...@googlegroups.com>. To unsubscribe from this group, send email to iiif-discuss...@googlegroups.com <mailto:iiif-discuss%2Bunsu...@googlegroups.com>. For more options, visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
> ---
> You received this message because you are subscribed to the Google Groups "IIIF Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com <mailto:iiif-discuss%2Bunsu...@googlegroups.com> <mailto:iiif-discuss...@googlegroups.com <mailto:iiif-discuss%2Bunsu...@googlegroups.com>>.
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> -- You received this message because you are subscribed to the IIIF-Discuss Google group. To post to this group, send email to iiif-d...@googlegroups.com <mailto:iiif-d...@googlegroups.com>. To unsubscribe from this group, send email to iiif-discuss...@googlegroups.com <mailto:iiif-discuss%2Bunsu...@googlegroups.com>. For more options, visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
> --- You received this message because you are subscribed to the Google Groups "IIIF Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com <mailto:iiif-discuss%2Bunsu...@googlegroups.com>.

Robert Sanderson

unread,
Mar 10, 2016, 12:42:03 PM3/10/16
to iiif-d...@googlegroups.com

Jeff, Rafael,

Thanks for your great work here :)

Some further thinking on the JSON structures ... I wonder if they could be simplified a bit, without losing any of the functionality. Let me know how the following sounds, as I could be missing some important pieces.

* We could instead use "within" as the means to signal which resource the new content is associated with.  That would provide a more generic pattern that could be applied for any sort of content, rather than being restricted to a manifest.

* We could add a viewingHint (most easily as a full URI) to identify structure that is only there to collect content to optimize the transfer (e.g. one AnnotationList of 1000 annotations would result in one webmention rather than 1000, but the List itself could be discarded as an artifact of the protocol)

* As Ranges can have Ranges, we could just use that instead of the new rangelist structure.

So, putting these together, what about the following:

{
  "@id": "uri-for-webmentioned-range", // the source in the webmention
  "@type": "sc:Range",
  "within": "uri-for-target-manifest", // the target in the webmention
  "ranges": [
  // ranges to transfer live here
  ]
}

Does that capture the requirements?  There could also be all of the other properties from the Presentation API on the Range, such as metadata, description, attribution and so forth.


Then for the service description in the manifest, I think we can also simplify:

* There's no need to have @context if there aren't any new JSON keys
* There's also no real need for @type -- the type of the resource is probably a Service. 
* Instead there's the profile property that can be any URI... such as the spec for webmention

That would bring the description down to:

"service": {
"@id": "uri/for/webmention/receiver",
"label": "Example Webmention Service"
}

Thoughts?

Rob


--
-- You received this message because you are subscribed to the IIIF-Discuss Google group. To post to this group, send email to iiif-d...@googlegroups.com. To unsubscribe from this group, send email to iiif-discuss...@googlegroups.com. For more options, visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
---
You received this message because you are subscribed to the Google Groups "IIIF Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Rafael Schwemmer

unread,
Mar 10, 2016, 2:09:01 PM3/10/16
to IIIF Discuss
Thanks, Rob! 

I think this all makes sense, as far as I can tell at first sight. I'm sure the simplification of the service description will be unproblematic. The sender would use the URI of the profile property to identify the service as a "webmention" service instead of using @type: "webmention".

Regarding the JSON structure: the proposed "within" – used for the target – contains a String whereas we were using an Array for our invented "manifests" property. However, I don't see a problem there either, as there should be a separate webmention request for each target anyway and we thus won't need an Array.

Let's see what Jeff says and then test the new structures with our different types (searchWithin, ranges, annotations) to see if it covers all the use cases. 

Best,
Rafael

Jeffrey C. Witt

unread,
Mar 10, 2016, 3:24:59 PM3/10/16
to IIIF Discuss
So I think that makes sense and shouldn't be a problem.

I think I would still like the "within" property to be able to take an array because, even though a separate webmention needs to be sent to each service, I only want to have to publish one supplement for a set of ranges, even if there are multiple manifests for which this information is relevant. 

So, when I send out a webmention, it will crawl my supplement first, identify each manifest listed in the "within" array and then will look for separate webmention receiving services on each manifest.

I'm not saying there will be lots of use cases in which someone wants to publish a webmention about data that applies to more than one manifest, but I can see some use cases. For example, what if the BnF maintains a manifest about their codex, but I maintain a manifest about a work contained within the larger codex, and someone else has comment annotations about the work in question. In this case we have two different manifests and we want the supplement publisher to be able to send webmention announcements to each manifest publisher, while still publishing only one supplement.

Best,
jw

Robert Sanderson

unread,
Mar 10, 2016, 6:37:52 PM3/10/16
to iiif-d...@googlegroups.com

Resources can be within multiple resources, so no problem there :)

We have clarified the cardinality of within in 2.1:

to explicitly disallow pages being within multiple collections or lists (as you could then never tell which was the next/previous page), but anything else is fine.

Rob



--
-- You received this message because you are subscribed to the IIIF-Discuss Google group. To post to this group, send email to iiif-d...@googlegroups.com. To unsubscribe from this group, send email to iiif-discuss...@googlegroups.com. For more options, visit this group at https://groups.google.com/d/forum/iiif-discuss?hl=en
---
You received this message because you are subscribed to the Google Groups "IIIF Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to iiif-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Jeffrey C. Witt

unread,
Mar 17, 2016, 6:58:21 PM3/17/16
to IIIF Discuss
Dear Rob (and all webmention enthusiasts)

Rafael and I met this week and came up with a few questions/problems as we tried to implement your suggestions.

Just so we are understanding you clearly: with the addition of the "viewingHint", the suggestion is that we can jettison the idea of a "supplement" wrapper completely and simply let a higher level version of the same resource be the wrapper (with the addition a viewingHint that informs a receiving service to disregard the top level object)?

So following your example, ranges would look like the example you gave: 

    {
        "@type": "sc:Range",
        "label": "Range wrapper to facilitate transfer",
        "ranges": [
            {
                "@id": "http://scta.info/iiif/wdr-wettf15/range/r1",
                "@type": "sc:Range",
                "label": "Commentary",
                "viewingHint": "top",
                "ranges": [
                // and so on
                ]
            }
        ]
    }

The ranges made some sense to us, but it was less clear what this would mean for a webmention about an available service or an available layer.

Would a webmention for available "service" look like the following?

    {
        "@type": "sc:Service"
        "label": "Search wrapper to facilitate transfer",
        "service": {
            "@context": "http://iiif.io/api/search/0/context.json",
            "profile": "http://iiif.io/api/search/0/search",
            "label": "Search within this manifest"
            }
        }
    }

Finally what would the structure containing a layer look like?

    {
        "@type": "sc:Layer",
        "label": "Layer wrapper to facilitate transfer",
        "otherContent": "http://scta.info/iiif/wdr-wettf15/layer/transcription"           
    }
        
I definitely see the simplicity of this in one regard. It avoids the creation of another resource type (i.e. a "supplement") whose only function is to be a wrapper around the data we hope to transfer.

On the other hand, there is a common function that the wrapper is playing in all three cases. It feels conceptually odd to me to describe the wrapper as a Range in one case, a Service in another, and Layer in another, when the wrapper is really performing the same function in all cases (and is never really being used as a Range, Service or Layer).

As an alternative I've modified the supplement wrapper as we originally had it for the sake of comparison. The @type has been changed to sc:Supplement in all cases, and we would expect the receiving endpoint to look to the "profile" to know how to parse the rest of the supplement in each case. (So for a "service" profile, it should look for a "service" property, for a "layer" profile it should look for a "layer" property, and for a "ranges" profile it should look for a "ranges" property).

At this point, I have added the "viewingHint," but I wonder if it is necessary, since it would be the nature of a supplement resource to be "discarded" after it has performed its function.

For a service, it would look like the following:
    
    {
        "@type": "sc:Supplement",
        "profile": "http://iiif.io/api/0/supplement/service",
        "service": {
            "@context": "http://iiif.io/api/search/0/context.json",
            "profile": "http://iiif.io/api/search/0/search",
            "label": "Search within this manifest"
            }
        }
    }

For a layer it would like: 
 
    {
        "@type": "sc:Supplement",
        "profile": "http://iiif.io/api/0/supplement/layer",
    }

And for a set of ranges:

    {  
        "@type": "sc:Supplement",
        "profile": "http://iiif.io/api/0/supplement/ranges",
        "ranges": [
            {
                "@id": "http://scta.info/iiif/wdr-wettf15/range/r1",
                "@type": "sc:Range",
                "label": "Commentary",
                "viewingHint": "top",
                "ranges": [
                    "http://scta.info/iiif/wdr-wettf15/range/r1-1",
                    "http://scta.info/iiif/wdr-wettf15/range/r1-2",
                    "http://scta.info/iiif/wdr-wettf15/range/r1-3",
                    ]
            }
        ]
    }

Let us know what you think. It's very likely we're missing something or not seeing things as clearly as you.
Likewise, let us know if we butchered your suggestions in the example implementations described above. 

Best,
jw

John Howard

unread,
Feb 8, 2017, 11:31:33 AM2/8/17
to IIIF Discuss
Hi Jeffrey et al.,

Just coming back to this discussion, which I hope will continue productively at Rome in June ... I'm also interested in the a couple related questions that might move a bit off topic, but which inevitably a repository manager will have to think about.

Is you start from the assumption that scholarly contributions arising from annotation activities--such as contents listings, transcriptions, translations, and the like--should be part of the durable scholarly record, then you might also want to capture new information that arises and integrate it with the repository that holds the source images (no matter how that system stores and manages data). I'm curious about the approach you might be taking in the local context, apart from IIIF, to integrate new data from third parties into your records that describe source documents. Are you capturing the new data, or just recording the references to it?

We're archiving a large body of transcriptions from a third-party transcription platform, and associating it with the original images of the documents transcribed. This is proceeding with batch processes, and near real time synchronisation of resources is not an issue. Neither are issues of intellectual property. But looking ahead, with this and other cases, there might be more challenging issues once notifications, additional third-party metadata about logical document structure come into play. For example, using one of your cases, integrating new details of document structure with a legacy METS structure map in a repository would be such an issue ... I think there'd be a challenge in recording appropriate credits for if information were captured in that way. Are there some assumptions that annotations residing in a third party system are always integrated via references, rather than captured?

John
Reply all
Reply to author
Forward
0 new messages