Session Date/Time: 01 Apr 2026 14:00
Dave Robin: Barry, do you want to start the talking while I'm uploading something that is kind of the more current note?
Barry Leiba: Sure. Okay. We are at the top of the hour, so let's go ahead and get started. I'd hope we would get Rohan on, but maybe he'll come on later. So welcome to the "Let's get back to EDN literals" call. Carsten, why don't you start us off?
Carsten Bormann: Okay. Where is... there it is. Basically, as you said, we are going to focus on the EDN column of this working group. There are four different areas in which we work. Hi, Dave, do you want to say something?
Dave Robin: Oh, yeah. Sorry. Clicked the wrong button. Go ahead.
Carsten Bormann: No problem. Thank you. Um, so, yeah, what is EDN? So, EDN is something that has been part of CBOR for 12 years, so you will have met it in one or other form, often called diagnostic notation and so on. And EDN has come back into the view of the working group in 2023 when we started to look at the document that's called draft-ietf-cbor-edn-literals. And the objective of this work was to formalize the extensibility mechanism that had been part of some tools since 2021. And, um, so we completed this work in 2024, had a Working Group Last Call, submitted to the IESG, and then we had this avalanche of "wouldn't it be nice if" inputs. And one was that the draft-ietf-cbor-edn-literals document was written as an update to the two documents that already define diagnostic notation, 8949 and 8610. And several people in the IESG said let's have that in one document. So we had the editorial job of pulling out all that stuff from the existing documents. Also, there was a request to generate a normative ABNF. In the existing documents, diagnostic notation is described in English, and of course it's much better to do this in ABNF if you actually see this as something that will be subject to interchange. Now, the objective of EDN is not to provide a textual alternative to CBOR interchange format, but to provide a way to actually talk about it—I'll say that in a minute. But still, there are situations where it is useful to have a normative ABNF, even if our requirement to be strictly interoperable is maybe much lower here than it is for the CBOR format itself. After we had done this, people noted that we hadn't really addressed all the operational usability issues that we had found in the, like, 10 years this had been out there. So we actually started collecting usability issues, and then that's a big piece of work that Joe undertook because he is quite familiar with how, for instance, JSON is being used in various parts of the ecosystem. So, yeah, we did those. And finally, we actually found an extension point that we wanted to exercise right away. The draft-ietf-cbor-edn-e-ref document, that is parallel to the draft-ietf-cbor-edn-literals document, does that. So that's where we are. We had a document that was complete, sent it to the IESG, but then fell into this mission creep hole. And so 2025 was spent in readying this for a second Working Group Last Call. So the first half of 2025, we had discussions in the working group. In the second half, we had discussions in various offline off-list activities and in the GitHub repositories. But yeah, we are now getting close to being ready for a second Working Group Last Call. So just to remind everyone what EDN actually is good for. EDN answers the observation that some people like text-based representations of information. So that has been a theme of the internet for, I think, 50 years now. And on the other hand, we have seen that a lot of environments have done the move from text to binary, like the HTTP environment and so on. So this is no longer a defining property of the internet that we do everything in text-based way. But text-based representations are good for diagnostics, for setting up test inputs, including the test vector project. The test vector project makes use of an EDN file to actually define the input to it. We are using text-based representations for configuration files. And it's really good if your configuration files can talk about the same data objects that your protocol is about. So having a configuration file format that is able to express CBOR is really useful. And here we have the additional requirement to support revision-controlled configuration files, so things like the line structure suddenly plays a pretty important role. Um, yeah, we want to be useful for discussion on whiteboards. Well, we're not going to have ABNF for whiteboards, so that's maybe not so demanding, but yeah, it should be somewhat concise. And we want to use it in documentation, including RFCs. And somebody brought to the list a couple of hours ago that actually we have to be able to do useful EDN in 69 columns. And that's actually still a requirement, so we have another conciseness requirement. EDN is not meant to be the only text-based representation of CBOR. JSON, for instance, is also quite useful for that. And if I'm editing a CBOR file in Emacs, I'm looking at the YAML representation. But EDN is really useful for people who come from the JSON world. So I'm not going to go into all the things we did in the usability round. But the most recent change that essentially we stopped discussing in Madrid was supporting raw strings. Raw strings are strings that do not give the backslash some special meaning. So we avoid all the various forms of "quoting hell" that we run into. And yeah, there's the example here on the slide. It's not particularly great, but it shows that we can notate a text string that has a single backquote by simply doubling the backquotes, and we can actually give any number of backquotes as start and end and avoid having to do backslash processing in the text. And that, of course, also is an efficiency advantage. So we did two little tweaks to this: we swallow the first newline and we keep superfluous backquotes at the end of the string, which allow us to write everything as a raw string except the empty string. We cannot write the empty string as a raw string, but we have enough other ways to write empty strings that this is not really a problem. Um, so this was again ready in Madrid, and yeah, we did various implementation items. And the most recent change in the document is that we have ABNF for integrated parsers that use raw strings for hex and base64 byte strings. Um, so integrated parsers are always a little bit optional, but it seemed it would be a good idea to actually have them here. So this is now in -21. Um, so this is just a report. I have not seen any requests to change what is in the document here, but it's the most recent one, so it's probably a good idea to mention it. Then we have a current discussion about comment syntax. EDN was—or the original diagnostic notation was—meant to be used for data structures that are binary to a large extent. So having comments in there was always pretty important, and having those comments being concise also was important. So we simply put in a comment mechanism that everything that is between slashes is a comment. So these are our inline comments. And what we did in the meantime was to add end-of-line comments with a hash mark as the comment delimiter. And there is an issue number 82, which used the fact that we represented raw strings in some interesting ABNF as a checkpoint and say, well, we can do this with counted asterisks as well. We cannot only count backquotes, we can count asterisks, so we might be able to have single asterisk, double asterisk, and so on comments. Um, so yeah, I implemented that. It's not particularly hard to do this with a modern PEG parser. However, looking more closely at what people actually have been doing out there, there are lots of conventions. And I'm just mentioning Doxygen's convention because it has been out there for 30 years. There have been lots of conventions to use asterisks in an asymmetric way. So I think we, after some discussion on the list, we are approaching consensus that that's not something we want to support. The original idea of Issue 82 that was implemented in PR 83 probably is difficult. Now, we could simplify this to only do a single asterisk only, like the original PL/I comment convention that became the C comment convention. And that's, of course, much simpler to do. Vadim asks in the chat, "Does Doxygen break on ** / endings?" I have no idea. But Doxygen is just one example of people using asterisks in a way that wouldn't be compatible with symmetric asterisks. So while we were doing this, there has been a long-standing request to support JavaScript-style end-of-line comments. And that is also something that easily can be added. And if you look at the EDN ABNF prototype tool, that's now implemented in 05-25. So that is an ongoing discussion, which I think is somewhat converging. I have a slide that we could use while we—or look at while we are discussing this. So I think we have a pretty common perception that doing double slashes as end-of-line comment delimiters is useful because many people actually use that with JSON, use that as a JSON extension. I had a pretty humiliating event a couple of months ago where I used the kramdown-rfc feature that actually can check a figure that is in JSON whether it's actually JSON. And somebody put in comments into the example, and I said, well, you can't do that. That's not JSON and also kramdown-rfc is going to give you a warning. And it turned out it did not give a warning because the Ruby platform that kramdown-rfc runs on actually thinks that double slash and the PL/I comments are parts of JSON. Um, so those people haven't implemented JSON, they have implemented an extended form of JSON because they didn't know that JSON doesn't have comments. Anyway, so we can easily add double slash. That has one non-backwards compatible (NBC means non-backwards compatible) consequence: you can no longer have empty inline comments. Um, I have never seen anyone use empty inline comments, so maybe we can accept this non-backwards compatibility aspect. And I think that also was the summary of what Joe wrote on the mailing list. The second point we could change is putting in inline comments, not just as delimited by slashes, but if the slash is... no, it doesn't... Oh, yeah, yeah. You're right, Christian. You're right. But in Rust, this means the same thing that it will mean in EDN, right?
Christian Amsüss: Um, yes, but people—I'm just saying like people might have this around, and if they expected this to start a comment and like end it later in the line, things might... like, in the typical use case it won't change. Um, but some might be around. I'm not... yeah.
Carsten Bormann: Yeah. So I think what we have to do here is to evaluate the benefit of having JSON-extended compatible comments, the benefit versus the drawback of ruling out particular usages. So the triple slash that you have also would be used by someone who tries to write mechanically a comment that has a leading or a trailing slash because people who are using the EDN comment syntax as it's used now just habitually double any slashes in the comment. So if the first or the last payload character of your comment is a slash, then you would write a triple slash. So yes, that no longer works. And—but it's really about no longer being able to support empty inline comments. So back to the asterisk thing. The PL/I or C syntax for comments is quite well-entrenched because it has been around in the C language for much longer time than the double slash, which only came in at the end of the 90s following its adoption in the C++ language. So, yeah, double slash we want to adopt, so we will be compatible with C or C++ there, support C or C++ there as well. And, yeah, so here maybe the perception is that this is slightly less great to have as a non-backwards compatible change. And in particular, comments that just happen to start with a star—let's say an item list in a comment might trigger this leading star. Yeah, Michael answered the question that was in the chat. Yeah, exactly. Christian explained why this is not going to be in the non-backwards compatible area. So everything that we like to do will still work with double slash as an end-of-line comment, but there is a weird case about empty inline comments. I'm not sure what Christian is trying to say now.
Christian Amsüss: Um, my point is that like, as long as the double slash is inside a comment, only stem are like a single double slash in a comment that someone put there because they say, I don't know, http:// and it works so I don't have to bother with the weirdness of the comments, then that's fine because the first slash of those two is consumed by the end of the first comment and the second slash is consumed at the start of the other comment. Yes. But if someone had in their comment a consecutive sequence of an even number of slashes, then all of a sudden that becomes a comment that goes until the end of the line. Yes. I don't know—I don't know what we expect in terms of compatibility, so I'm just observing.
Carsten Bormann: Okay. So I was prepared to talk about inline comments. So, um, yeah, the question is do we add the secondary inline syntax that uses asterisk star characters so we can have an unadorned slash within such a comment? Well, my personal view here maybe is not so relevant, but I personally find this not so great. But several people have said they would like having that, so I think it's a good idea to have this discussion. So my observation here would be the various JSON extensions that are out there like JSONC and JSON5 and HJSON and whatever, they all would be useful as a source of copy-paste material where after copy-paste the comments will still work. So I think that is a functional aspect that is not entirely irrelevant. So being able to use a JSONC configuration file or to use parts of it for copy-paste to another EDN-based configuration file, that would be a good thing to have. Vadim pointed out that there are other comments like the Pascal alternative syntax for inline comments. The character to use in Pascal for comments is the brace. Um, we are using braces for maps, so we cannot use that. But, yeah, Pascal has the alternative syntax open parenthesis asterisk because some of the early platforms that Pascal was used on didn't have brace characters, in particular the CDC 6600 didn't have those. And we could do that. I'm not sure that that is so useful because it's not mutually copy-pastable with what we find in JSONC and JSON5 and HJSON and so on. But we could do that. Christian says, "will anyone know those anymore?" Yeah, Michael asks whether Rohan is needed to declare no objections. We need to take this to the list anyway. But I would really like to know whether in the room we have a feeling about those inline comments. Should we actually add those, which would be different from what's currently in the document? So the main branch of the document doesn't have the asterisk thing at all, and the pull request number 83 has any number of asterisks which needs to match—or actually the asterisks at the end need to be as many or more than the asterisks at the start.
Christian Amsüss: Yeah. Um, I brought up the multiple asterisks topic mainly because back when I first brought this up, probably a few years ago now, it was shut down based on "yeah, ABNF can't do that." And now that we have raw literals, you have found a way around it. So I didn't want this concern to go unchecked just because we didn't do things in the right order. Um, I still prefer that we have some asterisk form—some inline asterisk form. Doesn't need to be the arbitrary number because really for the arbitrary number case, um, like just use your editor's feature to comment stuff out. I'd like to have something in there that allows me to use URLs without completely changing my comment style, but it's something where I mainly want the working group to have the maturity to make an informed decision. So if it turns out that things do work better if we stick with the old form, fine with me. Um, I'd just like to have—make sure that people know what the options are and apply the rationale for whether or not we pick something consistently. Yeah. That's—so that's where I'm at.
Carsten Bormann: Um, my advice to a good way to put URLs into comments is use end-of-line comments. I think that the old way of writing comments in C only survived because they didn't go away while C was still in this transitioning phase where the double slash hadn't fully taken root, and that is now a quarter of a century ago. So, um, maybe to just say a bit more about why I care so much about things in inline comments. The tool that I'm writing for CBOR diagnostics will be used a lot to annotate CBOR that is decoded from a binary form for a user. So there will be a lot of mechanical expansion of descriptions. And if it—and that goes hand in hand with things like indentation, which are supposed to be consistent to a viewer. And that consistency gets easily broken when all of a sudden just because there's a moderately funny character in the description of a key, all of a sudden you can't even—it's not just like you have to do the comment in a separate line, you also have to like break the indentation between the map key and the map value, or you have to start shifting all the comments to the line above. So there's—that's—it's not always just as easy as, oh, in that case just do an end-of-line comment. Good. So I think that this is an absolutely valid reason to have them. And of course we don't know where EDN will take us in the long term. But, yeah, we have the opportunity to do this now with a slight non-backwards compatible impact. And, yeah, my personal style would be not to do this, but I think if there are good arguments why people want that, we should do it. So that's why this is the proposal on the slide. So does anybody want to—anybody who is here want to argue against that? So Rohan has argued on the mailing list. But does anybody feel this adds complexity? So I haven't implemented this, but I think it's four or five places in the ABNF where this style of comments is being used, and it's pretty easy to write a regular expression or ABNF for this kind of comments if you know your deterministic finite automata. So I don't think we will have implementation problems with that. Vadim, what are tags in JSONC? Well, I mean, we can restrict ourselves to, for example, only add the asterisk version and omit adding double slash. So my summary of the discussion—I'm not a chair of this group, but I still can summarize—is that we do have some sympathy to having the slash-star in there. And so I will make sure that the next draft I put in there and the implementation I have correctly do this. And while I'm doing that, I think we all can look into our collections of EDN and see whether anything in there breaks, to corroborate that maybe the danger of doing this comment thing is not that bad. So that's all I wanted to discuss today. I have a few more slides. Well, first of all, the plan. My plan would be to finish this discussion, merge any PRs that come out of this, close the relevant issue. And of course if anyone else puts in an issue, we will have to look at that. But generally do all this with a view of having Working Group Last Call in April, so we have a little bit of time to process the Working Group Last Call feedback, which we certainly will get. And do the processing in the month after the Working Group Last Call ends and submit to the IESG on May/June if we seem to have reached consensus. Barry.
Barry Leiba: And as chair, I would say that's a great plan. So does anyone think that plan is wrong or unachievable? If so, speak up now. And I see no one speaking up. So good. We have a plan. Let's go for it. Sorry, Vadim, I didn't get that.
Вадим Гончаров: I'll write it.
Barry Leiba: Oh, yeah, Christian repeated it in the chat. Um, yes, we clearly—the plan is agreed to on this call. We have other people who are participants and they need to participate in that. So go ahead, Carsten, continue.
Carsten Bormann: Okay. So with that, I wanted to use any remaining time we have on this call and talk about extensions. As I said at the start, the whole point of the project originally was to be able to do those extensions. And we have found two extensions, E and REF, that actually are really useful. And we just had the fun work to take a document that uses these extensions and convert it together with the RFC Editor into a form where this extension was not needed. And I don't want to have this kind of fun anymore. So, yeah, we should also work on the draft-ietf-cbor-edn-e-ref document and get this done. But there are a few other extensions floating around, and I think it's good to keep those in mind, even if whether we actually do these extensions is a separate issue. I need to remind people that this is a registry, so we don't necessarily need a document that is consensus of the IETF to do an application-oriented extension. It might then have a slightly less generic name. So ignore the names here; these are just names. So in the test vector project, Joe and I needed a way to represent non-finites that we don't have representation in EDN for yet. So that's the FLOAT extension that we have been floating. Um, there is—yeah, everything that's in here is not in the draft because these are new things coming up. BOTH is an interesting thing because I have been asked more than once by people whether they should put something in the raw byte string format—C0, AA, 88, or 101—to really show how this is represented, or into the semantic form, like the IP address 192.168.1.1. And, yeah, having something like a BOTH extension that says here are two ways to say the same thing, and if they are not the same thing, we have a bug in the specification and we need to error out. Yeah. It could be all... we haven't really said whether we have polymorphic prefixes. EQUAL sounds like it gives you false or true.
Christian Amsüss: Yeah, I think like—I was just commenting on like what else we could do with this. BOTH is probably a good name.
Carsten Bormann: Good. Yeah, but I think the concept is really useful. We need various type conversions and selections, so the JSON that we have in CDDL, we might want to have an EDN file that then becomes both a JSON document and an efficient CBOR document. We might want to do Base32. As you may know, the two Base32 formats that 4648bis defines are not universal. There is a third variant defined by Douglas Crockford which I think gets more attention. Anyway, we can do all these things in a completely different timeframe. And I wanted to point to the MAPKEY draft as a way to do way more powerful things in such an environment. But the MAPKEY draft isn't done yet, so it's right now just an idea that needs to be fleshed out. Anyway, so that I think we can finish this meeting with a feeling that we will have extensions. There are four extensions in the document right now, and we should go ahead and write up those other extensions but in a separate document, I think, or in separate documents, I think. Any comments on that? Vadim just commented that he sees them here for the first time, which is not a surprise because some of them I just invented yesterday. But, yeah, we now have those extension mechanisms and we can use them if writing an EDN document becomes painful in some way. Good. I'm done.
Christian Amsüss: Yeah. Um, Ira said we should try to have not too many documents for these. I think MAPKEY will need to be its own document because it just requires some development. On the CDDL side, we have had documents that defined extensions approximately every two years. So that might be one way of doing this, just collecting additional things beyond E and REF, which I think should sail on its own timeline, writing another document like 9165 or 9682, which has a batch of extensions, is probably the best way to get these documents looked at. Good.
Barry Leiba: So, thank you for taking the time to work on this today. Yes. Does anyone have anything else they think we need to talk about today?
Christian Amsüss: Um, I started trying to assemble an overview of the string types, but I think that best goes to the list, so I'll do that there.
Barry Leiba: Okay. All right. Well, yes. So we have a plan and a few weeks to do it. Let's proceed with great vigor.
Carsten Bormann: Yes.
Barry Leiba: All right. Thanks everybody. Bye.
Christian Amsüss: And thanks Michael for the notes.