spec text for @context array feature

[davidlehn]

@context can be an array as specified here:
http://json-ld.org/spec/latest/json-ld/#node-objects

There is at least one test for this feature:
http://json-ld.org/test-suite/reports/#test_t0024

Feature is not mentioned here:
http://json-ld.org/spec/latest/json-ld/#the-context

Many places in the API spec that mention JsonLdContext only mention an object or IRI but not an array, for example:
http://json-ld.org/spec/latest/json-ld-api/#idl-def-JsonLdContext

[lanthaler]

It is explained here: http://json-ld.org/spec/latest/json-ld/#advanced-context-usage

In the API spec you can only pass an object because it has to be of the form { "@context": ... array or object ... }

Does this address your concerns?

[davidlehn]

Perhaps the basic section (http://json-ld.org/spec/latest/json-ld/#the-context) should reference the advanced section (http://json-ld.org/spec/latest/json-ld/#advanced-context-usage) since people like me easily missed seeing the features from the advanced part. Similar with the keyword section that says @context "is described in detail" in The Context but doesn't mention more details are in the advanced section.

In the API spec you can only pass an object because it has to be of the form { "@context": ... array or object ... }

I don't understand. Could you clarify? Shouldn't the API accept the same input for a context that you could specify with "@context"?

[lanthaler]

Perhaps the basic section (http://json-ld.org/spec/latest/json-ld
/#the-context) should reference the advanced section (http://json-
ld.org/spec/latest/json-ld/#advanced-context-usage) since people
like me easily missed seeing the features from the advanced part.
Similar with the keyword section that says @context "is described in
detail" in The Context but doesn't mention more details are in the
advanced section.

Good point. @msporny, since you are editing the syntax spec. Can you add those two pointers please.

In the API spec you can only pass an object because it has to be
of the form { "@context": ... array or object ... }

I don't understand. Could you clarify? Shouldn't the API accept the
same input for a context that you could specify with "@context"?

What I meant is that a valid context document has to be passed, i.e., a JSON object having an @context member. Just passing the value of that @context shouldn't be supported IMO - at least that's what I thought we decided.

I just realized the playground supports both things (but the predefined examples all use @context). That the spec isn't clear about this either. @dlongley, @gkellogg thoughts?

[davidlehn]

What I meant is that a valid context document has to be passed, i.e., a JSON object having an @context member. Just passing the value of that @context shouldn't be supported IMO - at least that's what I thought we decided. I just realized the playground supports both things (but the predefined examples all use @context).

Oh! I get it. You pass in {"@context": ...} and could set the innards to IRI, object, or an array. I'm forgetting the reasoning behind that but if that's how it has to be done, that's fine. The API docs should probably clarify that is how passed objects or IRI docs should be formatted.

[lanthaler]

Assigning this to @msporny

[lanthaler]

RESOLVED: Link all Basic concept sections to the Advanced Concepts section to ensure that readers understand that there are more advanced concepts associated with the basic features of JSON-LD.

[davidlehn]

Note that the first part of this issue is resolved, but we still need to look into the last part about JsonLdContext references not listing an array of strings and objects as a possible context value.

[msporny]

@davidlehn I fixed the JsonLdContext references to include the following text:

[JsonLdContext...] can be specified by using a JSON object, an IRI, or an array consisting of JSON objects and IRIs.

I also modified the JsonLdContext typedef to be the following:

typedef (object or DOMString or (object or DOMString)[]) JsonLdContext

I believe this resolves this bug, let me know if you want any further changes.

[lanthaler]

I think this (6770164) is wrong. It shouldn’t be allowed to pass arrays to as context. The API expects a context document, i.e. an object containing an @context member. If we allow both forms, i.e., a context document and the value of @context directly, we will run in to situations where we can’t distinguish them. @msporny, @davidlehn, can I go ahead and revert this change?

[msporny]

I think there are two different things that we're talking about here:

The first is whether or not you can differentiate between a context document and an object containing a context. You can. You check the object, if it has no @context, then it's a context object, if it does have a @context, you use that. That said, I don't think the 6770164 change says that at all (I don't think we should support it, and I don't think the change supports it). I've tried reading it making the assumption that you make above and I can't see how it would be misconstrued.

The second is whether or not we should allow context arrays to be passed in. I think we should because people will probably just want to pass in data["@context"] to the function and let the API do the merge into an active context. It's more complexity for the API, but the alternative is that we make developers write that code and they will almost inevitably get it wrong.

@dlongley, @gkellogg, @niklasl, thoughts?

[gkellogg]

Given that, within a document, @context can accept an array, then I don't see why it would limited at the API level; this leads to the kind of confusion that got us here in the first place.

[lanthaler]

The first is whether or not you can differentiate between a context document and an object containing a context. You can. You check the object, if it has no @context, then it's a context object, if it does have a @context, you use that

Well, yeah. But if someone passes in a document which isn't a context it might be interpreted as one and would yield to very weird results:

compact(
  input,
  { "http://xmlns.com/foaf/0.1/": { "@id": "http://me.markus-lanthaler.com" } }
);

That said, I don't think the 6770164 change says that at all (I don't think we should support it, and I don't think the change supports it).

What shouldn't we support?

The second is whether or not we should allow context arrays to be passed in. I think we should because people will probably just want to pass in data["@context"] to the function and let the API do the merge into an active context. It's more complexity for the API, but the alternative is that we make developers write that code and they will almost inevitably get it wrong.

Why can't they simply pass data in? The API will take care of the rest.

Given that, within a document, @context can accept an array, then I don't see why it would limited at the API level; this leads to the kind of confusion that got us here in the first place.

The question is whether the API expects a context document, i.e., an object with an @context member, the value of that member, or both.