uses latest 3.1 OpenAPI schema for 3.0 openapi.yaml file

[pjungermann]

Scenario

You have an openapi.yaml file which starts with

openapi: 3.0.1
# [...]

When running v8r:

ℹ Processing openapi.yaml
ℹ Found schema in https://www.schemastore.org/api/json/catalog.json ...
ℹ Validating openapi.yaml against schema from https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json ...

# [...]

openapi.yaml#/openapi must match pattern "^3\.1\.\d+(-.+)?$"

References

https://www.schemastore.org/api/json/catalog.json contains:

{
  name: "openapi.json",
  description: "A JSON schema for Open API documentation files",
  fileMatch: [
    "openapi.json",
    "openapi.yml",
    "openapi.yaml"
  ],
  url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json",
  versions: {
    3.0: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json",
    3.1: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json"
  }
}

[pjungermann]

the discriminator for the versions is the openapi field. However, there is no info about this at the catalog.json at SchemaStore.

One option might be to check against both. (like wrapping them into anyOf or oneOf) However, as both can fail, it might be unclear to know which one to use.

[chris48s]

I think there's a couple of angles to think about this from.

---

Firstly, when it comes to solving this specific problem, there are a variety of ways you can explicitly tell v8r to validate your file against the correct schema. You could use:

• the --schema argument e.g: npx v8r@latest openapi.yaml --schema https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json
• a custom catalog
• a config file

so you've got a variety of options there.

---

Secondly, there's a whole bunch of schemas on schemastore where there are multiple different versions available. If I search for versions": { in https://www.schemastore.org/api/json/catalog.json I get 59 results. How to decide which one to use for each format is going to vary wildly. That is not really a problem I have the appetite to solve.

That said, the current behaviour of completely ignoring the existence of the versions object and just silently using whatever is in url is probably not optimal either. In the case where a versions key exists and contains >1 schema, I think it would be reasonable to make the user aware of this (in much the same way we do if there are >1 possible schemas we could use based on the filename/pattern): https://github.com/chris48s/v8r/blob/4db179a4f7d3eb444835c4a39d562f9a1697cee2/src/catalogs.js#L90-L92 I'm in 2 minds whether the most sensible behaviour in that case would be to use the default schema from url anyway (like we do now) and emit a warning, or fall over completely and force the user to pick.

[chris48s]

I've just released version 0.14.0 which resolves this issue.

I decided to always fail if there are >1 versions found of the same schema. This does mean that there are now quite a lot more cases where the user must explicitly make a choice, rather than v8r automatically picking a schema for you. The tradeoff is that this massively reduces the number of case where v8r selects a schema for you and it is the wrong one.

I think this is the right balance to strike.

[pjungermann]

Thank you! This sounds like a reasonable approach to me, too.

Overall, it would be great of the SchemaStore would provide tool authors the means to make this decision without custom support for each case. However, this is not the case.

So far I used the local schema catalog approach to force the 3.0.x schema.