Toml: Preferred syntax for pragmas/directives in comments

[tamasfe]

Is there a consensus on the syntax for metadata inside comments?

While in general I believe these kind of comments should be avoided inside TOML, sometimes they can be useful.

I believe there should be an endorsed way of doing this in order to mitigate every tool implementing their own approaches so that we don't end up with files looking like the example below:

##! my-tool-toml-version: v1
#:schema example.com/schema
# some-other-tool schema example.com/schema
#!! another_tool::schema=example.com/schema
[the-actual-data]
# ...

I'm currently using lines starting with #:, but I've seen ##! mentioned as well. I don't like the latter as it is too close to shebangs, but these are just two examples and probably more should be explored.

[pradyunsg]

Is there a good reason to not make these top-level keys in the file?

version = 1
my-awesome-tool.schema = "example.com/schema"

[tamasfe]

Yes, these pragmas are directed towards the tools working with TOML itself, giving hints on how to interpret it and what (not) to do with it.

I believe such metadata should be separated as much as possible from the actual data itself as it's just noise for the reader/writer who is only interested in the actual configuration data for the application or whatever TOML is used for.

Your suggestion would also fail as soon as a target application started denying unknown fields, which is a good practice in order to avoid typos and other kinds of misconfigurations.

There could be name clashes as well, what if both the application and the TOML tool used the version or any other entry? This would never happen with comments as the target application would just ignore them.

Also I imagine some TOML formatters might introduce pragmas to configure formatting for regions, which are only possible with comments.

[eksortso]

So far, it seems to me that endorsing any one particular way of doing pragmas would yield little reward. Not a job that the standards project ought to perform.

You're rejecting top-level keys. So if all pragmas are just going to be in comments, why not let the parser writers do what they feel is best, regardless of aesthetics, and have those various parties resolve conflicts and set standards between themselves?

Perhaps you could provide a few concrete examples in order to flesh out your reasoning.