OpenAPI 3.1 Schema causes errors in OpenAPI 3.0.x files

[ak1394]

VS Code YAML extension uses Schema Store https://www.schemastore.org/api/json/catalog.json to automatically guess and apply JSON Schemas to documents being edited.

My understanding is that if multiple schemas match a file, these schemas are combined and then used to validate the matching file.

It looks though, that schemastore.org contains schemas written in newer and yet supported by VS Code schema dialect.

In particular, I've started seeing that OpenAPI 3.1 schema https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json which uses Draft 2020-12 dialect is being applied to OpenAPI files.

I'm an author of OpenAPI extension (which depends on Redhat YAML one) and I'm seeing users reporting errors which appear like OpenAPI 3.1 schemas are being arbitrarily applied to files they edit: https://github.com/42Crunch/vscode-openapi/issues/130

In particular complains are for the error messages which look like this:

{
	"resource": "xxx/openapi.yaml",
	"owner": "_generated_diagnostic_collection_name_#0",
	"severity": 8,
	"message": "String does not match the pattern of \"^3\\.1\\.\\d+(-.+)?$\".",
	"source": "yaml-schema: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json",
	"startLineNumber": 1,
	"startColumn": 10,
	"endLineNumber": 1,
	"endColumn": 15
}

Would it be possible (if I'm correct in my conclusion) to exclude unsupported schema dialects?

[benjaminfiliatrault]

Same, Postman only support version 3 for now so all our open api files have errors and the autocompletion is not working anymore.

From https://www.schemastore.org/api/json/catalog.json (URL of schema store catalog to use) at around the line 1684 where the openapi.json is defined it have the versions object which could be used to switch between version 3..0.x and version 3.1.x.

    {
      "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"
      }
    },

Work around

1. Go in your vscode JSON settings
2. add this (Change the yml to the extension you're using)

"yaml.schemas": {
    "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json": "openapi.yml",
  },

it should accept now the version 3.0 but won't work for version 3.1

[evidolob]

@JPinkney @gorkem I make some prototype of this, I want to allow users to choose schema, but I have two problems:

1. The UI which allows to choosing schemas(as LSP very limits UI interaction). I have two options:
   • First add more code lens on the first line: With Use: {version}, Click on it will change used schema. In this case we don't need to have any non standard LSP communication API
   • Second, add status bar item, which will contain info about used schema and on click shows schema selection dialog, similar to IntelliJ IDEA: But to implement this I need to add more non standard LSP communication API.
2. When Used Schema is changed, I need to store that in preferences, but LSP doesn’t provide any API for preference update(they are read only from server), so we need again standard LSP communication API for updating preferences.

WDYT?

[ak1394]

Just wanted to mention, that our extension uses redhat.vscode-yaml's registerContributor() to provide relevant schema based on the file contents.

Given that looking up schemastore catalog is pretty crude way of finding the schema (it only matches the file name, ignoring the file contents) perhaps schemastore should be ignored for the files where schema is known from registerContributor()?

[gorkem]

That is not a bad idea. I think it makes sense that extension registered schemas takes precedence over anything else.

[abelbraaksma]

As an alternative, I noticed adding this line on top of your OpenAPI 3.0 YAML file will fix it in VS Code and in VS 2022 (which probably also uses this same lib). More info here: https://github.com/redhat-developer/yaml-language-server#using-inlined-schema

# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json

openapi: 3.0.0

info: 
   ... etc

[shayded-exe]

When using the 3.0 schema, I get an error that definitions/Schema/properties/multipleOf/exclusiveMinimum must be a number.

It seems as if the extension is using a newer version of the JSON Schema spec to validate the OpenAPI schema than draft-04 like it declares.

[caleb-artifact]

It appears that the yaml-language-server hack no longer works, and neither does adding

"yaml.schemas": {
    "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json": "openapi.yml"
}

to settings.json

Can we get an update on this issue? AFAIK support for OpenAPI 3.1 is pretty low across tooling RN.

[shayded-exe]

Over half a year and still not fixed.

This issue makes the extension completely unusable for even OpenAPI 3.0!

[unional]

Note that when I try to drill down to a specific definition: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json#/$defs/response

It emits a wrong error saying Missing property "paths".

That schema does not have a property paths.

[bozzaj]

Running into the same issue here. This is technically not an issue with the VSCode YAML extension, but the underlying yaml-language-server. There are a couple of Issues in that repo, but I think the most important one would be this one: YAML Language Server checks against JSON Schema Draft 7 instead of the defined one

The hacks/configurations of specifying the schema to use for OpenAPI no longer work due to the fact that the language server itself uses a newer JSON specification than what the OpenAPI 3.0 schema defines. Essentially, the core issue is that the language server ignores the $schema line in schema files it references. This wouldn't just be an issue with OpenAPI, but any schema that hasn't been updated to use JSON Schema Draft 7. OpenAPI just happens to be the most recognized specification.

The above ticket has a comment around a fork of the language server that uses JSON Schema Draft 04, which would fix this issue, but this would likely just break other schemas that DO require Draft 07. Looking at the comments, it seems to already be an issue for people wanting to use Draft 2020-12.

I'd recommend anyone having this issue to voice them in the above Issue 780 in yaml-language-server.

[paul-barton]

I was able to work around this by migrating the OpenAPI v3.0 Schema from draft4 to draft7 locally using alterschema and adding this to .vscode/draft7-schema.json and setting this in the yaml.schemas in my .vscode/settings.json

Steps I used:

1. Download https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.0/schema.json
2. Run alterschema to migrate it to draft7

npx alterschema --from draft4 --to draft7 ./schema.json > ./draft7-schema.json

3. Add the new schema to .vscode for local access

Ideally, this should be committed to a repo for github raw access like other schemas

4. Update yaml.schemas in .vscode/settings.json

{
  "yaml.schemas": {
    ".vscode/draft7-schema.json": [
      "*openapi.yml",
      "*openapi.yaml",
      "openapi.yml",
      "openapi.yaml",
    ]
  }
}

Note: this seems to work, but I didnt really test the if the schema is 100% perfect as I just wanted this error to go away.

draft7-schema.json