TOML as an RFC?

[mnot]

Have you considered publishing v1.0.0 as an RFC?

I can see two immediate benefits:

• The format would be easier to use / reference from other RFCs and by other standards efforts.
• You could get application/toml registered¹.

If you'd consider it, I'd be happy to help - you don't have to go through the full standards process, the independent stream would be very appropriate for this and comparatively lightweight.

Footnotes

1. You don't need an RFC for the full format to get the registration -- but it does require some sort of standards publication. ↩

[paulehoffman]

+1 to the "happy to help". @mnot and I both have written dozens of RFCs (although none together, yet).

[pradyunsg]

Have you considered publishing v1.0.0 as an RFC?

Yes! That's the motivation behind keeping the language grammer in ANBF.

IIUC, the blocker here is one of the authors figuring out the "paperwork" of the process and doing it. Help would very much be welcome! :)

[paulehoffman]

If one of the main contributors wants to step up as the primary author, I'm happy to walk you through the paperwork. @mnot will probably do so as well, and may agree with me on some of it. :-)

[mnot]

Definitely. Consider us at your disposal. From our side, we just need buy-in from the TOML project and someone to work with; we can handle the process issues, etc.

[eksortso]

I'm just a bit player here. But with a number of serious enhancements in the pipeline, TOML v1.1.0 would be a better candidate for an RFC once it's released. Is there an immediate demand for an RFC to be filed now, or can we take the time to propose one with TOML's new features?

Deferring until the v1.1.0 release would also give us an opportunity to move toward a set of documents that would line up more with the requirements of an RFC, where it would make sense to further that process in the project as it stands.

[ChristianSi]

Yes, I agree. The changes made since TOML 1.0 are significant and certainly justify the release of 1.1 in the foreseeable future. So, to be really future-proof, that's a better target for standardization.

[arp242]

I did a bit of work to write an "RFC-style" specification for TOML; still some work to do (I just wrote it as Markdown for now, as that's easier for me so I can focus on the text and not formatting).

An RFC will "lock down" TOML quite a bit; which is both a good and bad thing: it's good so we have a stable format we can rely on the long term, it's bad since updates will be harder. I think it would be good to make sure we really have everything nailed down first.

Looking at the open issues/PRs, "Add a duration/timedelta type" and "hex floatingpoint values" are something we can still go either way on; there's no clear consensus. "Implementation-defined values", "custom type syntax", and "add Filesize" seem like a fairly solid "no". "Relax comment parsing" is WIP, and the others are all clarifications or other things that don't really change the semantics.

I propose a future "TOML 1.1" (whenever that will be released) functions as a "RFC release candidate"; we can wait for a bit after its release for feedback from implementers and users, maybe make a few tweaks if need be, and then submit the RFC.

[paulehoffman]

I'm happy to help with the mechanical part of the RFC process, including the Markdown stuff.

[robertlagrant]

Just wondering if this is likely to happen. I don't see it in the registry. We have a use for it!

[eksortso]

Your use may give this process a boost! What's your use case?

[aamelnikov]

Hi,
I am one of designated expert reviewers for Media Types appointed by IETF and I just received a request to register application/toml using the following template:

---

Name: Ben van Hartingsveldt
Email: ben.vanhartingsveldt@yocto.com
Media type name: application
Media subtype name: toml
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: 8bit
Security considerations: (1) TOML files don't contain executable content.
(2) Information contained in TOML files do not require privacy or integrity services. If a client is storing information that is potentially sensitive, some sort of security is recommended. TLS, and specifically HTTPS, are the recommended way to protect potentially sensitive information.

Interoperability considerations: N/A
Published specification: https://toml.io/
Applications which use this media: Various
Fragment identifier considerations: N/A
Restrictions on usage: N/A
Provisional registration? (standards tree only): No
Additional information:

1. Deprecated alias names for this type: none
2. Magic number(s): none
3. File extension(s): .toml
4. Macintosh file type code: TEXT
5. Object Identifiers: none

General Comments:

Person to contact for further information:

1. Name: Ben van Hartingsveldt
2. Email: ben.vanhartingsveldt@yocto.com

Intended usage: COMMON

Author/Change controller: Ben van Hartingsveldt

---

Do you have any objections/support/have correction(s) to this registration?

In particular note that the "Change controller" is the person who is contacted when further changes (for example if you decide to publish an RFC describing TOML format) to the media type registration are suggested. (Also note that there is no implication that the Change Controller of the registration has any control over the underlying format.)

Best Regards,
Alexey

[paulehoffman]

The TOML project seems to be either dead (stuck at 1.0.0) or badly wedged; see #928

Having a media type that does not specify the version may be acceptable, but is possibly dangerous, given that the proposed changes in 1.1.0 are breaking changes to the allow bytes in the format (that is, new restrictions on which Unicode charaters are allowed). OTOH, I'm sure that there are similar problems with other formats that have media types.

[arp242]

In particular note that the "Change controller" is the person who is contacted when further changes (for example if you decide to publish an RFC describing TOML format) to the media type registration are suggested. (Also note that there is no implication that the Change Controller of the registration has any control over the underlying format.)

I don't think this person has had any involvement in TOML (AFAIK); I don't think it's a good idea to record them as the contact.

I don't really know who would be; the project is in a "absent maintainer, but not handed over to anyone else"-state.

Also:

Encoding considerations: 8bit

I'm not sure what "8bit" refers to exactly here, but TOML files are always UTF-8 (which is "8 bit" for some but not all meanings of it).

[aamelnikov]

In particular note that the "Change controller" is the person who is contacted when further changes (for example if you decide to publish an RFC describing TOML format) to the media type registration are suggested. (Also note that there is no implication that the Change Controller of the registration has any control over the underlying format.)

I don't think this person has had any involvement in TOML (AFAIK); I don't think it's a good idea to record them as the contact.

I don't really know who would be; the project is in a "absent maintainer, but not handed over to anyone else"-state.

Thank you.

Also:

Encoding considerations: 8bit

I'm not sure what "8bit" refers to exactly here, but TOML files are always UTF-8 (which is "8 bit" for some but not all meanings of it).

This field is actually an enum with 3 choices: 7bit, 8bit and binary. 8bit is anything excluding NUL, so UTF-8 without NUL seems consistent with that.

[aamelnikov]

The TOML project seems to be either dead (stuck at 1.0.0) or badly wedged; see #928

Having a media type that does not specify the version may be acceptable, but is possibly dangerous, given that the proposed changes in 1.1.0 are breaking changes to the allow bytes in the format (that is, new restrictions on which Unicode charaters are allowed). OTOH, I'm sure that there are similar problems with other formats that have media types.

Existence of 2 versions is probably a "Interoperability consideration" for the registration template.

[notpushkin]

@aamelnikov Thanks for looking into this!
Would you recommend getting a provisional registration for TOML in meantime?

[ChristianSi]

@aamelnikov While all the suggested values seem correct and I suppose this is a good-faith submission, having as change controller someone who seems to be unrelated to the TOML project is not a good idea, so I too suggest not to accept this submission for now.

Regarding the state of the project: it's currently stalled, because @pradyunsg, the sole remaining maintainer, has largely become inactive but failed to appoint any successors so far. However, there's still hope that that'll change sooner or later and at that point things might move swiftly again.

As for incompatible versions, there's actually no need to worry about that. All versions, from fairly early drafts (I think) up to the latest 1.1 draft, are backwards compatible. As TOML uses semantic versioning, the first breaking changes might come with 2.0, and that's certainly a long time off, if it ever comes.

[paulehoffman]

I agree that having an unrelated person as the change controller is a bad idea. @ChristianSi: are you maybe willing to step up for that role? There is nearly nothing to do but be available for questions in the foreseeable future.

As for the "incompatible versions" part: is there a full list of diffs from 1.0.0 to the intended 1.1.0? I thought that I saw the allowed characters list in parts of 1.1.0 was smaller, meaning that some valid 1.0.0. documents would become invalid. If I'm wrong about that, I'm happy.

[ChristianSi]

@paulehoffman:

@ChristianSi: are you maybe willing to step up for that role? There is nearly nothing to do but be available for questions in the foreseeable future.

Thanks for the suggestion, but while I'm involved with TOML, others such as @eksortso are even more so, and in any case I'm afraid that without a functional maintainer structure such a decision would be arbitrary.

As for the "incompatible versions" part: is there a full list of diffs from 1.0.0 to the intended 1.1.0? I thought that I saw the allowed characters list in parts of 1.1.0 was smaller, meaning that some valid 1.0.0. documents would become invalid. If I'm wrong about that, I'm happy.

Yes, see the "unreleased" section at the start of the Changelog.

There it says: "Relax comment parsing; most control characters are again permitted." So it's the opposite of what you thought: TOML 1.0 is fairly restrictive in what it allows in comments, possibly causing parsing to fail because of stuff that's commented out, which is unintuitive and might lead to nasty surprises, since people generally expect text in comments to be ignored rather than cause parsing errors. So TOML 1.1 attempts to correct that as far as reasonably possible, accepting more documents but never rejecting any that were already valid.

[mnot]

The change controller doesn't need to be a person -- e.g., if you have a community mailing list that could do it - or maybe even the GitHub issues list (although that might raise some eyebrows?).

Another approach would be to nominate Tom Preston-Werner.

[arp242]

Tom has been active even less than Pradyun.

I think the issue list is fine, and better than any single person. There isn't really an email address for it though.

[paulehoffman]

Or, maybe leave it blank. It is a "general comment", and I think a correct answer is "None". I like @mnot's suggestion, but that is probably a worse can-o-worms than "None"

[paulehoffman]

As for the "incompatible versions" part: is there a full list of diffs from 1.0.0 to the intended 1.1.0? I thought that I saw the allowed characters list in parts of 1.1.0 was smaller, meaning that some valid 1.0.0. documents would become invalid. If I'm wrong about that, I'm happy.

Yes, see the "unreleased" section at the start of the Changelog.

There it says: "Relax comment parsing; most control characters are again permitted." So it's the opposite of what you thought: TOML 1.0 is fairly restrictive in what it allows in comments, possibly causing parsing to fail because of stuff that's commented out, which is unintuitive and might lead to nasty surprises, since people generally expect text in comments to be ignored rather than cause parsing errors. So TOML 1.1 attempts to correct that as far as reasonably possible, accepting more documents but never rejecting any that were already valid.

Thanks! I had misread this in some other comment in an issue or PR. I'm happy that alll of what is proposed is forwards-compatible.

It would be grand if @pradyunsg would cede control to one of the many people here who seem eager, we get 1.1 out, and then put it in the freezer.

[aamelnikov]

The change controller doesn't need to be a person -- e.g., if you have a community mailing list that could do it - or maybe even the GitHub issues list (although that might raise some eyebrows?).

Another approach would be to nominate Tom Preston-Werner.

Tom Preston-Werner should probably be listed as "Author", but doesn't need to be "Change Controller".

[aamelnikov]

@aamelnikov Thanks for looking into this! Would you recommend getting a provisional registration for TOML in meantime?

I had to research this :-). Provisional might be the next best thing, but I think this can be registered in the main registry after some changes to the submitted registration template are made.