Add example that does not contain @context.

[msporny]

This PR is an attempt to address issue #54 by adding an example that does not contain an @context property.

---

Preview | Diff

[dlongley]

See suggestion to make the example valid.

[David-Chadwick]

It would be helpful to the reader to provide a description of the controller document underneath it such as:
This controller document for "id": "https://controller.example/101", says that a signature from the subject of this id can be authenticated using the public key "#key-20240828"

[msporny]

@David-Chadwick wrote:

It would be helpful to the reader to provide a description of the controller document underneath it such as: This controller document for "id": "https://controller.example/101", says that a signature from the subject of this id can be authenticated using the public key "#key-20240828"

I agree, and we do this in multiple sections throughout the specification... when we introduce a new property, we provide an example and explain what the property does. If we added that text here, we'd re-state things stated earlier in the specification.

I do also admit that we need to make another editorial pass on the examples to make sure they're properly explained, as @David-Chadwick notes. I've raised an issue to track that concern here: #125

[iherman]

The issue was discussed in a meeting on 2024-11-20

• no resolutions were taken

View the transcript

1.6. Add example that does not contain @context. (pr controller-document#124)

See github pull request controller-document#124.

Brent Zundel: Again, nothing but approvals.

Manu Sporny: This was another request from Mike Jones. The current controller document says that if you don't want your document to be processed in a JSON-LD environment, you don't need to include context.
… Organizations that want to verify against JSON-LD can inject context.
… Mike suggested removing context from all other examples but there was resistance.
… Leaves the question of where we include them or not in the spec.
… I would like to include @context in other examples. Right now, it's sporadic throughout the document.
… Except for the ones that explicitly state that it's possible to work without a context.
… There are also examples in the appendix that should be updated.

Brent Zundel: I don't find the lack of consistency to be confusing.

Ivan Herman: +1 to Brent.

Brent Zundel: Folks reading the entire spec will figure it out. My proposal is to do nothing, asking folks to consider that as a path forward.

Kevin Dean: The challenge with examples is that as you move through a specification, you are building up capabilities until by the end of the document you have a complete specification.
… The natural flow for a specification for a feature in this section to be using features in prior sections. There are seldom forward references, having examples follow that pattern, making examples consistent -- you can rely on examples, is useful as a way of understanding the specification.
… The absence of a context line in an example, when it's closely related to example in previous section, could be confusing for neophyte readers, left out because it is an example of how to do this without a context.

Manu Sporny: +1 to what Kevin said.
… What we have in the spec right now are examples created by people who wanted JSON Web Key stuff.
… We have examples with context, then without context, then with context. It can be confusing.

Dave Longley: -1 as that would imply that JsonWebKey won't work with contexts which is not accurate.

Manu Sporny: I can put together a PR for it. The key here is that we provide examples that are what we believe best practice to be, which can launch another debate I don't want to get into.
… Can we please get examples that are best practice that don't get into the JSON/JSON-LD debate.

Brent Zundel: I don't think we can. Past discussions of best practices have gone long and not reached a resolution.
… Happy to see PR that structures examples aligned with how the specification develops. I would love to see someone restructure the document.
… I haven't encountered people who are confused by the spec. If there are folks who are, I would like to hear from them.
… Let's see PR to modify things if folks want to do that.
… As far as this PR goes, I'm not hearing anyone to say not to merge this one.
… Happy to take more comments, or move on to next PR.

[selfissued]

Suggested change

	<pre class="example nohighlight" title="A controller document without an @context property">
	<pre class="example nohighlight" title="A controller document without a @context property">

[TallTed]

I generally read @context as "at-context", not as "context", partly because it is distinct from context. That reading makes an @context ("an at-context") appropriate, not a @context ("a at-context"). Perhaps others should weigh in, so we can decide which indefinite article to use throughout.

[jandrieu]

I tend toward TallTed's perspective. I have a similar inner voice that pronounces the @: "at-context".

But I think it's more important to figure out one way and be consistent.

A bit of sleuthing shows @selfissued's take shows up once in the JSON-LD spec, but the spec also uses "an @context" six times.

[TallTed]

@jandrieu — Thanks for that sleuthing. w3c/json-ld-syntax#448 created to make that errant a match the other six an.

[David-Chadwick]

I also read it as "an at-context"

[msporny]

Yes, the Editors have attempted to consistently read @context as at context and therefore try to keep a consistent rule of us an vs. a.

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.