search

w3c / data-shapes

RDF Data Shapes WG repo
87 stars 33 forks source link

Clarity of prose in sec. 1.4 #110

Open skynx opened 5 years ago

skynx commented 5 years ago

Section 1.4, "SHACL Example" articulates the following caveat when introducing the JSON-LD variant of an example.

The example below shows the same shape definition as a possible JSON-LD [json-ld] fragment. Note that we have left out a @context declaration, and depending on the @context the rendering may look quite different. Therefore this example should be understood as an illustration only.

I think the choice to leave out the @context part of the JSON description (which ungrounds the small number of namespace prefixes) and to explain this in preceding ancillary text is confusing. Rather than rely on the reader to bring in background knowledge at such an early point in the text, it could be more effective to alter the example to include the assumed namespace prefixes in @context. If desired, the meaning of @context could then be illustrated by also showing the URI-expanded JSON-LD representation (i.e. what you need without providing prefixes in @context) of the same example shapes graph.

This is an editorial/stylistic issue.

HolgerKnublauch commented 5 years ago

Thanks for your comment, which will remain open to be considered by a future revision. I agree it would be better to have this self-contained. The WG did not deliver an official JSON-LD context, although some work on this was actually done in the group and the result can be found at https://github.com/w3c/shacl/blob/master/shacl-jsonld-context/shacl.context.ld.json and https://github.com/w3c/data-shapes/tree/gh-pages/shacl-jsonld-context. Users can access that using

https://w3c.github.io/data-shapes/shacl-jsonld-context/shacl.context.ld.json

(Without checking details I think if we embed the context into the example then we'd also need to declare that ignoredProperties is @list, not just the namespace prefixes).