Subject: [Jsonpath] Use of non-normative text

From: [email-masked]
Date: Tue, 27 Oct 2020 10:24:37 +0000

We've recently clarified the semantics of array slice notation in our
I-D ([1]) and tested it by having someone implement an array slice
function from the spec alone. This is all well and good for
implementers, but another audience for an I-D is users of JSONPath. It
may be helpful to include some non-normative text to give users a bit
of a gentler introduction to that part of the spec.

So my question is: what's the best practice, if any, for including non-
normative text in an I-D?

(There's a clear notion of normative vs informational references, but I
haven't found any corresponding guidance for inline text.) 

[1] https://jsonpath-standard.github.io/internet-draft/

---

From: Brian Rosen <[email-masked]>
Date: Tue, 27 Oct 2020 09:31:17 -0400

Generally, normative text uses upper case SHALL, MUST, MAY, etc.  Informative text doesn’t.  That’s how you tell.  

> On Oct 27, 2020, at 6:24 AM, [email-masked] wrote:
> 
> -- 
> Jsonpath mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/jsonpath

---

From: Julian Reschke <[email-masked]>
Date: Tue, 27 Oct 2020 16:33:41 +0100

> Generally, normative text uses upper case SHALL, MUST, MAY, etc.  Informative text doesn’t.  That’s how you tell.

That's not really true in general.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 27 Oct 2020 18:53:55 +0100

> That's not really true in general.

Indeed.  A lot of normative text contains simple factual statements such as “a foo is composed of a bar and a baz”.  RFC 2119 interoperability keywords come in when there is a decision to be made by an implementation, and making the wrong decision will lead to less interoperability.  Such as "Messages with unknown version numbers MUST be silently ignored” because sending back an error message might lead to error message wars.

Really, we try to make the informative text correct, so it doesn’t hurt if it is taken to be normative.  (If the informative text is not correct, readers will be misled and thus interoperability hurt regardless of its normative status.)  Occasionally, we mark whole sections or appendices as informative; e.g., when a detailed rationale for a specific design is given.  But then, such text usually self-identifies its informative intention.

An example for this is examples.  Implementors often care for examples more than they care for text; understanding is often led by theory-building about what is seen in the examples more than by the often tedious text.  So examples MUST (see?) be correct, and we spend a lot of energy machine-checking (or machine-generating) the examples.

More generally speaking, we like our specifications to be somewhat redundant, so they can be self-checked; the intent is not for interpretation to lead to exactly one outcome but to the right outcome that supports interoperability (where reliably stating “the spec is broken” may be one such outcome).

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Oct 2020 12:44:05 +0100

Am 27.10.2020 um 18:53 schrieb Carsten Bormann:
> ...

Carsten, thanks for the well-written explanation :-).

As an additional data point: you can have a normative standards-track
document without using any UPPERCASE requirements at all; RFC 3986 is an
example for that.

Best regards, Julian