Proposed description of sealed contexts

[pchampin]

As per my action during last call, here is a first proposal to describe sealed contexts in the Syntax document. A few comments about this text:

• After writing this, I take back what I said about multiple sealed contexts; I think it can work. I'm still not comfortable with sealing individual terms, though (and the algorithm that I am about the propose does not handle them). However I chose not to mention them in this non-normative section, to keep it short enough.

• Resetting @context to null must also be prevented by sealed contexts, since it resets all term definitions. I didn't mention that in the text, though, because the effect of setting @context to null is never described in the document (it is in the API doc).

• Finally, I didn't mention "extension points" in sealed contexts (i.e. terms of a sealed context that explicit reset the context and hence stop the sealing).

• The first example in the "Sealed contexts" section will actually fail(?) and thus provide no result. So may be the alternative versions should not even be included??

---

Preview | Diff

[dlongley]

Thanks @pchampin!

This looks like a really good first cut. I agree with the reasoning. We'll need to explore it further by considering it against the specific examples we've come up with so far and make sure it covers identified use cases.

[iherman]

This looks very clear; as @dlongley said, we will have to compare with the use cases.

One editorial/didactic proposal: example 43 may be extended to emphasize the differences. Maybe the following example could be a bit better:

{
  "@context": [
    {
      "@version": 1.1,
      "@sealed": true,
      "name": "http://schema.org/name",
      "employee": "http://schema.org/employee",
      "Organization": "http://schema.org/Organization"
    },
    {
      "member": "http://xmlns.com/foaf/0.1/member"
    }
  ],
  "@type": "Organization",
  "name": "Digital Bazaar",
  "employee" : {
      "@context": {
          "name": "this_attempt_will_fail"
      },
      "name" : "Dave Longley"
  },
  "member": {
    "@context": {
      "name": "http://xmlns.com/foaf/0.1/name"
    },
    "name": "Manu Sporny"
  }
}

[pchampin]

This makes the example clearer indeed, but may be a problem. Let me explain. I'm not sure what is expected when a context attempts to override a sealed term. The processor may ignore this attempt with a warning, or fail with an error. In the first hypothesis, my example 41, and your version of example 43 are fine. In the second hypothesis, they will raise an error and produce no triple at all., which makes them less informative. I realized this when I wrote example 41, but I kept it that way to open discussion. Then I tried to avoid the problem with the other examples... Now, the discussion is open: how do you (all) think a processor should react on a failed attempt to override a sealed term?

[ajs6f]

Some (most!) of the use cases that have been presented for sealing concern security issues. From that fact, I would argue that at least the default should be failure with error unless some other mode has been enabled.

[dlongley]

Some (most!) of the use cases that have been presented for sealing concern security issues. From that fact, I would argue that at least the default should be failure with error unless some other mode has been enabled.

The security issues have to do with allowing the sealed terms to be overridden, however. This feature would ensure that can't happen -- regardless of whether a processor outputs a warning or an error. I think we should support both modes (warning or error) ... but I'm not sure which we should default to yet.

[ajs6f]

@dlongley I wasn't thinking of the path of execution-- I was thinking about the path of notification. A warning can more easily be ignored, whereas an actual halt inspires attention. But since you raised the use cases, if guarding against actual execution with overriding is enough for you, 'nuff said from me!

[dlongley]

@ajs6f,

But since you raised the use cases, if guarding against actual execution with overriding is enough for you, 'nuff said from me!

To be clear -- I'm not yet convinced either way regarding the default behavior (error or warning). The only argument for warning by default is for backwards compatibility/easier ergonomics ... but that might be the winning argument. Even if we do decide that warning is the best default, I would certainly want an error mode when authoring new contexts.

[gkellogg]

I'm not sure what is expected when a context attempts to override a sealed
term. The processor may ignore this attempt with a warning, or fail with an
error.

For similar issues in the past, we've chosen to ignore rather than raise an error. We don't have consistent language about issuing a warning, which would need to be application-specific, and we don't presently have a way to check for warnings being emitted in the test suite. We should probably figure that out.

[gkellogg]

Looks good, other than a couple of inline comments.

Regarding ignore/warning/error, this is a bigger issue for the API in general. WebIDL doesn't have anything to support warnings AFAIK. Given that, with scoped contexts, the results are unambiguous, I don't personally see it as an error condition.

[gkellogg]

Also, don't forget to add yourself to the editor's list! Something like the following:

    { name:       "Pierre Antoine-Champin",
      company:    "Université de Lyon",
      companyURL: "http://iut.univ-lyon1.fr/",
      w3cid:      "your w3cid from your W3C user profile",
      note:       "v1.1" }
    ],

@iherman can help with your w3cid; I believe it's required for the publication process.

[iherman]

Now, the discussion is open: how do you (all) think a processor should react on a failed attempt to override a sealed term?

My preference would go for the warning and ignore approach. This is in line with what JSON-LD 1.0, and I think @dlongley's argument (see #119 (comment)) sounds convincing to me.

[iherman]

@pchampin,

@iherman can help with your w3cid; I believe it's required for the publication process.

yes indeed, this number should be part of the respec header. Your number is 42931

[iherman]

This issue was discussed in a meeting.

• No actions or resolutions

View the transcript

Review Pierre-Antoine’s proposal for sealed context processing
Benjamin Young: https://lists.w3.org/Archives/Public/public-json-ld-wg/2019Jan/0016.html
Ivan Herman: #119
Gregg Kellogg: #20
Ivan Herman: -> the proposed text for the syntax draft: https://pr-preview.s3.amazonaws.com/w3c/json-ld-syntax/pull/119.html#sealed-contexts
Benjamin Young: API PR w3c/json-ld-api#60
Gregg Kellogg: I can represent pchampin’s issue, since he can’t call in due to internet connectivity problems
… There’s an issue, and discussion in the PR
… the principle issue in #20, and pchamin’s work is around syntax
… basically, he suggests sealing contexts, not terms, though it’s not design limited that way
… and sealing a context, the term definitions are tagged with an identifier associated with that context
… an implementation, for each term def., you know which context it comes from (for sealed contexts)
… so if you attempt to update that within a sealed node, you can only update it if the update is coming from the sealing context
… this would happen for embedded context
… so if I define a term foo, and that context wants to update a term in that context, you can see the terms that the updated terms came from the same context
… that would allow terms defined in other sealed contexts to not interfere
… so you cannot create a term that interferes with a different sealed contexts.
… there is a list of active sealed contexts active during expansion…
… that effectively unseals all the other contexts when processing
… if you were to descend into another property not associated, that would have the effect of unsealing all contexts.
… if you use a term from a context, even if it’s unsealed, you now enter a mode where the context is sealed.
… what this means for sealing contexts or terms, since you’re tagging the context info per-term, it seems straightforward to do that per-term. There is no support for sealing part of a term, say the ID, but not the container
… no use cases
Rob Sanderson: does the seal ID need to be different than the context ID? is it specified explicitly?
… does this mean that the top context might be sealed, but an embedded one might be unsealed?
Ivan Herman: he also put a text into the syntax document which describes things and makes it clear and easy to understand
… there was also an issue: what happens if you do something that is not kosher? one possibility is a warning and you ignore, the other is to throw an error
… and some of the examples will change based on that answer. It’s a decision
Benjamin Young: This felt a lot like one context being last
… it would be super if we could have our use cases written up, both verifiable claims and web of things
… have use cases
Dave Longley: I am thinking about this and reviewing it, and looking at it, I’m not sure how it would impact caching of active contexts.
… I haven’t thought through how it works…can we keep track of an ancestry tree?
… whatever we put in the spec, whatever matches the output, it’s OK. Still thinking through it
Ivan Herman: I am worried that what’s described is an implementation strategy, not a requirement for a spec
Rob Sanderson: +1 to Ivan
Ivan Herman: we should make sure that we don’t define the process, but instead what we need to have as normative
Dave Longley: +1 to Ivan
Ivan Herman: informatively, we can put in examples. What counts is the test cases
Benjamin Young: we currently don’t track term overriding and who overwrote what in what order
Dave Longley: +1 … that would be a helpful tool
Benjamin Young: so if you have two contexts and one overrides it, there’s no awareness of that in the code. So in a context dev, and to keep sealing in, it would be helpful to know what happened and in which order. that could clear a lot of confusion
Gregg Kellogg: My feeling tis that we’ve been overly prescriptive to ensure interoperability
… embedded contexts cerate a new ID and inherit from the one embedded
… so I think we need to try and describe that in a way that stays as close as possible to the behavior, and the mental model has to be described in the syntax doc to understand orders of operations
… but adding more complexity threatens to degrade performance
Rob Sanderson: in the proposal, does that include externally referenced, but scoped contexts? So if I had a doc that had sealing at the top level, and I scoped in schema.org within a term, would that then seal schema.org?
Dave Longley: {"@context": {"sealed": true, "foo": {"@context": "http://schema.org"}}}?
Rob Sanderson: does that seal by reference schema.org? if you had it as an externally reference, sealed context.
… what dave said in the chat
… what happens?
Gregg Kellogg: my feeling is that scoped context is not explicitly sealed. So, no. schema.org would not be sealed in that example.
… what you need to know is there is a reference, and we might restrict that to being things in a local/embedded context, have the ability to affect things that were defined in the outer context, but not implicitly sealed
… does the sealing act valid for everything, or are there parts like vocab that are not sealed?
Gregg Kellogg: three top-level directives: version, vocab, language, and base
… context is not a member of a context, it’s a member of a term definition
Dave Longley: i’ll just say — my view of “sealed contexts” is that someone made a specification for a bunch of terms (a “sealed context”) and JSON-only devs will read that spec and apply the rules therein — not running any JSON-LD processing after that… and we should consider how sealed contexts according to that line of reasoning.
Gregg Kellogg: the body is an object that contains term definitions, default vocabs…a term definition can itself be sealed, and if that includes an embedded context, and if that’s sealed, then the context that it defined in not implicitly sealed
… I can’t update the context with a new context…otherwise the use of context within a context is in the document, and….
… . too many uses of the word “context”.
Dave Longley: so if we want to allow people to write specs that say: “everything under this term will use schema.org’s context” … that’s what JSON devs would expect, no changes
Dave Longley: we could of course, require those spec writers to redefine all those terms manually if need be
Benjamin Young: the top level directives…is it imagined that those would be sealed?
Gregg Kellogg: we don’t seal base, vocab. if you want to seal, seal a term. if the default vocab is schema.org, and can’t override it…
Dave Longley: the main use is a spec, like W3c, and they’re defining terms in the spec, and will provide the context, and will only apply the rules in the spec.
Rob Sanderson: I agree with that too, but then to me it’s going to be clearer if the individual terms are sealed, rather than the terms defined in a context that’s sealed, but other features (e.g. base and vocab) are not sealed in that context
Dave Longley: first, you’re using JSON-LD to enable extensibility and semantics. that means that you want other terms to be created.
… so I think that losing .vocab won’t work. Sealed contexts should not be constrain things not defined.
… we should think of how they should behave within that domain.
… if we want to figure out how it should work, we should think about it in the context of a spec–if there’s a term not in the spec, you can ignore them.
… none of these term definitions will change. If you’ followed the path in the spec, nothing will change.
… that’s what the feature should guarantee
… everything else is outside of what people who care bout JSON will care about.
Benjamin Young: +1
Dave Longley: think about this domain through the lens of JSON-only developers
Rob Sanderson: Also +1
Ivan Herman: what would happen if Schema.org sealed that context?
Dave Longley: all that would happen is that the terms wouldn’t change.
Ivan Herman: using schema.org, some of the terms are underspecified. So what we do is add our own context that defines, with the same URL, we add additional constraints to the term.
… this would prevent this
Dave Longley: if you’re redefining these terms, this would lock that possibility.
Ivan Herman: even if I use the URL, but I specify the type..
Dave Longley: that’s a separate issue, but an important one
Ivan Herman: this happens a lot with schema.org a lot. Often I want to make them more precise
Benjamin Young: maybe, given large vocabs, sealing many terms, this maybe an API thing, but not a syntax thing? Can the processor seal/not-sealed to create a processor that says that this context is sealed
… but the developer chooses
… and then these terms are sacrosanct
… these are the terms my processor must understand
Gregg Kellogg: echoing ivan, schema.org author: Values are expected to be an org or person, but that’s defined without a type. JSON-LD processor will allow a string value there
Dave Longley: i’ll just say that’s interesting (doing this via an API mode/flags) Benjamin … and worth considering further.
Gregg Kellogg: not a URI.
Dave Longley: interesting, but i don’t think will work :)
Gregg Kellogg: that’s a case for updating it for author is explicitly a URI.
Rob Sanderson: +1 to dlongley, agree it needs to be syntactic
Dave Longley: a good idea, but there will be people who won’t know to read the spec and flip on the flags. it needs to be in the data.
Benjamin Young: we’ll see you in a week or less. look through it, add your notes, etc.

[iherman]

@pchampin I am perfectly fine with the content as is, thanks!

However... after our discussion before and after the F2F I think we should not use schema.org in the examples for sealing. Let us not give bad ideas... Nor should we use sealing with other 'generic' examples like foaf or dublin core.

To be honest I am not sure what example we should use; maybe some of the examples used by Digital Bazaar may be reused...

[pchampin]

@iherman My understanding was that a generic context, such as the one published by schema.org, should not be sealed. On the other hand, I see no problem in sealing a term that resolves to http://schema.org/name, as long as the context sealing it has a very specific use case (and requires no further specification of the terms it defines). In fact, I would even argue that it is good practice, for such a context, to reuse an existing IRI rather than coining its own...

But granted, this is a rather subtle distinction, and the examples may give bad ideas to context authors, giving the false impression that it would be ok to seal schema.org ...

We could use artificial vocabularies in the examples related to sealing, but I'm afraid that would make them harder to grasp.

[gkellogg]

Changes look good to me. Note that travis reports syntax errors in some examples. You should be able to use rake to check these before pushing now.

[iherman]

@pchampin, yes, I understand what you say, but I also see the subtlety...

Maybe make things explicit in a note? Ie, leave the examples intact, but add a note along the lines of:

Note that sealing a term may create difficulties if the corresponding vocabulary is frequently adapted for particular applications (e.g., defining a more precise datatype, restricting the term's use to lists, etc.). Publishers of general purpose contexts should use this feature with care.

WDYT?

[gkellogg]

Note that -- inside of <!-- --> is causing the HTML parser problems. Try using a unicode character such add – instead.

[pchampin]

@iherman you are right; I added such a note