EPCIS JSON should require `@context`

[VladimirAlexiev]

(title was: require context, or provide examples with external context; changed after agreement was reached)

All current JSON examples are JSONLD because they include a (link to a) JSONLD context.

However, https://w3c.github.io/json-ld-syntax/#interpreting-json-as-json-ld shows how to attach a context to a JSON externally (by the server who returns the info). It's an important use case for JSONLD because it shows how existing JSONs can be interpreted as JSONLD, without having to edit them in any way.

1) Has the working group decided that all GS1 JSON payload will include a context, or is this just a coincidence in the examples?

2) Should we include examples with external context?

• I think the tooling I use (jsonld-cli) can pass an external context when processing a local file,
• It would also be nice to add some server tests

3) Note: an external context can't include @base, that's considered a security risk, but we don't have any such examples.

[mgh128]

The main reason why all the current examples show an inline declaration of @context rather than using the HTTP header mechanism is so that it's self-contained and can be pasted into https://json-ld.org/playground/ in a straightforward way.

We're not using @base as far as I remember.

We're not forbidding the use of HTTP headers to reference an external context file but during this stage of development, I haven't found it at all helpful to do so, especially as JSON-LD playground doesn't appear to support it. I use JSON-LD playground to check that the RDF triples are plausible (I'm not claiming that what I've written is 100% perfect) - and I don't see any benefit in removing the inline declaration of @context for the sake of it if it just results in additional editing hassle every time we want to use the JSON-LD playground to check anything. That just seems to be a backward step.

[VladimirAlexiev]

• Playground is not the only way to validate. The jsonld-cli that I use for JSONLD->Turtle conversion is based on the same code, but runs from the command line, can be automated (put in makefiles), and takes option -c for external context
• It's not so much about examples (I'll edit the title accordingly). The big question is: should EPCIS 2.0 require the JSON representation to provide a @context, given that only 1% of users care about it? (I haven't yet read sec 10.1.2)
• If not, then providing advice/examples how to interpret JSON as JSONLD is very relevant.

[mgh128]

True - but JSON-LD playground is convenient.

I have no objection to providing some explanation about the potential use of HTTP headers to transmit a reference to a context resource - but no enthusiasm to do this for each example. A single example of this approach should suffice.

The danger is that if we don't do this carefully and explain clearly that the context resource(s) SHALL be referenced EITHER inline/embedded OR transmittted via HTTP(S) headers, then there is the risk that some users or implementations might ignore it completely and then you've just lost all Linked Data capability for that user / implementation, probably not the outcome you want to see.

[jmcanterafonseca-iota]

I agree with @mgh128 here. The only option to reference the JSON-LD Context should be through the @context field. I would be in favour of making it mandatory, similar to what it is specified at https://www.w3.org/TR/vc-data-model/#contexts.

Even though JSON-LD offers the workaround of the Link header for expressing the LD context , actually it is very limited (for instance, you can only point to one @context resource) so I am in favour to reference the @context inline.

[VladimirAlexiev]

Has the working group decided that all GS1 JSON payload will include a context, or is this just a coincidence in the examples?

I now found the answer in Sec 10.1.2 (line 2283):

• "Many users of EPCIS 2.0 will initially focus on the JSON representation and may disregard the context object.".

So it's optional, and it will benefit users if we explain how an external context can be attached to pure JSON.

@mgh128 I'm not saying to rework all examples, but to explain and include some examples.

@jmcanterafonseca-iota

I would be in favour of making it mandatory

If the EPCIS WG agrees to this, we could adapt the wording from vc, eg:

• "EPCIS JSON messages MUST include a @context property. The value of the @context property MUST be a string or an ordered set where the first item is a URI with the value "https://ns.gs1.org/ref/EPCIS-context"

is very limited (for instance, you can only point to one @context resource)

You are right: "A response MUST NOT contain more than one HTTP Link Header using the http://www.w3.org/ns/json-ld#context link relation". So we should describe that if people want to use custom extensions, they should use an embedded context that's an array of links to the EPCIS context and the custom contexts.

[VladimirAlexiev]

@mgh128 @CraigRe @RalphTro @shalikasingh Please vote whether pure JSON should be allowed (as currently), or a JSONLD context must be present in every JSON.

Given that 99% of EPCIS users don't care about RDF, I vote to leave the context optional (as currently)

[jmcanterafonseca-iota]

I would strongly suggest to make the @context mandatory following the same pattern as W3C VC has defined. The usage of a mandatory @context together with @protected @context terms makes lives easier to implementors and ensures a pretty smooth interoperability and compatibility between JSON-LD and JSON-only implementations. Remember that the point with EPCIS is to share data between stakeholders that may provide different EPCIS implementations. Imagine a lazy JSON implementation (no @context) talking to a JSON-LD implementation ... or imagine a JSON-LD sophisticated implementation using an alternative @context that maps the EPCIS URI's terms to terms defined in a different language and tries to speak with a JSON implementation ...

In essence, making mandatory the @context and ensuring it points to the GS1 EPCIS official @context will avoid many headaches ...

On Mon, Apr 19, 2021 at 10:54 AM Vladimir Alexiev @.***> wrote:

@mgh128 https://github.com/mgh128 @CraigRe https://github.com/CraigRe @RalphTro https://github.com/RalphTro @shalikasingh https://github.com/shalikasingh Please vote whether pure JSON should be allowed (as currently), or a JSONLD context must be present in every JSON.

Given that 99% of EPCIS users don't care about RDF, I vote to leave the context optional (as currently)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gs1/EPCIS/issues/236#issuecomment-822296950, or unsubscribe https://github.com/notifications/unsubscribe-auth/AQEZJLSG5WIOBJ5IAKCNCODTJPVVPANCNFSM42CK2XVA .

-- IOTA Foundation c/o Nextland Strassburgerstraße 55 10405 Berlin, Germany

Board of Directors: Dominik Schiener, Serguei Popov, Navin Ramachandran ID/Foundation No.: 3416/1234/2 (Foundation Register of Berlin)

[VladimirAlexiev]

@mgh128 @CraigRe @RalphTro @shalikasingh Please vote whether pure JSON should be allowed (as currently), or a JSONLD context must be present in every JSON. And I think the issue should be discussed at the next call.

[CraigRe]

@VladimirAlexiev we were hoping you would join yesterday's 14:30-16:45 EET extended EPCIS 2.0 workgroup call (in conjunction with GS1 standards week) to discuss this and a number of other issues...

[jmcanterafonseca-iota]

I am really looking forward to discussing this issue ... and it is not a matter of voting but a matter of putting on the table reasons why it is a good idea to always include the LD @context regardless you use JSON or JSON-LD.

On Wed, May 26, 2021 at 12:14 PM Craig Alan Repec @.***> wrote:

@VladimirAlexiev https://github.com/VladimirAlexiev we were hoping you would join yesterday's 14:30-16:45 EET extended EPCIS 2.0 workgroup call (in conjunction with GS1 standards week) to discuss this and a number of other issues...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gs1/EPCIS/issues/236#issuecomment-848648212, or unsubscribe https://github.com/notifications/unsubscribe-auth/AQEZJLW5XSC7OHF4QMDUUHDTPTCYPANCNFSM42CK2XVA .

-- IOTA Foundation c/o Nextland Strassburgerstraße 55 10405 Berlin, Germany

Board of Directors: Dominik Schiener, Serguei Popov, Navin Ramachandran ID/Foundation No.: 3416/1234/2 (Foundation Register of Berlin)

[shalikasingh]

Hi @VladimirAlexiev,

@mgh128 stated in the last call that recommended way to define user-extension fields is through using CURIE whether the format is JSON or JSON-LD. Sticking to the above recommendation we can conclude that @context field must be present to hold the various namespace against namespace_alias pair in JSON format as well.

[CraigRe]

@VladimirAlexiev please respond to the email re your availability... thanks!

[mgh128]

As @jmcanterafonseca-iota has already mentioned in https://github.com/gs1/EPCIS/issues/236#issuecomment-814215835 the Link header approach is very limited to specifying a single context resource, with no support for specifying more than one. I think it's safest to require that the JSON/JSON-LD data should always explicitly use @context to specify one or more context resources (which in turn may reference additional context resources). For any JSON-only users, they simply reference the standard context resource unless the data is using any custom namespaces beyond epcis: and cbv:

My view is that when we talk about JSON/JSON-LD we're actually talking about returning JSON-LD framed/formulated in such a way as to hide most of the JSON-LD weirdness - but always served as Media Type application/ld+json , in which case we should take note of the following:

Please note that JSON-LD documents served with the application/ld+json media type MUST have all context information, including references to external contexts, within the body of the document. Contexts linked via a http://www.w3.org/ns/json-ld#context HTTP Link Header MUST be ignored for such documents.

( from https://www.w3.org/TR/json-ld11/#interpreting-json-as-json-ld )

Hopefully for JSON-only folks, the insertion of a single line that maps "@context" to the standard EPCIS context resource is usually as painless as writing <!DOCTYPE html> at the start of an HTML document.

To the point that I think @VladimirAlexiev is raising, we should probably adjust our JSON Schema to require at least the standard EPCIS context to be specified.

[VladimirAlexiev]

Don't know if we need to take a vote in a telco, but it seems the prevailing opinion is to require @context. So please make it agreed. Tasks:

• @CraigRe edit EPCIS spec per https://github.com/gs1/EPCIS/issues/236#issuecomment-815829823
• @mgh128 add to JSON schema

[jmcanterafonseca-iota]

the JSON Schema part is already implemented at my branch that will turn in a PR imminently

https://github.com/jmcanterafonseca-iota/EPCIS/tree/gs1_epcis_modular_json_schema/JSON/modular-schema

[VladimirAlexiev]

@jmcanterafonseca-iota and @CraigRe , if the PR is accepted and Sec 10.1.2 (line 2283) is fixed then close this?