JSON-LD grammar

[lanthaler]

This was "Value space of keywords" before. Pleas read the comment below for an updated description.

In #91 we decided to not change the value space of @type but to allow the use of rdf:type for use cases that require different forms. Nevertheless, in 67a0909, the algorithms were changed to allow also other forms of @type. expand-0026-in.jsonld basically contains:

   "@type": [
        "http://example.com/d",
        {
          "@id": "http://example.com/e"
        }
   ]

So, what do we wanna do with this? Do we wanna allow it or not?

A similar issue exists for the @graph keyword. Do we wanna allow @value objects there? So, would the following snippet be valid?

   "@graph": {
        "@value": "My named graph 91"
   }

Just to make sure we all agree on the value space of all of our keywords, here a list of what I think is the value space (perhaps we should include this in some form in the syntax spec):

• @context: (array of) object | string
• @graph: (array of) object (not @value, @list, @set objects) | string
• @id: string
• @value: string | number | boolean | null
• @language: string
• @type: (array of) string
• @container: string
• @list: (array of) object | string | number | boolean | null
• @set: (array of) object | string | number | boolean | null

[lanthaler]

RESOLVED: In general, if the author's intent is clear, we should transform the input into proper JSON-LD (keeping the processor mode, if any, in mind - in strict mode, throw exceptions, in lax mode, attempt to interpret the value).

[lanthaler]

I think the initial description of the issue was not clear enough, so here's another attempt.

While the syntax of JSON-LD is already specified by JSON , the current JSON-LD Syntax spec lacks a formal specification of the allowed grammar, i.e., what constructs are allowed where. The outcome of this issue should be exactly that. This grammar will then form the base for what JSON-LD processors MUST be able to process. Maybe we will also come up with some constructs that are either ignored or automatically corrected.

Let me first introduce a number of definitions that I'll use later:

• value objects: a JSON object that has either a @value, a @set, or a @list property
• node: an object that is not a value object
• scalar: a JSON string, number, true, false, or null // what about array

The following description of what I think should be the valid grammar for JSON-LD is a bit a mixture of ABNF, pseudo-code and prose. I hope it's understandable. I numbered the statements so that we can easily reference them.

1. document = node / node[](i.e. an array of node objects)
2. a node MUST NOT have an @language property
3. a node or value object MUST NOT have an @container property
4. a node MAY have a @context property
5. the value of an @context MUST be a string (that will be used as relative or absolute IRI), an object, null, or an array of a combination thereof
6. The value of properties used in @context MUST be a null, a string, or an object.
7. @context.[..].@id and @context[..].@type MUST be a string (equal @id or it will be interpreted as term, absolute, or compact IRI; not as an relative IRI) or null.
8. @context.[..].@container values have just a defined meaning for @set and @list
9. @context.[..].@language MUST be a string or null
10. Any other property in @context.[..].___ MUST be ignored, but MUST be preserved in compaction and framing
11. A node MAY have an @graph property.
12. The value of an @graph property MUST be null, a string (that will be interpreted as an IRI), or a node.
13. The value of @id in a document (i.e., outside a context), MUST be null or a string (that will be interpreted as term, absolute, relative, or compact IRI).
14. a a value object with an @set property MUST NOT have any other properties
15. a a value object with an @list property MUST NOT have any other properties
16. the value of an @set or @listproperty can be a scalar, a node, a value object, or an array of a combination thereof
17. a value object with a @value property MAY HAVE a @language or @type property and MUST NOT have any other properties
18. in a value object @language and @type MUST NOT be present at the same time
19. the value of the @value property MUST be a scalar
20. the value of the @language property MUST be null or a string. If the value of @value is not a string, @language will be ignored and will this not be checked
21. in a value object @type MUST be null, a string that will be interpreted as term, absolute, relative or compact IRI or a node (or an array thereof with just one entry)
22. in a node @type MUST be null, a string (that will be interpreted as term, absolute, relative or compact IRI), a node, or an array of a combination thereof (with an arbitrary number of entries)
23. In the document the value of @type MUST NOT be @id; in contrast to the context where this is allowed.

The question is first of all if we agree on this grammar and secondly what should happen if a input document violates this grammar. Should a processor throw an error and stop processing? Should it ignore that statement (and possible the whole subtree) and try to continue?

[gkellogg]

I think if we're going to define a grammar for JSON-LD, we should probably do it in W3C EBNF. It so happens, I'm working on a parser for it, but there are a number of other existing resources.

I'll start work on such a grammar myself. It might start something like this:

[1] document ::= node | array
[2] array ::= '[' valueList ']'
[3] node ::= '{' propList* '}'
[4] propList ::= propValue ( ',' propValue )*
[5] propValue ::= key ':' value
[6] key ::= keyword | STRING
[7] keyword ::= '@' WORD
[8] value ::= array | node | STRING | BOOLEAN | NULL

Establishing specific semantics of possible property/value limitations will be more challenging, but is doable.

[lanthaler]

Agree that it should be a bit more formal, but before that we should agree on the grammar itself.. that's what this issue is all about. I'm not so sure that we all agree yet. E.g. 21) and 22) might need some discussion as well as where exactly we allow relative IRIs and where not.

[niklasl]

Does these added rules in the specification currently allow:

"@context": {"@language": "en"}

It seems that item 8 there doesn't permit it?

[lanthaler]

It does:

8.The value associated with the keys used in a @context must be a null, an IRI, or a _JSON object.
9.For each value that is a JSON object that is associated with a key in a @context:
...
_9.3. @language must be a string expressed in [BCP47] or null.

[niklasl]

That seems to take care of using it within a JSON object (i.e. in a term definition). But in the case above the value associated with the @language key is a string, not a JSON object. (I.e. it's about setting a global default language.)

[lanthaler]

Oh I see, I read it too fast. I think that's included in 7) in the spec. But as I said on the telecon there are things that got lost. Let's discuss based on the list in this issue.

It goes a bit around this specific issue since in point 9 is not very well defined what the [..] means.

[lanthaler]

RESOLVED: Express the JSON-LD Grammar in prose with supporting tables/examples. Clarify that violating the grammar does not necessarily mean that a JSON-LD processor will not process the document.

[msporny]

@gkellogg wrote the section, I just proof-read it and made a few minor improvements in 2565c51. I think that the section addresses Andy's concerns. If it doesn't, he will have to provide text that does.