Subject: [Json] Two Documents

From: Douglas Crockford <[email-masked]>
Date: Thu, 13 Jun 2013 08:50:33 -0700

The confusion and controversy around this work is due to a mistake that I
made in RFC 4627. The purpose of the RFC, which is clearly indicated
in the title, was to establish a MIME type. I also gave a description of
the JSON Data Interchange Format. My mistake was in conflating the two,
putting details about the MIME type into the description of the format. My
intention was to add clarity. That obviously was not the result.

JSON is just a format. It describes a syntax of brackets and commas that
is useful in many contexts, profiles, and applications. JSON is agnostic
about all of that stuff. JSON shouldn't even care about character encoding.
Its only dependence on Unicode in the hex numbers used in the \u notation.
JSON can be encoded in ASCII or EBCDIC or even Hollerith codes. JSON can
be used in contexts where there is no character encoding at all, such as
paper documents and marble monuments.

There are uses of JSON however in which such choices matter, and where
behavior needs to be attached to or derived from the syntax. That is
important stuff, and it belongs in different documents. Such documents
will place necessary restrictions on JSON's potential. No such document
can fit all applications, which causes much of the controversy we've seen
here. One size cannot fit all. JSON the format is universal. But real
applications require reasonable restrictions.

So we should be working on at least two documents, which is something we 
have
discussed earlier. The first is The JSON Data Interchange Format, which is
a simple grammar. The second is a best practices document, which recommends
specific conventions of usage.

---

From: John Cowan <[email-masked]>
Date: Thu, 13 Jun 2013 11:57:10 -0400

Douglas Crockford scripsit:

> The confusion and controversy around this work is due to a mistake
> that I made in RFC 4627. The purpose of the RFC, which is clearly
> indicated in the title, was to establish a MIME type. I also gave
> a description of the JSON Data Interchange Format. My mistake was
> in conflating the two, putting details about the MIME type into the
> description of the format. My intention was to add clarity. That
> obviously was not the result.

Indeed.

> So we should be working on at least two documents, which is something
> we have discussed earlier. The first is The JSON Data Interchange
> Format, which is a simple grammar. The second is a best practices
> document, which recommends specific conventions of usage.

Fine, but the definition of the application/json media type can't be
exiled to a BCP.  It either has to be in a separate standards-track RFC,
or needs to be in the same RFC as the definition of JSON format but in a
different section of it.  The latter strikes me as more sensible.

-- 
John Cowan                                   [email-masked]
        "You need a change: try Canada"  "You need a change: try China"
                --fortune cookies opened by a couple that I know

---

From: Douglas Crockford <[email-masked]>
Date: Thu, 13 Jun 2013 09:11:47 -0700

> different section of it.  The latter strikes me as more sensible.
I think it will be better for ECMA that application/json be in a 
separate document.
ECMA does not appear to be concerned with the maintenance of MIME types.

---

From: Mark Miller <[email-masked]>
Date: Thu, 13 Jun 2013 09:21:46 -0700

I support separating these documents, and directing the present activity
towards standardizing the JSON Data Interchange Format. I agree that this
focuses the activity on which IETF and ECMA need coordinate.

On Thu, Jun 13, 2013 at 9:11 AM, Douglas Crockford <[email-masked]>wrote:

> ______________________________**_________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/**listinfo/json<https://www.ietf.org/mailman/listinfo/json>
>

-- 
Text by me above is hereby placed in the public domain

  Cheers,
  --MarkM

---

From: "Markus Lanthaler" <[email-masked]>
Date: Thu, 13 Jun 2013 18:50:14 +0200

On Thursday, June 13, 2013 5:57 PM, John Cowan wrote:
> exiled to a BCP.  It either has to be in a separate standards-track
> RFC, or needs to be in the same RFC as the definition of JSON format
> but in a different section of it.  The latter strikes me as more
> sensible.

+1 and I also think that it makes more sense to put the media type
definition in the same RFC.

--
Markus Lanthaler
@markuslanthaler

---

From: Tim Bray <[email-masked]>
Date: Thu, 13 Jun 2013 09:55:02 -0700

I think we have widely-shared agreement on two documents, a JSON spec and a
best-practices doc.  Just a word of caution, though: Our profession has
ample experience with the notion of “abstract syntax” - in ASN.1 and in
SGML.  Neither of which ever exhibited good usability in Internet
protocols.

One of the central defining virtues of the Internet and the Web is that
there are no object models or APIs, just messages. It is the job of the
IETF to define the message formats and interchange patterns.  Which is to
say, a document that defines a syntax but omits discussion of how that
syntax is expressed in bytes for transmission on the wire is not really
appropriate subject matter for the IETF.

The end-goal is pretty clear, I think: As someone who regularly works on
the design of network protocols based on JSON, I want an RFC to turn to
that will have nice crisp definitions of “JSON text”, “object”, “array”,
“string”, “number” and “boolean” so I can use those confidently in my
protocol design, and also sufficient precision about byte encoding that I
can rely on infrastructure builders to have created interoperable libraries
that work well on a variety of platforms and architectures.

It would also be nice if there were a best-practices document so that
someone could review my design and berate me for something stupid like
allowing the use of duplicate keys, and have something to point to.

So... two documents, yes.  Abstract syntax, no.

 -T

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 13 Jun 2013 22:55:52 +0200

> So... two documents, yes.  Abstract syntax, no.

+1

The JSON data interchange format has no use if it is floating in the air.
It must have both feet firmly on the ground, in concrete syntax, in bits and bytes.
(And one of the feet can be RFC 3629.)

RFC4627 managed to do this reasonably well, why should it suddenly be hard?

Grüße, Carsten

---

From: Nico Williams <[email-masked]>
Date: Thu, 13 Jun 2013 16:05:56 -0500

>> So... two documents, yes.  Abstract syntax, no.

To be fair "JSON in EBCDIC vs. JSON in UTF-8" are not really
comparable to "ASN.1 w/ DER vs. ASN.1 w/ PER -- a difference of
degree, though not of kind.  :)

> RFC4627 managed to do this reasonably well, why should it suddenly be hard?

It isn't.  I think the talk of EBCDIC was illustrative or best taken
as such.  Move along, nothing to see here :)

More seriously, we have to iron out the details of what strings really are.

I think we must prohibit certain unescaped code points, but we must
allow any 16-bit number \u-escaped.  This is tied to JavaScript's
handling of those code points as well as to the validity of
UTF-8-encoding those code points.

The best practices document should further recommend the use of proper
Unicode characters only in JSON strings.

Nico
--

---

From: John Cowan <[email-masked]>
Date: Thu, 13 Jun 2013 17:36:45 -0400

Carsten Bormann scripsit:

> The JSON data interchange format has no use if it is floating in
> the air.  It must have both feet firmly on the ground, in concrete
> syntax, in bits and bytes.

A concrete syntax in characters only is not useless.  Essentially all
programming languages are defined only in characters, and rightly so.
Even for special cases like JavaScript, it's sensible to define the
repertoire used by the language, but not the encoding(s) of the language.

-- 
My corporate data's a mess!                     John Cowan
It's all semi-structured, no less.              http://www.ccil.org/~cowan
    But I'll be carefree                        [email-masked]
    Using XSLT
On an XML DBMS.

---

From: Jacob Davies <[email-masked]>
Date: Thu, 13 Jun 2013 16:15:49 -0700

I think the current lucid, succinct text that describes a data model, a
language, and a byte serialization is so useful because it comprehensively
describes all three things. So I wouldn't break it up.

The byte serialization description is essential because in order to
actually use JSON for anything you must deal with some byte serialized
form, and in 99% of cases that will be the application/json form.

I advocated dropping the mentions of Unicode except in byte serialization
and character lookup for Unicode escapes. That's as a matter of clarity
since those mentions are extraneous, and also so that applications that
represent models without using Unicode or serialize to non-Unicode
encodings not described as application/json are not needlessly deemed
non-compliant. But I think those changes are relatively unimportant; few
people are going to be confused by the current text, and those who are
doing non-compliant things probably don't know or care.

---

From: R S <[email-masked]>
Date: Thu, 13 Jun 2013 18:42:57 -0700

> describes all three things. So I wouldn't break it up.

I also think it is useful. JSON is a wildly successful format, so that
leads me to believe that the current document got the level of encoding
precision just about right.

This dual-document proposal seems aimed at avoiding impractical character
encoding requirements. I am sympathetic to that. I would prefer two
documents over a single document with prescriptive and therefore incorrect
encoding directives.

- Rob

---

From: Tim Bray <[email-masked]>
Date: Thu, 13 Jun 2013 19:01:25 -0700

> documents over a single document with prescriptive and therefore incorrect

I think it’s pretty clear that 4627bis can’t retroactively rule out things
that are already in JSON like naked surrogates. So with luck we’re good
with a single JSON spec that says so, then another best-Internet-practices
one that says “don’t”. -T

>
> - Rob
>
> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json
>
>

---

From: Eliot Lear <[email-masked]>
Date: Thu, 13 Jun 2013 22:49:00 -0400

Hi Douglas,

I think your suggestion of two documents is an interesting one.  One way
to go would be to create the 2nd document and include what needs to be
included there, and then decide LATER whether to merge the two documents
back.  If the best practices document ends up not being excessive in
length, then perhaps there's no harm in adding stuff back to the main
document, so long as it is clear what is normative and what is advice.

Eliot

---

From: "Matt Miller (mamille2)" <[email-masked]>
Date: Tue, 18 Jun 2013 00:14:32 +0000

Hello Douglas,

In order for the WG to fully understand your proposal, we need a more definitive list of what to expect in each document.

As a starting point, can you describe which sections of the current RFC4627 would be in "JSON Data Interchange Format" and which would be in the JSON best practices document?  Clearly the latter will have many additions from the recent discussions, but it is less clear which portions of the current text goes into which document.

Thanks,

- m&m

Matt Miller < [email-masked] >
Cisco Systems, Inc.

On Jun 13, 2013, at 9:50 AM, Douglas Crockford <[email-masked]> wrote:

> So we should be working on at least two documents, which is something we have

---

From: Vinny A <[email-masked]>
Date: Mon, 17 Jun 2013 22:19:52 -0500

> As a starting point, can you describe which sections of the current RFC4627 would be in "JSON Data Interchange Format" and which would be in the JSON best practices document?  Clearly the latter wi…

Obviously I'm not Douglas, but I'd like to make a proposal in this department.

The simplicity of the JSON standard has proven to be one of the many reasons why it's so popular. It would be a shame if we ended up bloating the official standard with miscellaneous nitpicks and advice. Clearly the standard needs some touch-up work (duplicate keys, for instance) - but it should be limited to just that, touch up work.

Everything else should be reserved for the best practices document; basically the rule of thumb would be that any new topics should be moved to best practices, while any current topics in the RFC should stay. Here's a short list of potential best practice topic candidates (additions/deletions welcome): 

- Unicode processing
- Runtime/Wire format recommendations
- Streaming parser recommendations
- Additional MIME types
- Comments
- String comparison
- Miscellaneous

-----------------
Vinny
www.jsontest.com

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 18 Jun 2013 07:04:28 -0700

> Obviously I'm not Douglas, but I'd like to make a proposal in this department.

<grumpy hat>

Not only are you not Douglas (who made the original proposal, and thus the question was directed at him), you did not even answer Matt's request. Douglas proposed two documents but did not clearly state what might be removed from the current WG draft; knowing that will help the WG decide whether or not to adopt Douglas' proposal. Your list of ideas for the new document is fine, but is out of scope for the current charter *unless* you are proposing to remove sections from the current WG draft.

--Paul Hoffman

---

From: Douglas Crockford <[email-masked]>
Date: Tue, 18 Jun 2013 19:06:22 -0700

> As a starting point, can you describe which sections of the current RFC4627 would be in "JSON Data Interchange Format" and which would be in the JSON best practices document?  Clearly the latter wi…
Please excuse the lateness of this reply. I am traveling.

I am proposing that The JSON Data Interchange Format document contain 
only the material that is universal to all applications of JSON. So, for 
example, the only dependency on any character encoding is the 
interpretation of the four hex digits in the \u notation, where Unicode 
determines the meaning of the numbers.

It includes an abstract, an introduction, the detailing of the elements 
(object, array, string, etc), and security considerations. No parsers or 
generators, no octets, no MIME types.

This provides a standard description of JSON that all other standards 
and practices may refer to. I think this is the standard that ECMA wants 
to publish.

We can then consider other documents that constrain or interpret JSON 
for specific purposes. The poorly named application/json is one. JSON as 
a file format, JSON as a streaming format, and JSON as an embedded data 
representation are others.

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 18 Jun 2013 20:01:44 -0700

<two chair hats on>

On Jun 18, 2013, at 7:06 PM, Douglas Crockford <[email-masked]> wrote:

> I think this is the standard that ECMA wants to publish.

As you know from our earlier off-list discussions, you do not represent ECMA, nor even TC39, to the IETF, nor even to this WG. Everyone from TC39 represents themselves here. Your statement above still implies authority that doesn't exist.

ECMA and TC39 leadership has had, and probably will continue to have, discussions about whether ECMA wants to have an official position on what they want to see from the IETF. Until we hear that from those higher-ups, no one speaks for ECMA here (and no one speaks for the IETF in TC39). Please try harder to refrain from suggesting that particular technical or process decisions would be what ECMA wants. Thanks in advance.

--Matt and Paul

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 18 Jun 2013 20:14:03 -0700

<no hat>

On Jun 18, 2013, at 7:06 PM, Douglas Crockford <[email-masked]> wrote:

> It includes an abstract, an introduction, the detailing of the elements (object, array, string, etc), and security considerations. No parsers or generators, no octets, no MIME types.

The parser and generator sections define interoperability specifications. Removing them is a huge change to the technical specification, one that feels well outside of the "minimal changes" in our charter.

I still want the WG to later work on an implementation guidance document after we have finished work on refining the current technical specification; in fact, it is probably negligent if we don't make a run at that. But calling requirements on parsers and generators "implementation guidance" at this late date seems like a very bad move.

--Paul Hoffman

---

From: Rick Waldron <[email-masked]>
Date: Tue, 18 Jun 2013 23:22:54 -0400

cc es-discuss

On Tue, Jun 18, 2013 at 11:01 PM, Paul Hoffman <[email-masked]>wrote:

> As you know from our earlier off-list discussions, you do not represent
> ECMA, nor even TC39, to the IETF, nor even to this WG. Everyone from TC39
> represents themselves here. Your statement above still implies authority
> that doesn't exist.
>
> ECMA and TC39 leadership has had, and probably will continue to have,
> discussions about whether ECMA wants to have an official position on what
> they want to see from the IETF. Until we hear that from those higher-ups,
> no one speaks for ECMA here (and no one speaks for the IETF in TC39).
> Please try harder to refrain from suggesting that particular technical or
> process decisions would be what ECMA wants. Thanks in advance.
>
> --Matt and Paul
>

---

From: Mark Miller <[email-masked]>
Date: Tue, 18 Jun 2013 20:39:43 -0700

>> represents themselves here. Your statement above still implies authority
Hi Paul, I'm missing all the context, but from this out of context
fragment, your response seems inappropriate. A statement like Doug's "I
think this is the standard that ECMA wants to publish" sounds to me like
speculation on how TC39 will react to some proposed standard. Whether
coming from someone on TC39 or not, I do not see that any assertion of
authority is involved. Here on es-discuss, both members and non-members of
TC39 speculate and argue all the time on what kinds of things TC39 might
approve of. Member of TC39 participate in these discussions, not to speak
for TC39 as a whole, but to speak a) for themselves as participants in
TC39, and b) as someone who is more informed than most, but still fallible,
speculating about howTC39 might react to something. Perhaps this line gets
blurry sometimes, but a statement like "I think this is the standard that
ECMA wants to publish" seems to me clearly on the non-blurry side of that
line.

If the context changes how all this would be interpreted, my apologies.

> es-discuss mailing list
> [email-masked]
> https://mail.mozilla.org/listinfo/es-discuss
>
>

  Cheers,
  --MarkM

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 18 Jun 2013 20:47:54 -0700

On Jun 18, 2013, at 8:39 PM, Mark Miller <[email-masked]> wrote:

> Hi Paul, I'm missing all the context, but from this out of context fragment, your response seems inappropriate. A statement like Doug's "I think this is the standard that ECMA wants to publish" sounds to me like speculation on how TC39 will react to some proposed standard.

If that's truly the case, such speculation from a random person is fine. Clearly, Douglas is not a random person: he is both the author of RFC 4627 and a TC39 member. If he meant to make that statement as neither, he needs to have said so.

> Whether coming from someone on TC39 or not, I do not see that any assertion of authority is involved. Here on es-discuss, both members and non-members of TC39 speculate and argue all the time on what kinds of things TC39 might approve of. Member of TC39 participate in these discussions, not to speak for TC39 as a whole, but to speak a) for themselves as participants in TC39, and b) as someone who is more informed than most, but still fallible, speculating about howTC39 might react to something. Perhaps this line gets blurry sometimes, but a statement like "I think this is the standard that ECMA wants to publish" seems to me clearly on the non-blurry side of that line.

Different SDOs have different customs, and in the IETF, custom says that you make clear when you are speculating and when you are representing. Douglas' earlier statement about ECMA was misinterpreted by WG members, so it felt worthwhile for the chairs to make clear who is and is not representing whom to the IETF.

--Paul Hoffman

---

From: "Markus Lanthaler" <[email-masked]>
Date: Wed, 19 Jun 2013 09:40:49 +0200

On Wednesday, June 19, 2013 5:14 AM, Paul Hoffman wrote:
> The parser and generator sections define interoperability
> specifications. Removing them is a huge change to the technical
> specification, one that feels well outside of the "minimal changes" in
> our charter.
> 
> I still want the WG to later work on an implementation guidance
> document after we have finished work on refining the current technical
> specification; in fact, it is probably negligent if we don't make a run
> at that. But calling requirements on parsers and generators
> "implementation guidance" at this late date seems like a very bad move.

+1

--
Markus Lanthaler
@markuslanthaler

---

From: Stefan Drees <[email-masked]>
Date: Wed, 19 Jun 2013 13:13:05 +0200

+1

---

From: Tim Bray <[email-masked]>
Date: Wed, 19 Jun 2013 07:33:21 -0700

Let’s take a moment to consider who our audience is.  The RFC will be used
almost exclusively by JSON parser and generator implementors. Out in the
general population of JSON users, the only docs they look at are the docs
for the parser/generator library they’re using.

And if I’m an implementor writing a JSON parser or generator, well, yeah, I
care about the abstract grammar and the security issues, but I also care
about what the incoming sequence of bytes is going to look like, and what
the outgoing sequence of bytes needs to look like.

So I think it would be abusive to our customers to make them read two
documents to get their jobs done.  I’m scratching my head to think of
anyone who would read one of these documents but not the other, and I’m
coming up empty.

 -Tim

On Tue, Jun 18, 2013 at 7:06 PM, Douglas Crockford <[email-masked]>wrote:

>> In order for the WG to fully understand your proposal, we need a more
>> definitive list of what to expect in each document.
>>
>> As a starting point, can you describe which sections of the current
>> RFC4627 would be in "JSON Data Interchange Format" and which would be in
>> the JSON best practices document?  Clearly the latter will have many
>> additions from the recent discussions, but it is less clear which portions
>> of the current text goes into which document.
>>
> I am proposing that The JSON Data Interchange Format document contain only
> the material that is universal to all applications of JSON. So, for
> This provides a standard description of JSON that all other standards and
> practices may refer to. I think this is the standard that ECMA wants to
> publish.
>
> We can then consider other documents that constrain or interpret JSON for
> specific purposes. The poorly named application/json is one. JSON as a file
> format, JSON as a streaming format, and JSON as an embedded data

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 19 Jun 2013 16:49:30 +0200

On Jun 19, 2013, at 05:14, Paul Hoffman <[email-masked]> wrote:

> interoperability

That is the operative work here.

We write standards track specifications to foster interoperability.

If you can't go away with a standards track spec (and the documents it normatively references) and independently create something that then interoperates, the spec has missed its mark.

The WG is specifically tasked with taking the existing RFC to standards-track, so any change that counteracts that objective is a non-starter.

So +1 to what Paul and Tim said.

Grüße, Carsten

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Wed, 19 Jun 2013 15:00:22 +0000

I agree with Tim.  I think we can make it crystal clear with wording and
structural changes at what point a person that already has a stream of
codepoints (rather than a stream of octets) starts implementing.

Of course, I want to make sure we don't *prohibit* more performant
processors that both decode and parse in one pass, but that won't work for
JSON.parse unless ECMA allows JSON.parse to also take a typed array in
addition to a string or adds JSON.parseBuffer.

On 6/19/13 8:33 AM, "Tim Bray" <[email-masked]> wrote:

>Let¹s take a moment to consider who our audience is.  The RFC will be
>used almost exclusively by JSON parser and generator implementors. Out in
>the general population of JSON users, the only docs they look at are the
>docs for the parser/generator library
> they¹re using.
>
>
>And if I¹m an implementor writing a JSON parser or generator, well, yeah,
>I care about the abstract grammar and the security issues, but I also
>care about what the incoming sequence of bytes is going to look like, and
>what the outgoing sequence of bytes needs
> to look like.
>
>
>documents to get their jobs done.  I¹m scratching my head to think of
>anyone who would read one of these documents but not the other, and I¹m
>coming up empty.
>
>
> -Tim
>
>
>
>On Tue, Jun 18, 2013 at 7:06 PM, Douglas Crockford
><[email-masked]> wrote:
>
>additions from the recent discussions, but it is
> less clear which portions of the current text goes into which document.
>
>
>
>
>interpretation of the four hex digits in the \u notation,
> where Unicode determines the meaning of the numbers.
>
>specific purposes. The poorly named application/json is one. JSON as a
>file format, JSON as a streaming format, and JSON as an embedded data

-- 
Joe Hildebrand

---

From: John Cowan <[email-masked]>
Date: Wed, 19 Jun 2013 11:03:32 -0400

> anyone who would read one of these documents but not the other, and I’m

People who are reading or writing JSON text with general editors are the
obvious targets for a syntax-only document.  One group would be
programmers dealing with JSON literals; another would be people writing
books or papers or standards that involve JSON examples.  This group
doesn't care about encoding or security, but I agree that they would
not be injured by an RFC that contains this information, provided it is
not intertwingled with the syntax.

-- 
The first thing you learn in a lawin' family    John Cowan
is that there ain't no definite answers         [email-masked]
to anything.  --Calpurnia in To Kill A Mockingbird

---

From: Nico Williams <[email-masked]>
Date: Wed, 19 Jun 2013 10:30:44 -0500

On Wed, Jun 19, 2013 at 9:33 AM, Tim Bray <[email-masked]> wrote:
> almost exclusively by JSON parser and generator implementors. [...]

+1.

I'd be OK with separating a description of JSON from any text talking
about parsers and encoders, but all of that should be in the main doc.
 (Remember, we already have a second doc: the best practices doc.)

---

From: "Pete Cordell" <[email-masked]>
Date: Wed, 19 Jun 2013 16:37:03 +0100

Original Message From: "Tim Bray"

> anyone who would read one of these documents but not the other, and I’m

My feeling is that the current JSON spec has warts, largely due to 
ambiguity, that many of us would like to see resolved, but by the nature of 
backwards compatibility we can't fix them with a one document strategy.

I'm musing that what I'd ideally like to see is a document to describe JSON 
as it currently is, warts and all, in a document called "The JSON Data 
Interchange Format".  As much as anything this would highlight ambiguities 
in the current spec, but not necessarily resolve them.

Then have a separate spec named along the lines of "The Good JSON Data 
Interchange Format" that has a structure similar to the first, but has 
wording along the lines of "A good JSON parser MUST..." etc.

Hopefully the second one can be effectively JSONbis and a single document 
source for anybody that wants to go that route, and is also less ignorable 
than an informational BCP for those that like to cut corners on 
implementation.

Pete Cordell
Codalogic Ltd
C++ tools for C++ programmers, http://codalogic.com
Read & write XML in C++, http://www.xml2cpp.com

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 19 Jun 2013 18:14:25 +0200

On Jun 19, 2013, at 17:37, "Pete Cordell" <[email-masked]> wrote:

> can't fix them with a one document strategy

It is still possible to have a section with behavior that the spec accepts as legacy but doesn't approve of.
Concentrate it into a section so the rest stays readable without a million exceptions.

Cf. the "BWS" (bad white space) in HTTPbis:

   BWS is used where the grammar allows optional whitespace, for
   historical reasons, but senders SHOULD NOT generate it in messages;
   recipients MUST accept such bad optional whitespace and remove it
   before interpreting the field value or forwarding the message
   downstream.

This is quite different from "best practices" in that it is a legacy-based addition to the accepted set, not a restriction of the accepted set based on some "best practices".

Not part of the desirable spec     Allowed by the desirable spec
                                |                 _______________
                                |                /
                                |                \
                               /|                /
                              / |                \    Best
                             /  |                /     Practices
                            /   |                \
                           /Barf|                /
                           \ bag|                \
                            \___|                 \
                                |                  \_____________
                                |

The main part of the normative spec would describe the vertical line.
That special section with legacy behavior we can't get rid of in the normative spec is marked "Barf bag" for brevity above.
The "best practices" are over in desired land, but way more restricted.

Grüße, Carsten