Delete `@context` from examples so as to not mislead readers

[selfissued]

https://www.w3.org/TR/2024/WD-controller-document-20240817/#example-controller-document-with-a-controller-property Some of the examples imply that a @context property is needed in Controller Documents, which isn't the case. The @context property should be deleted from the examples. Or if there isn't consensus to do that, let's at least delete it from every other example.

[msporny]

There won't be consensus to remove the @context property from all examples, deleting it from every other example seems arbitrary and confusing as well. For the purposes of consistency, it was agreed that we'd include @context in every example.

[selfissued]

This issue should be discussed by the working group, particularly in light of @jyasskin's pending TAG review comments.

[decentralgabe]

Is the data model a JSON-LD data model? If so, @context in every example makes sense. If not, then having some examples without @context makes sense.

[msporny]

Is the data model a JSON-LD data model?

Is @context not allowed in a JSON document? :)

We could add examples of Controller Documents that don't have @context entries, and if we do so, we should do it in a way that's not as arbitrary as making every other example not have it w/o an explanation.

[selfissued]

For what it's worth, there's at least one Controller Document example in the spec that's not JSON-LD: https://www.w3.org/TR/2024/WD-controller-document-20240817/#example-minimum-conformant-controller-document

[iherman]

The issue was discussed in a meeting on 2024-09-04

• no resolutions were taken

View the transcript

#### 2.6. Delete `@context` from examples so as to not mislead readers (issue controller-document#54) _See github issue [controller-document#54](https://github.com/w3c/controller-document/issues/54)._ **Brent Zundel:** and focus on discuss issue. … delete `@context` from examples. **Manu Sporny:** removing the `@context` from every other example feels arbitrary and confusing. … we can have an example that shows you can do it either way. … `@context` is a valid JSON key, so it doesn't change the document from being JSON. … the challenge with removing it is what happens to the extensibility model? > *Michael Jones:* [https://github.com/openid/federation/issues/35](https://github.com/openid/federation/issues/35) includes an example without `@context`. **Manu Sporny:** the only alternative I've heard is a centralized registry. … which is something the DID WG did not feel was a good path forward. … so this raises the question of extensibility. > *Michael Jones:* The following example provides a minimum conformant controller document containing a minimum conformant verification method as required by the algorithm in this section: ``` Example 16: Minimum conformant controller document. {. "id": "https://controller.example/123",. "verificationMethod": [{. "id": "https://controller.example/123#key-456",. "type": "ExampleVerificationMethodType",. "controller": "https://controller.example/123",. // public cryptographic material goes here. }],. "authentication": ["#key-456"]. }. ``` **Michael Jones:** example 16 doesn't have a `@context`. … my suggestion was a straw man. … I'm fine if we delete them from half of them. > *Manu Sporny:* -1 for "half of them" -- again, it's arbitrary. **Ivan Herman:** I do not think we should restart the JSON-LD or not conversation again. > *Manu Sporny:* +1 to Ivan - we can do that in the conformance section. **Ivan Herman:** for the sake of simplicity, we just say `@context` is optional but keep it in all the examples. **Brent Zundel:** so, is `@context` a normatively required property. **Michael Jones:** no. **Brent Zundel:** than maybe we just have one example with it in with all other required properties. **Michael Jones:** per the chat, I just put a link to a rendering of the document that shows that a minimal document doesn't need an `@context`. … I don't want to confuse people that it's necessary. **Manu Sporny:** to follow up on ivan and brent. … example 16 is the minimal example, we can start with that. … ivan also said for the sake of uniformity we can do the same thing we did with languages. … totally fine with having a couple examples not having `@context` in it, but I think removing it from half is arbitrary. … for the people who don't want to use `@context`, we already have clear statements and examples that show it's not required. **Joe Andrieu:** just because we have an example doesn't mean we have consensus on that example. … there doesn't seem to be a technical argument for 50%. … if there are specific ones where having it is confusing, we could address those. … I think this mostly hinges on whether we have a concrete serialization or not. **David Chadwick:** I think since it's optional only one example should have it and the rest not. **Brent Zundel:** please add further thoughts on the issue.

[msporny]

In order to make progress at W3C TPAC, I am suggesting that this issue is "editorial" and can be resolved during the Candidate Recommendation phase. The VCWG will discuss this issue at W3C TPAC to see if the "during CR" determination is correct.