To what extend do we enforce a language for adapter configuration files

[uekerman]

To what extend should the adapter schema enforce the language of the adapter configuration file?

v0.2 of the guidelines say:

preeco-orga/guidelines/guidelines-adapters.md

Line 74 in 543f29c

- [ ] R.10: The configuration follows the [preCICE Adapter and Tooling Configuration Schema](https://github.com/precice/preeco-orga/blob/main/adapter-config-schema/preatcs.json), either directly in JSON or indirectly via LLM-based auto-conversion. Using the standard name `precice-adapter-config.json` is possible (if JSON). Validating a JSON configuration against a schema can be done with the Python library [jsonschema](https://pypi.org/project/jsonschema/) or via the [JTutor GUI](https://validationproofs.oa.r.appspot.com/), for example.

(we should actually remove the "LLM-based" and allow any conversion)

So, we currently do not enforce any format and there are good reasons for this as summarized by @MakisH: #18 (comment)

Should we still tend towards a certain configuration language and if yes, which one?

If for a certain adapter or tool, there is no good reasons to use a solver-specific configuration, we could still weakly recommend using either YAML of JSON. This could further improve interoperability, since the conversion could be skipped.

Pro JSON:

• Currently widely used in the preECO ecosystem. Inertia.
• Since the schema is currently in JSON, we do not require conversion for validation.
• Better tooling support? For YAML, we have to go via yaml-cpp for CPP codes?

Pro YAML:

• Easier to read and write for humans.

[MakisH]

Should we enforce?

I understand the concept of a schema as the abstract representation of what goes in such a file, with names and relations, but irrelevant of the implementation language. As such, I think we don't need to enforce.

As long as we can convert between formats (which a schema should by definition enable us to), even if we currently don't have deterministic ways to convert between all formats, I also don't think we need to enforce.

Given that:

1. in the end this will require additional effort for the maintainers of each non-conforming adapter to port it
2. it might introduce additional technical challenges to them (e.g., additional dependencies, which might not be stable),
3. and it is not strongly motivated ("I can do the same I could do before, but now I need to port all my code and cases")

I think we should not enforce.

Should we encourage?

Yes, definitely! We should lead with an example to follow, but state that old adapters are still fine.

If yes, which language?

As I wrote in more detail #18 (comment), the choice for JSON is mostly historical/inertia. Since we are currently in the process of designing the ecosystem as we want it to be, I think it is wrong to make the choice solely based on what is widely used.

The reasons should be usability-focused, given technical restrictions.

In the end, it might be neither JSON nor YAML, but something else. But I agree that these are good starting points.

Disclaimer

I have no objection in porting any adapter myself to what we decide to. I am just imagining how I would argue with users about this.

[Logende]

Pros and Cons:

JSON:

• more easier to implement support for it
• more libraries

• looks complicated/overwhelming for non computer scientists

YAML

• more user-friendly

• wrong indentation leads to errors
• might be more difficult to work with in the code

[fsimonis]

YAML is easier to read and write than JSON.
YAML does have parsing complications though, which is pretty much why TOML exists. However, I think that we will not end up with YAML parsing ambiguities and the more verbose format of TOML makes it an inferior default choice.

I suggest to use YAML by default primarily as it will make adapter documentation easier to write and read.

[uekerman]

I think there is no harm in encouraging YAML and JSON both as good options.

I suggest to use YAML by default primarily as it will make adapter documentation easier to write and read.

Just as a side note: As a vision, the schema should make quite some adapter documentation redundant 🤞

[fsimonis]

Just as a side note: As a vision, the schema should make quite some adapter documentation redundant 🤞

I mean that it allows to write easier to read documentation on adapters in general, which should be able to apply to all adapters. At least structurally.

[MakisH]

Something important we discussed but is not yet mentioned here: in JSON we cannot have comments, in YAML we can.

[uekerman]

New solution in #50

The configuration follows the preCICE Adapter and Tooling Configuration Schema, either directly in JSON or YAML or indirectly via auto-conversion. Using the standard name precice-adapter-config.json is possible (if JSON). Validating a JSON configuration against a schema can be done with the Python library jsonschema or via the JTutor GUI, for example.

Good enough to close here?

[MakisH]

#50 makes the YAML explicitly allowed. We are not yet giving a clear language guideline, but I understand that we are implicitly encouraging JSON and to a lesser extent YAML.

Maybe it's just too soon to give a concrete recommendation here, and it is apparently a hot topic. Good thing is that we accept more options now.