Subject: [Json] sourcecode type="json"

From: Carsten Bormann <[email-masked]>
Date: Tue, 26 Oct 2021 21:26:33 +0200

https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-08.html

includes a number of JSON examples, or at least it claims so.

We created 15 examples that are marked »<sourcecode type=“json”>«.  Of these, 3 are JSON, and 12 are a single member (or two) without surrounding braces, meant to be put into larger JSON objects.

E.g.:
https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-08.html#section-3.2-6

These braces can of course be added, but they are really noise distracting from the content that is in these members (and the objects formed this way may be valid JSON, but they usually aren’t valid SDF).

Should we introduce a new sourcecode type “json-members”?
Or should we bite the bullet and add the noise to get real JSON texts?

Grüße, Carsten

---

From: Pete Cordell <[email-masked]>
Date: Tue, 26 Oct 2021 21:18:58 +0100

> Or should we bite the bullet and add the noise to get real JSON texts?

For a fragment of something bigger in free-form text I'd add ellipsis 
either side, e.g.:

    ...
    "namespace": {
      "cap": "https://example.com/capability/cap",
      "zcl": "https://zcl.example.com/sdf"
    },
    "defaultNamespace": "cap",
    ...

Is there not a precedent using things other than JSON (such as code 
samples) that offers guidance on whether to keep with a type="json" or 
add a new type?

HTH,

Pete.
-- 
---------------------------------------------------------------------
Pete Cordell
Codalogic Ltd
Read & write XML in C++, http://www.xml2cpp.com
---------------------------------------------------------------------

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 27 Oct 2021 09:58:09 +1100

For http, we use 'http-message', which is defined to be either a full *or* partial message. Remember, this is not a media type...

> On 27 Oct 2021, at 6:26 am, Carsten Bormann <[email-masked]> wrote:
> 
> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json

--
Mark Nottingham   https://www.mnot.net/

---

From: "John Levine" <[email-masked]>
Date: 26 Oct 2021 20:36:05 -0400

>For http, we use 'http-message', which is defined to be either a full *or* partial message. Remember, this is not a media type...

Right.  We have lots of sourcecode which is a chunk of a program, not a full program.

If it's a chunk of JSON, call it JSON.

R's,
John

>> We created 15 examples that are marked »<sourcecode type=“json”>«.  Of these, 3 are JSON, and 12 are a single member (or two)
>without surrounding braces, meant to be put into larger JSON objects.
>> 
>> E.g.:
>> These braces can of course be added, but they are really noise distracting from the content that is in these members (and the objects
>formed this way may be valid JSON, but they usually aren’t valid SDF).
>>

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 27 Oct 2021 08:21:00 +0200

Thank you all for your great feedback.

> On 27. Oct 2021, at 02:36, John Levine <[email-masked]> wrote:
> 

That is certainly true of e.g. C language — there is no expectation that C language in a sourcecode block is a complete program.

The question is really why are we marking up sourcecode as to its type in the first place.

One need would be for rendering.
But amazingly, it’s 2021 and we don’t yet have syntax coloring in RFCs.
This, however, could be added from the information that is in the XML today; full JSON texts and JSON fragments probably can be handled by the same coloring engine.
(The coloring would be heuristic during rendering, not embedded in the XML; only the type information would be needed to select the appropriate heuristics.)

With FDT languages such as ABNF or CDDL, extraction is needed; since some ABNF/CDDL is just for exposition, extraction needs the distinction between that and the normative ABNF/CDDL; in recent RFCs that has sometimes been done by using the @name attribute alongside @type.

Apart from that, the needs I’m more interested in are as a support for authoring.
This is mostly based on extraction, but also on the ability to run CI processes on the sourcecode extracted (per-block and between them).
Additional metadata may be required as input to e.g. a validation process; YANG puts that into the “<CODE BEGINS>” line.

The specific question came up because I was adding some CI to the SDF spec repo.
Inevitably, that made me find one typo, which although not obscuring the intention, if undetected would sooner or later have led to an errata report.
I expect authoring tools like kramdown-rfc will provide some of this validation as a matter of course, but that requires metadata.
Of course, these don’t *have* to be saved in the XML, but for practical reasons much of the CI processing operates on the XML output.

So I’d rather have a way to embed metadata that is required for automatic processing (extraction, validation) in the XML.
This would also help with maintaining validation through the RFC production.

My current CI code has to guess whether type=json means JSON text or JSON fragment (where the latter is well-defined for SDF, but maybe not in general).
My concern is less that this adds 5 lines of code to the now 19-line validation script.
I’d rather not require that a validation step needs to guess the author’s intention.

(The next step then is to add CDDL validation for the JSON texts and fragments.
Additional metadata needed here is: which specific CDDL rule is intended to govern that text/fragment.
I’m not too happy if I need to cram that into @name, but it looks that way.) 

Grüße, Carsten

---

From: "John Levine" <[email-masked]>
Date: 27 Oct 2021 14:39:00 -0400

It appears that Carsten Bormann  <[email-masked]> said:
>One need would be for rendering. ...

>With FDT languages such as ABNF or CDDL, extraction is needed; ...

>Apart from that, the needs I’m more interested in are as a support for authoring.

That seems about right.  If we really care about extraction, we'd need attributes with
more clues about how to do it since in most languages unlike ABNF, the order in which
you paste fragments together makes a difference, and you often need hints about what
version of the language, e.g. python 2 vs python 3.

I don't think we should try and solve this problem now, just throw it on the heap of
things to donsider for xml2rfc v4.

R's
John