Providing examples to ICAR files

[donwilson-rezare]

Rezare is generating developer documentation based on our schema files. This includes the list of fields in the schema and their descriptions. We are also displaying the example(s) for the schema built from the examples defined in the schema. We would find it very helpful if the ICAR schema files included examples.

How would the ADE Working Group feel if we were to propose examples to some of the ICAR schema files (resource and type files)? @cookeac please schedule discussion of this in the next ICAR meeting

[cookeac]

Agreed we would test with one resource to ensure that code generation does not break. @donwilson-rezare to prepare a PR with examples in one resource. During review working group members using code generation will test this for Java and C#.

[cookeac]

We found a problem with adding "example": { ... } to the JSON schema files. This keyword is part of the JSON Schema specification (2020-12), but is NOT supported by OpenAPI "3.0". It is supported by OpenAPI "3.1.0" and later - which is the current main version of OpenAPI/Swagger (since 2021-02).

It is relatively easy to update OpenAPI files from "3.0.0" to "3.1.0", particularly as we have used mostly modern constructs. However, OpenAPI "3.1.0" expects JSON Schema 2020-12, which no longer supports "nullable": true. Instead, you tell the schema that you support "the null type".

For instance, instead of:

"specie": {
    "type": "string",
     "nullable": true
  }

You would substitute:

"specie": {
    "type": ["string", "null" ]
  }

This is probably solvable, but might it break generated code?

[cookeac]

Agreed we will investigate this.

[cookeac]

@donwilson-rezare we have now updated ADE to OpenAPI 3.1 so you can complete this work, but we have decided (meeting 2024-05-16) that it does not have to happen before ADE 1.4 is released.