JSON-LD Community Group Telecon

Minutes for 2012-12-11

  1. Ongoing research into JSON-LD .graphify() API
  2. ISSUE-200: JSON-LD API Review by Robin Berjon
  3. ISSUE-182: Graph vs. DataSet
  4. ISSUE-153: Define error handler behavior
  5. ISSUE-201: Update dataset examples
  6. ISSUE-202: Do not compact @graph arrays with one element
  1. Move the .toRDF() and .fromRDF() WebIDL API calls into a separate document that will not be a part of the JSON-LD 1.0 work. The to/from RDF algorithms will still be a part of the JSON-LD API 1.0 work.
  2. Add a note to the "Relationship to RDF" section to specify that if clients that do not understand Datasets are to be supported using JSON-LD, that the primary information should go in the default graph.
  3. Keep values of @graph that are arrays consisting of just one element as arrays.
  4. Do not compact "node references" that are values of @graph to strings.
Manu Sporny
Gregg Kellogg
Manu Sporny, Niklas Lindström, Gregg Kellogg, Lin Clark, Markus Lanthaler, François Daoust
Audio Log

Topic: Ongoing research into JSON-LD .graphify() API

Manu Sporny is scribing.
Niklas Lindström: I've been working on something - http://niklasl.github.com/rdfa-lab/examples/rdfa-api-comparisons.html
Gregg Kellogg: looks interesting...
Niklas Lindström: The LD.connect() thing is my extension to the JSON-LD API. I'm going to work on it some over the holidays. I'm trying to use local names for everything... maybe raise an error if there are collisions.
Gregg Kellogg: Ivan had JSON-LD output, he constructed a context on-the-fly based on what the RDFa processor had read.
Niklas Lindström: If you are computing things, you could try to figure out the most compact possible context. The JSON you'd get back would be very compact, but it would not work for the more advanced RDFa use cases. It would work for every schema.org use case in existence, which is 90% of every developer that wants this API.
Markus Lanthaler: Lin, just out of curiosity: why do you depend on the fact that empty arrays are preserved (during compaction for the Drupal use case)?
Lin Clark: Markus, if you want to remove values from a field on PATCH
Niklas Lindström: The graph API may be interesting because you get access to things like property paths. It seems plausible that I could implement this with hooks back to the live DOM tree. Maybe with DOM mutation listeners. If you manipulated the DOM with JS, yo'd be able to see that live when you navigated the graph.
Markus Lanthaler: Lin, do you mean to distinguish between not set vs. set to empty array
Gregg Kellogg: I think the first one for schema.org looks quite nice - the inverse of this we don't necessarily have a solution for.
Lin Clark: Markus, no, set in PATCH means do nothing to that field. So if it already has values, you couldn't remove them
Niklas Lindström: I've thought a bit more about .connect() - maybe you can add custom indexes for it, the @context is one input... the next one might be definition of indexes and which key you want to use for inverses. Karl Dubost asked for an RDFa API, his example needed something to getByType(). You'd go with the Graph API or the Microdata API (for RDFa) or you'd need a .connect() implementation. I think .connect() gives much more for a fairly cheap price.
Markus Lanthaler: Lin, I see... but it seems to be a bit brittle
Gregg Kellogg: Since we're not going to do .connect() in this version, we should look for another group to attach that work to.
Lin Clark: Markus, what do you think is brittle there?
Niklas Lindström: Maybe we should start a CG focused on these sorts of APIs. The RWW group has so much on its schedule.
Markus Lanthaler: Lin, well the thing is that if you look at it from a graph perspective (abstract) both are equivalent... you would have to set it to something likeowl:Nothing to clearly differentiate between the two cases
Niklas Lindström: I start a new job at Royal Swedish Library - they're interested in Linked Data, could use a lot of this work there.
Markus Lanthaler: Lin, just wanted to point that out.. if it works for you this way it's probably simpler to keep it as is
Lin Clark: Markus, cool, thanks for pointing it out

Topic: ISSUE-200: JSON-LD API Review by Robin Berjon

Gregg Kellogg is scribing.
Manu Sporny: We left off when talking about asynchronous interfaces.
… The async interface is probably the way to go.
… We have previously discussed using just the async, but allowing people to use the sync if they like.
… We also have different conformance levels, sot that implementations can be just processing, and do their own API.
… Robin notes that we list errors, but don't define constants: we need to do that.
… We don't need all UPPER CASE errors, we can just use strings.
… For the API, people are moving away from numbers to text strings.
Markus Lanthaler: We need to collect the text strings or whatever, perhaps in an enum.
Manu Sporny: error codes that are numbers aren't too useful; strings are better.
Manu Sporny: next item, is loosing information an issue? Should we throw an error?
… Don't return a lossy compaction. If you would loose data, don't compact.
Markus Lanthaler: we don't do that, but we may fail (e.g., List of Lists).
Manu Sporny: resonse to robin is that we don't do lossy compaction.
… robin doesn't want it to throw an error, but there are problems if we keep everything around.
… If you don't specify how a term expands, then it is dropped; typically in expansion.
François Daoust: One of the use cases robin may have had in mind is being able to take an arbitrary JSON-LD document and apply a context then compact.
… If you do that, there may still be problems in compaction. Are there workarounds? Keep it in expanded form?
Manu Sporny: if it expands correctly, it will stay expanded if you don't have a mapping when you comact.
… you can get errors in either expansion or compaction. It depends on what you're doing, but in general, if you have a successful expansion, you will not loose data when compaction; it just may not completely compact.
Manu Sporny: next thing: you might want to be clear about "copying the input".
… WebIDL doesn't have number, use one of the appropriate numeric types.
Markus Lanthaler: a JSON number depends on the form, either an integer or a float.
Manu Sporny: question is about WebIDL numeric version.
… change "string" to DOMString, and numbers appropriately.
Niklas Lindström: .. the unsigned long IDL type mapping to the Number type in ECMAScript (from http://www.w3.org/TR/WebIDL/)
Markus Lanthaler: For the record, the sourceValue member of JsonLdProcessingError might be a number.. should be an integer but probably we will drop it anyway
… toRDF is designed wrong; should be a single callback with a quad array.
… ConformanceCallback: will remove; just not sure how to report "linting" errors through issue feedback.
… what if the developer doesn't provide a callback?
Markus Lanthaler: question is what if it isn't ever called back?
Manu Sporny: issues with IRI definitions ...
… Better to use dictionary with keys.
… Basically, he's saying we shouldn't have interfaces, just dictionaries with keys.
… We want objects to be easily used in developer code.
Manu Sporny: the problem with passing back strings, is you need to do some magic, as you don't know the type of what you're dealing with. Some people will be unhappy no matter what we do.
… If you do new IRI and new Node, it annoys web apps folks, because it should just be a dictionary.
… if you use a dict, you're stuck with .type and .value, and it's less elegant.
Niklas Lindström: is this just about to/from RDF?
Manu Sporny: this is a general problem, IMO.
Niklas Lindström: until we know what the exact needs are, we're not doing ourselves a favor by defining them. It might be better to just use a dictionary.
… to/from RDF would just translate one form into another (objects with keys from triples).
… We also have this in SPARQL JSON output where they have dictionaries.
… on the other hand, we might not have to define it at all, as the expanded form already references the RDF.
… This is an argument for getting rid of type definitions, and maybe the to/from RDF API calls themselves.
… In my work, I just expand JSON-LD or produce it directly.
… Similarly, I've used expanded JSON-LD to create a graph. Otherwise, it's hard to know where the contract for the JSON-LD API ends. It might be better to just leave this to something else.
Markus Lanthaler: why can't we just re-use our JSON-LD constructs, @iri, @value, etc.
… We don't really need to define new structures.
Gregg Kellogg: I'm starting to feel like the API is beyond what we want to do. Once you get into the nuances of the API, it becomes a different conversation. Is this something that we should really be spending time on? [scribe assist by Manu Sporny]
Gregg Kellogg: We're already postponing .connect() to another CG. Since we've separated the processing from the IDL interface, I'm coming around to that viewpoint. [scribe assist by Manu Sporny]
Manu Sporny: as a data point, this is the exactly the same conversation we went through with the RDFa API.
… One of the negatives that comes out is that the work doesn't get done, or is delayed.
… For DB, the API is really important, without a solid API we don't have something to implement against. We'd just end up going off and doing our own thing, and wouldn't sync with an API.
… If feel like if we through out the API, it's going too far. There are just a few tweaks we need with the API rather than doing wholesale changes.
Niklas Lindström: I am sympathetic to both positions. Regarding the RDFa API, although it's being asked for, I'm glad we didn't give them what we were originally looking on.
… In this case, i have the feeling that the good parts are expand and compact, which needs to be precicely defined. I think that expanded JSON-LD represents RDF.
… I don't think it's necessary to define an API for that, as it's just data describing itself.
… We could use those concepts to represent the data and the Nodes represent all we need semantically.
… I don't see the need for to/from RDF API methods, as other tools can just work with expanded JSON-LD. Saying you need an API indicates that it's something that's hard.
… we have an array of resource descriptions.
Manu Sporny: your argument is to remove the API from the spec?
Niklas Lindström: not the entire API: keep expand and compact. to/from RDF do not seem necessary. We should have a precise definition of what the expanded JSON-LD form means as RDF.
Markus Lanthaler: I kind of agree with niklas about dropping the RDF part.
… It might be good to factor out flatting as a separate method, instead of hiding it behind a flag.
… I agree that to/from RDF are not very useful as an API. You'd need adaptor code anyway.
Niklas Lindström: from an RDF point of view, it would be easier to just look at flattened expanded JSON-LD as an RDF expression.
Markus Lanthaler: it's completely deterministic.
Markus Lanthaler: if we remove to/from RDF from WebIDL, we should make it clear that there's a way to get a deterministic shape out of an arbitrary document: expand with flatten.
Manu Sporny: I've always preferred having a flatten API method.
Niklas Lindström: the IRI and Node interfaces are only needed for to/from RDF.
PROPOSAL: Move the .toRDF() and .fromRDF() WebIDL API calls into a separate document that will not be a part of the JSON-LD 1.0 work. The to/from RDF algorithms will still be a part of the JSON-LD API 1.0 work.
Gregg Kellogg: +1
Niklas Lindström: +1
François Daoust: +1
Manu Sporny: -0.5
Markus Lanthaler: +1
RESOLUTION: Move the .toRDF() and .fromRDF() WebIDL API calls into a separate document that will not be a part of the JSON-LD 1.0 work. The to/from RDF algorithms will still be a part of the JSON-LD API 1.0 work.
Niklas Lindström: For a shape of the "just dictionary" RDF node representation, I suggest using http://www.w3.org/TR/rdf-sparql-json-res/#variable-binding-results verbatim
Manu Sporny: we might want to consider changing IRI to URL.
Niklas Lindström: .. In that other document
Manu Sporny: the concern is that the API will be built on an HTML5 DOM, so we should align with that.
… We could say that when we say URL we mean an internationalized resource identifier.
… If we don't do that, we're in violation of the HTML5 DOM.
Markus Lanthaler: we don't have an IRI concept in the API, just in the algorithms.
Manu Sporny: we should just define URL in the API.
Manu Sporny: will the API users ask for to/from RDF.
Manu Sporny: developers work with APIs.
Niklas Lindström: compact seems very useful for developers.
Manu Sporny: the URL/IRI thing is really just terminology.
… If we talk about things in the prose, we need to draw the equivalence.
We'll need to separate the WebIDL definitions used within the to/from RDF.
Manu Sporny: Robin's stuff is resolved now, after we make the editorial/design changes discussed.

Topic: ISSUE-182: Graph vs. DataSet

Manu Sporny: seems to be resolved in conformance with RDF WG.
… I wonder if we should make a slight change the the language.
… We might want to say that the client should look in the top-most object and use that value, or use the first item in the @graph.
… I wonder if we could give some feedback to clients so they know where to look for the default graph.
… Either the top-level object.
Gregg Kellogg: I think it's problematic to rely on the JSON-LD Syntax - in the cases that I was talking about, they're RDF consumers. [scribe assist by Manu Sporny]
Gregg Kellogg: I'm sympathetic to the idea of being able to provide some indication of which graph to use from a dataset, if you're just using it - but something that relies on the JSON-LD syntax is not going to solve the types of problems I'm concerned about. [scribe assist by Manu Sporny]
Gregg Kellogg: You might type a graph as something being the "jsonld:PrincipleGraph" - that's the item that contains the graph-like results. [scribe assist by Manu Sporny]
Manu Sporny: I'm trying to get the concept of "the subject of" or "primary topic".
… to RDF consumers you're saying that the primary topic is the default graph.
Gregg Kellogg: I think that the best route would be sort of some for of type on a graph that allowed us to designate it as the one that is "most interesting" [scribe assist by Manu Sporny]
Niklas Lindström: I'm confused of what we're trying to do. Are we defining standard rules for the consumption of datasets?
… I think we're getting away from what JSON-LD can say.
… Anything else is semantics and should be defined elsewhere.
Markus Lanthaler: I agree with niklas.
… To address the signature, both data should be in named graphs. The signature only makes sense if you can interpret the named graphs.
… It makes no sense to assert something that you can't retrieve.
Manu Sporny: I'm concerned that we might need to serve the data in a different form than it is naturally served.
can be added to the payload (of the default graph) as a graph named by <iri>?
… The top-most object is the signature information, and inside the @graph is the data that is primary, but it must be named.
Gregg Kellogg: [explains how this already works in PaySwarm]. The principle data is in a named graph, and you use the data to sign it - you have something that makes sense. The best alternative is take the graph that takes the name of it's location. [scribe assist by Manu Sporny]
Manu Sporny: in web payments we have a default graph with the signature and a named graph with the asserted data.
Markus Lanthaler: it's a problem if you serve datasets with both.
François Daoust: [Looking at it from a syntax perspective, the example 50 discussed in issue 201 (which matches current discussion, AFAICT) does look much better when metadata is in the default graph and data in a named graph than on its possible update that puts metadata in a named graph and data back to the default graph]
Gregg Kellogg: [explains why this needs to be placed in a semantics document] [scribe assist by Manu Sporny]

Topic: ISSUE-153: Define error handler behavior

No progress on this issue.

Topic: ISSUE-201: Update dataset examples

Manu Sporny: given our discussion, we should update the dataset examples.
Markus Lanthaler: it really just matters if you're a consumer that can just deal with graphs.
Gregg Kellogg: Yes, agree with Markus. We are conflating clients that understand datasets with ones that do not. We don't need to add this text. [scribe assist by Manu Sporny]
François Daoust: [I'm still at a loss as to how a provider can tell whether a client understands datasets or not. It needs that info to serve the appropriate form, right?]
Markus Lanthaler: tidoust, the provider doesn't have to know
Manu Sporny: a provider can provide multiple endpoints, or just always merge data into the default graph.
PROPOSAL: Add a note to the "Relationship to RDF" section to specify that if clients that do not understand Datasets are to be supported using JSON-LD, that the primary information should go in the default graph.
Gregg Kellogg: +1
Manu Sporny: +1
Niklas Lindström: +1
Markus Lanthaler: +1
François Daoust: +1
RESOLUTION: Add a note to the "Relationship to RDF" section to specify that if clients that do not understand Datasets are to be supported using JSON-LD, that the primary information should go in the default graph.

Topic: ISSUE-202: Do not compact @graph arrays with one element

Markus Lanthaler: basically just make sure the value of @graph is always an array.
Manu Sporny: uniformity probably wins over the array access tax.
Niklas Lindström: .. "Please note, this doesn't affect the fact that the default graph's @graph is optimized away."
PROPOSAL: Keep values of @graph that are arrays consisting of just one element as arrays.
Markus Lanthaler: +1
Gregg Kellogg: +1
Manu Sporny: +1
François Daoust: +1
Niklas Lindström: +1
RESOLUTION: Keep values of @graph that are arrays consisting of just one element as arrays.
PROPOSAL: Do not compact "node references" that are values of @graph to strings.
Manu Sporny: +1
Markus Lanthaler: +1
François Daoust: +1
Niklas Lindström: +1
Gregg Kellogg: +1
RESOLUTION: Do not compact "node references" that are values of @graph to strings.
Niklas Lindström: this copy is a reduced version of my RDFa transformation, without framing.
… It was easy to keep it up to date.
Manu Sporny: we're wondering how small we can get a minified version, but it's half the size without framing and to/from RDF adapting.