Fix: #38. Stubs Conformance.

[ioggstream]

This PR

• stubs conformance

---

Preview | Diff

[gkellogg]

Might want to make actual definition references using data-cite for these terms. The JSON-LD spec created a "Definitions" section and defined the imported terms locally, which were themselves references. Might want to do something similar for consistency.

E.g.:

  <dt><dfn data-cite="JSON-LD11#dfn-json-ld-document">JSON-LD document</dfn></dt><dd>
    A <a>JSON-LD document</a> is a serialization of
    an <a>RDF dataset</a>.
    See the <a data-cite="JSON-LD11#json-ld-grammar">JSON-LD Grammar</a> section in JSON-LD 1.1 for a formal description.
  </dd>

These are defined in https://github.com/w3c/json-ld-wg/blob/main/common/terms.html and used with some clever code which tries to only define those terms actually used. I'm not proposing that we do that here, or that we use the local definition for for imported terms, necessarily, but structure them similarly.

[ioggstream]

I suggest to do this referencing job in a subsequent editorial PR once the referenced terms are consolidated
filing another issue like #40

JSON-LD ... defined the imported terms locally

IIUC, in json-ld there are copy-pasted definitions from other documents. Is that correct?
I think we should just use references, so that people is encouraged to read the original documents:
an implementer is expected to read the JSON, JSON-LD and YAML spec.
The fact that they won't do it should be addressed e.g. in the Appendix.

In my recent ramblings on other specs I spent a good amount of time replacing copied definitions with hrefs to make them coherent with the latest HTTP spec (RFC9110): this work would have been easier if they just used hrefs :)

WDYT?

[gkellogg]

IIUC, in json-ld there are copy-pasted definitions from other documents. Is that correct? I think we should just use references, so that people is encouraged to read the original documents: an implementer is expected to read the JSON, JSON-LD and YAML spec. The fact that they won't do it should be addressed e.g. in the Appendix.

Not exactly, consider the term "JSON object". It has an entry in the dl for Terms imported from Other Specifications, but the key is a reference to RFC8259. But, by defining a dfn for this, we can simply use <a>JSON Object</a> rather than the more lengthly <a data-cite="RFC8259#section-4">JSON Object</a> within the body of the document for every occurrence; it will use the reference directly into RFC8259, rather than that in the dl. It simplifies later usage, and provides a single place for us to describe the terms we are importing, vs defining. Yes, there is a brief description, but that is mostly to describe the context for usage within JSON-LD, not to repeat the definition from the referenced spec.

[ioggstream]

brief description ...

@gkellogg ah, ok. I'll file it in a separate, editorial, issue. Since I'm working on 4 other I-Ds, it would be great if during today's call we could find someone volounteering on those editorial stuff.

See #47

[ioggstream]

Moved the other issue to #47. @gkellogg feel free to merge

[TallTed]

"YAML document" has been carefully edited out of most of this document, so perhaps it should be removed here as well?

Suggested change

	The terms YAML, "YAML document", "YAML representation graph",
	The terms YAML, "YAML representation graph",

[gkellogg]

@ioggstream I'll hold off on merging this until you've responded.

[ioggstream]

The original text is ok to me. Let me just rebase the PR @gkellogg :)

[gkellogg]

PR is merged, thanks.

[gkellogg]

This PR was discussed in the 2022-07-06 meeting, and it was agreed to merge.