flathub-infra
Keep comments in JSON template files
Oke, let's first preface this issue: I know that JSON doesn't officially support comments. As such, I think it's a poor format for any non-machine communication, and really it should never have been used as a templating/config format.
That said, Flatpak does allow comments in their JSON files and this is often important for package maintainers as they can use those comments to highlight important or unconventional elements of their manifest. Sadly, the external data checker doesn't respect these comments.
I would recommend you to use JSONC when parsing and writing JSON-based manifest files, so that comments can be preserved for future maintainers.
JSONC is a different standard. It seems mostly compatible with normal-json-with-C-style-comments, but relying on this unintended compatibility seems like a bad idea, adding risk to write a json file that won't be readable by flatpak-builder. flatpak-builder uses json-glib (which permits C-style comments), so we use it for loading files as well, thus ensuring compatibility with flatpak-builder. But json-glib doesn't preserve comments on write (at least I don't know a way to make it to). So, I don't see a reliable way to achieve this. Maybe ask json-glib devs about a way to preserve comments?
Sounds good, I've made an issue upstream: https://gitlab.gnome.org/GNOME/json-glib/-/issues/63
Actually, your proposal (to add jsonc support to json-glib) is better than mine. We probably couldn't use json-glib to write files, since its semantics are way too different from python dicts. If json-glib would support jsonc, we could use some python library for it.
You can also use "//" keys in your JSON manifest, wth the comment as a string value. These are valid JSON, explicitly ignored by flatpak-builder, and will be preserved by tools like this
@wjt This is what I usually suggest to people wanting comments in json, but this way you can't add multiple comments to the same node (it would be a duplicate key) and can't comment array items.
Got it. I agree it would be nice to preserve non-standard comments. If jsonc is de-facto compatible with what people use on Flathub (easy enough to verify if one has every repo cloned) then making flatpak-builder/json-glib use jsonc doesn't seem strictly necessary but it would indeed be nicer to use a standardized format. I have been frustrated in the past that json-glib comments can't contain URLs because the // after the URL scheme confuses json-glib's tiny brain.
If jsonc is de-facto compatible with what people use on Flathub
It's not compatible the other way round: what is valid for jsonc is not necessarily valid for json-glib's "extended" json. So, we can't guarantee that we write back files readable by flatpak-builder.