Discussion: YAML versus JSON file format in the context of 'projmgr'

[jkrech]

In issue #12 YAML is proposed to be used for the input files: ctarget, cproject, clayer

We shall review pros and cons of either file formats, create and agree on a format in the context of this project and capture it in an Architecture Design Record (ADR).

Criteria:

• readability
• ease of editing / editor support
• validation / debugging
• popularity / usage
• TBD

[LMESTM]

Some extract from this week discussions, to be completed / corrected by all with more inputs:

YAML Pros: ability to comment, easier to edit manually, used in github, (seems it) can benefit from json schema
YAML Cons: comments may be discarded by few libraries (can be annoying), blank space / indentation may be error prone
JSON Pros: well known, json schema support, widely deployed and used in many technologies e.g. VScode, so many libraries available
JSON Cons: no native support for comment (though alternatives exist like //)

Bottom line, one needs to be selected and tried. Proposal from Reinhard: start with YAML as it was the initial plan and see if we face technical issues in the future development. In case of such issue, re-open the topic.

One action though : try and experiment schema with yaml.

[fred-r]

Indentation might be error prone and is too permissive in my opinion to keep it maintainable (then it becomes not easy for a human to read it):
https://yaml.org/spec/1.2.2/#61-indentation-spaces

Probably we need to define rules to avoid that indentation becomes chaotic ?

Nevertheless, I am also puzzled by the human-readable/human-modifiable criteria.
To me we are talking about "project" files that the end-user should never need to look at.
We are not talking about the configuration file of an IDE for instance (like user settings).
It might even be very dangerous if the end-user starts messing around with the content of these files, especially if we use DRY concepts like anchors and extensions.

I wonder also how we are going to handle the comments, unless my assumption that we will try to handle these files with a UI and avoid the user looking at it is wrong ?

Maybe the assumption is more to let users write clayer and other projects files manually ?

Today in Keil uVision I do not need to edit such files manually and I can even manage CMSIS components and CMSIS packs graphically.
I think it is nice that the user does not need to go into these details.

[0xc0170]

I haven't yet read enough to understand of projmgr but assuming the format chosen, these files are meant to be readable and maintainable by users that use command line tools (not IDE). to describe software components, their relations and so on. These files are meant to be written by hand or by a tool (both options available).

These two formats we are discussing are very similar. I am happy with any of these two (rather than xml that I don't like maintaining due to its readability).

Indentation might be error prone and is too permissive in my opinion to keep it maintainable (then it becomes not easy for a human to read it):

You get an early error to show this. Also if we choose a format that does not require indentation, it is good practice to set a tool to ident it for you anyway. Otherwise spaces, indentation becomes a problem when manual edits are done or generated by external/internal tools - both should result with the same output (helps when comparing different versions - this might be one of the use cases why I would vote for readable format and have set of styling rules to follow).

Probably we need to define rules to avoid that indentation becomes chaotic ?

Lot of projects use 4 spaces or so anyway even if the format does not require it. Styling issues are the ones I don't want to have as everyone has different opinion if not predefined by a project.

It might even be very dangerous if the end-user starts messing around with the content of these files, especially if we use DRY concepts like anchors and extensions.

Command line tools - CI won't open IDE and select via click boxes or so, it uses cmd with files discussed here, they are generated and provided via cmd. So someone needs to maintain these files and edit via cmd.
Or generators, not certain if these files will be generated by other generator (Cmake generators or other tools), but they might be.

[fred-r]

Hi Martin,

interesting point about CLI indeed.
My thinking was that we would use CLI to generate code based on existing project files.
I did not envision the possibility to create a project with CLI only and user-written (manually) files.

I thought that CI would use preconfigured projects.
So we would still test in CI the tool but with predefined project files (like clayers).
To be clarified I guess, that's a very valid point.

Regarding the styling : actually I am not concerned only about using 4 spaces or 2.
What I see in the YAMl spec is that the only indentation consistency constraint you have is for siblings (as far as I understand, I might be wrong).
So you may use various levels of indentation if you wish and then it becomes not so readable and maintainable.
But if we agree on a style then it is solved.

[jkrech]

We have experimented and demonstrated the schema files for YML formatted files and e.g. integration with Visual Studio Code giving a good user experience including help with "wrong" indentations.
For the experimentation of the projmgr we have decided to go with YAML and revisit that choice afterwards.