Misleading introductory text in "Terminology" subsection

w3c / json-ld-syntax

JSON-LD 1.1 Specification

https://w3c.github.io/json-ld-syntax/

Other

112 stars 22 forks source link

Misleading introductory text in "Terminology" subsection #185

Closed pchampin closed 5 years ago

pchampin commented 5 years ago

The "Terminology" subsection starts with a sentence saying:

This document uses the following terms as defined in JSON [RFC8259]. Refer to the JSON Grammar section in [RFC8259] for formal definitions.

While this was true in the 1.0 spec, this section has been augmented with many terms that are not defined in JSON, but are specific to JSON-LD.

I would recommend rewriting common/terms.html to split it into two separate subsubsections, one with "borrowed" terms from RFC8259, and one with original terms.

NB: this also applies to other specs (API, Framing).

pchampin commented 5 years ago

Meta-question: is it proper etiquette if I tag this issue as spec:editorial, or is it the prerogative or chairs?

gkellogg commented 5 years ago

Its clearly editorial, and editors regularly make this determination. Of course, if contested, it can be determined not to be editorial.

gkellogg commented 5 years ago

I say we change the introduction to be more appropriate. The terms are already split into different parts, but not sections. We could use sub-section for these different bits:

Primitive datatypes from JSON, INFRA, and ECMASCRIPT. The only thing in that first bit we defined is the internal representation, which seems appropriate here.
Terms defined in other specs, such as RDF, IRI. We might include here our own terms, such as base IRI, compact IRI, relative IRI, and JSON Literal.
JSON-LD specific terms.

Perhaps we could say something like "From ECMASCRIPT we use the following terms:", and so on for the specs we import from.