Is `Example` a single example, or a list of them?

[dkoslicki]

In particular, for PR #7 , there is some confusion whether examples should be a single example, or a list of examples.

[edeutsch]

It might be a good goal to set the "example" for each property to a value such that if an object were manufactured using all the example values for the properties, it would make a nice standalone example object, either for autogen documentation purposes or even for functional test purposes. For example, I think SmartAPI does this to automatically manufactore "live" tests. and the OpenAPI autogen active documentation does this.

e.g., this autogen doc: https://arax.ncats.io/api/arax/v1.0/ui/#/query/query is built from "example" tags.

Perhaps use an "examples" property to provide a list of different values that might illustrate the range of possible values better?

I dunno, just ideas.

[patrickkwang]

I think this is the relevant documentation for OpenAPI 3.1, which uses JSON Schema 2020-12: https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.5 So with OpenAPI 3.1, we'd want something like this:

type: string
examples:
  - hello
  - goodbye

OpenAPI 3.0, on the other hand, uses a much older JSON Schema version that does not include any provision for examples. But OpenAPI 3.0 itself adds an example property, which should not be a list.

The values of our parameters are not OpenAPI schemas but JSON schemas, we just need to decide what version. This may be informed by our desire to incorporate them into the TRAPI OpenAPI schema, which is currently on OpenAPI 3.0. And none of this is meant to imply that the tools we use (Swagger UI) etc. handle any of these versions the way we hope.

[dkoslicki]

We decided to go the OpenAPI 3.0 direction and use example