[Examples] JSON doesn't support comments => most of the Examples are not valid JSON

[mwherman2000]

Reference: https://stackoverflow.com/questions/244777/can-comments-be-used-in-json

Reference: https://w3c-ccg.github.io/did-spec/#example-2-minimal-self-managed-did-document

[davidlehn]

It's a matter of making the examples more useful to explain concepts. It's a similar issue with ... that is in various places. I don't think all the examples are fully valid anyway. Is the desire to have every example be fully complete and valid? That seems like it would be more confusing to the reader. If the desire is to at least have valid JSON, a partial step could be to start comments and ellipsis with # instead and make the examples at least be valid YAML that is easily converted.

[aljones15]

we could prefix examples with example.js while it does introduce language specific features to the spec it at least means the examples could be cut and pasted into the browser console. p.s. it is a good idea to make sure all the examples are valid json and json-ld.

[peacekeeper]

I agree with @davidlehn that examples in the spec don't necessarily have to be 100% valid if they include comments or other obvious artifacts such as .... This makes it easier for a human reader to understand the examples. It would be different if e.g. a comma or quote is missing somewhere, then that should be fixed.

For completely valid, machine-readable examples, the Test Suite should be a useful resource.

Other specs like the Verifiable Credentials Data Model also have JSON-LD examples with comments.

@mwherman2000 can you live with this? Or do you believe all examples should be 100% valid?

[mwherman2000]

Should be 100% valid. ...unless they are obvious incomplete fragments of a complete JSON document ...there should be no non-standard/made-up constructs.

Specifications are for people who don't know any better.

[jandrieu]

I'm with @mwherman2000 on this. It's an unfortunate side effect of using JSON, but the examples should be valid or people will get confused when they try to interpret the examples in their own code and follow the pattern, adding comments and ending up with bad JSON.

[peacekeeper]

The VC data model spec also includes comment lines in the examples, but highlights them in gray. Would that be acceptable? And perhaps explain this somewhere in the Introduction?

I don't feel strongly about this either way, I'm also fine with simply removing all comments to make examples 100% valid.

[TallTed]

I would suggest a dual presentation -- one with the complete and clean JSON (or whatever else doesn't support inline comments), and one with the inline commentary that clarifies the thing being presented. Yes, this is somewhat duplicative, but I think it's worthwhile.

Graying out the comment lines is a helpful thing for the readability of the commented block, while making it clear what is not part of the real block, and having a clean, uncommented block which can be copied-and-pasted helps clarify what the "real" block can contain while providing a live sample.

[mwherman2000]

Another option is to display the JSON text with line numbers and then include line by line explanations in the body text that follows.

Grey highlighting of "comments" isn't acceptable to me unless the greyed text can be excluded from copy and paste operations across all devices.

[brentzundel]

Perhaps it would be sufficient to add a note to the spec that says the examples may include comments or other notation for clarity that are not pure JSON, and therefore the examples should not be copied/pasted.