Manifests as Named Graphs and the use of the JSON-LD @graph keyword

[Christopher Johnson]

Hi,

I am looking for feedback on how the community views the advocacy of the JSON-LD @graph keyword.  Manifesto (and consequently UV) does not currently support it AFAIK.   To distinguish the manifest node from the named graph that contains it and all of the other @context nodes, the identification of the manifest @id from the resource, the named graph @id, could/should be different.  If the convention is that the manifest resource is a .json file, it should be a referenced as a URI ending with ".json" whereas the top @id in the graph is an LDP container reference or dereferenced node.  So there seem to be two distinct URIs, one that should point to a JSON file (and identify the named graph) and the other that points to the manifest @id.  The named graph may be versioned and have associated context metadata, whereas the manifest @id may not.  If they have the same URI, then this could be a default graph and would not need an explicit @id to identify the named graph, but could still be explicitly expressed with @graph. 

Furthermore, I noticed in the NCSU implementation that they include non-IIIF context identified versioning properties, "ncsul:metadata-updated" and "ncsul:manifest-updated".  I feel that this type of metadata appropriately belongs outside of a named graph of manifest nodes as recommended by the JSON-LD specification on named graphs (https://www.w3.org/TR/json-ld/#named-graphs).

My implementation generates the manifest with SPARQL, so when transformed into JSON-LD it includes the manifest linked nodes in the @graph array.  I can remove it to make it work with UV, for example, but I am not sure that this should be necessary in a proper schema.   

Cheers,
Christopher Johnson

Akademie der Wissenschaften zu Göttingen

[Tom Crane]

Hi Christoper,

A viewer such as Mirador or UV could in theory encounter @graph in a manifest (see implementation note at http://iiif.io/api/presentation/2.1/#d-implementation-notes), but providers of IIIF resources are encouraged not to serialise manifests like that ("servers SHOULD remove it before sending to the client") and so far most implementations build or transform the JSON-LD from other data rather than direct from a triple store, so the lack of support for @graph in the UV at least hasn't come up. For full compliance with the spec, Manifesto should handle @graph - but a server should also remove it if it can. 

IIIF is "JSON-LD First" in the interests of ease-of-development. It's important that a simple JavaScript client doesn't have to process a manifest as RDF. Any client that wants to do that via the @context can do it, and you can also link to additional assertions about the manifest via the "seeAlso" property.

Tom

[David Newbury]

I also worry a bit about this, and about the cavalier approach that the IIIF community often seems to take with RDF.  I've got no problem at all with IIIF being an extremely useful JSON API, or even a JSON API that uses hypermedia links to attempt to be self-documenting.  But if it's going to position itself as a Linked Data API, it needs to support RDF and RDF parsing as well as JSON and JSON parsing.  

One of my biggest worries about the standard as it is currently defined is that the context (and thus the RDF expression of a IIIF Presentation API) is not considered part of the API and is not included as part of the semantic versioning of the API.  This means that anyone who uses RDF (rather than JSON) to express their IIIF manifests could have their manifests break as part of a point version release.  That seems like it could be a big problem.

Again—If the intention of IIIF is to loosely support RDF but to primarily be a JSON API, that's a fine decision and one that I could support. It's just important for those of us using it as RDF to understand what the IIIF community's position on RDF is.

- David Newbury
-----------------------------------
p. (773) 547-2272
e. david....@gmail.com

--
-- 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+unsubscribe@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+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Robert Sanderson]

Hi David, all,

I don't think IIIF intends to position itself as a Linked Data API, but instead an API that uses JSON-LD, which is happily Linked Data.  This was discussed relatively early on and the strong consensus was that requiring content negotiation for different formats of RDF was a barrier to entry (the complexity is pretty high for non RDF initiated) and for interoperability (unless every format is required, you end up with balkanization based on the intersection of client/server supported formats).

There was also a choice made from the Shared Canvas model to simplify the expressivity to make the implementation easier for typical json/javascript applications. There's a Shared Canvas 2.0 process just starting up, which it would be great if you have time to be part of, to both update to get the model and API back in line and to address issues that have been encountered along the way, particularly in the AV side.

The non semantic versioning part for the context comes from these observations:

  *  We don't want to have the URI of the context change every patch release.

  *  We do want it to change every major release when the model and API changes in backwards incompatible ways

  *  We want to be able to add new features in minor versions, so long as they're compatible  

     (e.g. a 2.0 client should read a 2.1 manifest)

  *  We're all fallible and getting the semantics right is hard! We didn't want to require a major version for a small tweak that wouldn't affect the current community in any meaningful way.  And example of this was rights versus license -- it was pointed out that our current "license" text actually describes dcterms:rights. So we fixed the mapping in the context, and we're waiting for 3.0 to fix the name in the JSON.  See:  https://github.com/IIIF/iiif.io/issues/644 and https://github.com/IIIF/iiif.io/issues/636

On that last point ... if there are people using this as RDF, we can put the context documents under semver to some degree -- we'll still need to add features, but we could have waited for license -> rights change and done them both at 3.0.

Working code doesn't actually win ... but it does inform us all about what is practical and useful.  If there are people with RDF based implementations that we're making more difficult, then please do speak up and we'll do whatever we can to make things better!

Rob 

--

Rob Sanderson

Semantic Architect

The Getty Trust

Los Angeles, CA 90049

[Christopher Johnson]

Dear all,

Thank you for the feedback.  On the original question of the use of @graph, I feel that the implementation guideline statement that it "SHOULD" be removed is incorrect.  It is a legal keyword in JSON-LD and represents a standard form for RDF that is serialized as JSON-LD.  Therefore clients that are expected to interpret a JSON-LD document should handle it appropriately, regardless of the specifics of any API implementation.  I would also consider @graph to be appropriate for non-RDF data model serializations, as it can clearly identify the content (as a directed graph) from the serialization document itself.  Thus, its general use should be encouraged and supported in the community.

The beauty of JSON-LD is that it does not depend on RDF, with all of its complexity, for non-LD implementations.  This does not mean, however, that these implementations should not consider the advantages that LD can offer when creating a serialization format.  And, a primary use case for @graph is to make statements about the content in the serialization document.  To embed these statements in the content with a seeAlso property does not make sense imo.  

For my implementation, the URI (and @id) for the manifest document is completely different from the manifest @id which is an addressable LDP container / fedora repository resource.  So, technically, I need to keep @graph to maintain this distinction in the serialization.

On semantic versioning of @context, maybe following existing conventions for XSD publishing may be advisable.  I would simply argue that it is a user responsibility to use the correct schema for an implementation.   

Christopher Johnson

Akademie der Wissenschaften zu Göttingen

--
-- 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.

--
-- 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.

[Robert Sanderson]

Hi Christopher,

Comments inline ...

On Mon, Sep 19, 2016 at 12:39 AM, Christopher Johnson <chjoh...@gmail.com> wrote:

Thank you for the feedback.  On the original question of the use of @graph, I feel that the implementation guideline statement that it "SHOULD" be removed is incorrect.  It is a legal keyword in JSON-LD and represents a standard form for RDF that is serialized as JSON-LD. Therefore clients that are expected to interpret a JSON-LD document should handle it appropriately, regardless of the specifics of any API implementation.  

It certainly is a legal keyword in a W3C standard for an RDF serialization, and any generic RDF client that can process JSON-LD should be expected to understand it.  However, as per my response to David, that's not the scope of the IIIF work.

Note that a list of small JSON objects, rather than the specific nested structure we've defined in the Presentation API, would also be legal JSON-LD and indeed the simplest form for RDF based servers to produce, as there's no need for framing and embedding rules.  However we also don't recommend that particular structure, as it's significantly harder for clients to use.  The same applies to @graph -- to date there hasn't been a need expressed for it, and having to test for it makes it harder than the more compact form.  

 

I would also consider @graph to be appropriate for non-RDF data model serializations, as it can clearly identify the content (as a directed graph) from the serialization document itself.  Thus, its general use should be encouraged and supported in the community.

This just isn't that community, I'm afraid. Past experience has shown that the complexities of doing this outweigh the benefits.  Consider (for example) the Europeana Data Model's use of ORE.  ORE flat out requires the use of a Resource Map, as the same sort of serialization level metadata. Europeana doesn't mention it at all... and has been significantly more successful than the more generic but more structured base ontology.  The Portland Common Data Model (PCDM) made exactly the same choice, for the same reasons.

 

For my implementation, the URI (and @id) for the manifest document is completely different from the manifest @id which is an addressable LDP container / fedora repository resource.  So, technically, I need to keep @graph to maintain this distinction in the serialization.

Can you expand on this a bit with an example please? It would be great to understand the requirements and assess the impact :)

From what I understand, you have a URI that identifies the content and a second URI from which that content is available, which happens to be in an LDP container?  What's the purpose of the URI that can't be deferenced, particularly in the Linked Open Data world, and even more specifically in the IIIF landscape?  When is it used in practice?

Many thanks!

Rob

[Christopher Johnson]

Dear Rob,

Thank you for your insight.  Though still very experimental, I can demonstrate what I am doing and how it works (with a very minimal example).  

First, I am using a service API that dynamically generates the serialization. The service URI for a manifest looks like this:

http://service.b-ol.de/api/graphs/manifest.nt?$node=<http://dor.b-ol.de/fcrepo/rest/collection/test/003/manifest> 

The manifest reference is an addressable LDP container that is the data model representation of the manifest graph root node.  The manifest graph is constructed from collections of nodes primarily linked with Skolem IRIs.  To create the data model in Fedora, I have extended a java client that basically uploads a bag of stuff and patches the statements that bind everything together per the IIIF specification.

The benefits of this rather elaborate manifest serialization process sourced from RDF stem directly from the core use of Fedora as an LDP for binary resource storage.  In my (perhaps limited) understanding, the trend for institutional repositories is towards LDP.  I would hope that the IIIF aims to position itself in accordance with this trend.   

Christopher Johnson

Akademie der Wissenschaften zu Göttingen

[David Newbury]

Rob, 

Thank you for your thoughtful response.  

I agree that changing the URI with every patch response is a bad idea, and I'd want it to only change at 3.0.  I think that considering putting the context under SemVer as well would be helpful for those of us manipulating this information via RDF instead of JSON transformations—it might also help in the hypermedia world, if we're using the context to help document the API.  (Not my particular axe to grind. :-) )

Perhaps it would be helpful to add an example of how to use the JSON-LD frame to recontextualize RDF?  I'm still not 100% confident that my understanding of how JSON-LD frames works is correct, but an example using it to take RDF information and pre-process it into standard IIIF JSON would go a long way.  

- David Newbury
-----------------------------------
p. (773) 547-2272
e. david....@gmail.com

[Christopher Johnson]

Dear David,

The JSON-LD framing algorithm alone will not magically transform any arbitrary RDF into an IIIF Manifest, unfortunately.  The transformation process that I have developed depends entirely on the IIIF data model @lists existing first as RDF collections.  Assuming that your data is already in collections, then the jsonld library can process a manifest graph using the fromRDF method first, which orders the RDF collections into JSON-LD @lists (among other things), and then frame it which simply formats it into the expected IIIF manifest serialization.  Check the convert-from-rdf-algorithm document for further information.

Christopher Johnson

--
-- 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.

--
-- 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.

--

Rob Sanderson

Semantic Architect

The Getty Trust

Los Angeles, CA 90049

--
-- 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.