ADL formalisms

[joostholslag]

@pablo let’s do the discussion here:

@pablo

+1 on the comment by @sebastian.iancu I don’t want to start a discussion on which format is “better”, just wanted to point out those formats were mentioned in the NL SEC meeting.

@pablo

is that for JSON there is a schema, which is more convenient for validation, though there are some adaptations to use JSON Schema to validate YAML, and there is certainly a simpler JSON ↔ YAML conversion than XML or other standard formats to JSON.

@pablo

Though my personal preference would be not to have one single “preferred” format, but instead having a standard serialization and deserialization process to/from many formats to the AOM 1.4 an 2.x, that allows then to have bidirectional format transformations like format1 → AOM → format2 (change format1 and format2 to whatever you want). That way we can support multiple use cases. For instance, if I need to display an archetype on a web app, I would prefer JSON because of the browser’s native support for JS. For storing ADL I would prefer YAML because it’s smaller. So using the best format for the job.

Ideally I’d have ADL artefacts in YAML primarily, because of (arbitrary) legibility over json, do validation using json (or yaml) schema. And work together on an export/serializer to json (in this case of the archetype, not the aom/adl meta schema).
Off course I’m not against serialising archetypes to json also. But the risk I see if we don’t pick a single preferred format for hand editing, is we end up with a lowest common denominator.

@sebastian.iancu

yaml comes besides readability also with some advantages over json, like comments, typing, tagging

These are some important advantages I think we wouldn’t want to loose.
Also tool support can become confusing. A ‘single’ conversion algorithm from yaml->json would be much more scalable than each tool having to support both yaml and json editing and conversion.

@damoca

An archetype is not a simple configuration file, as the examples provided show. It is a very nested structure where the use of brackets would be very welcome, instead of having to control the indentation levels by spaces. Just imagine having to add a sibling node here in a plain text editor. It is not about the number of keystrokes, but about the possibilities of introducing errors.

This is indeed a major disadvantage of yaml.