OpenAPI-Specification

OpenAPI-Specification copied to clipboard

Hello, there is a lot of JavaScript tooling that uses AJV to validate OpenAPI specs. None of it seems to support 3.1, which is really unfortunate. I was trying to remedy the situation, but failed miserably.

As far as I can tell (see https://github.com/ajv-validator/ajv/issues/1745) even the examples in your OpenAPI3.1 folder do not pass validation. The AJV folks (understandably) won't help unless I create a minimal reproducible example of a failing schema, which I'm not really qualified to do.

Would you be able to help/shed light on what's going on?

Copying the relevant details:

Ajv options object

{
    allErrors: true, 
    validateFormats: false, 
    strictSchema: false, 
    strictTypes: false
}

See OAI/OpenAPI-Specification#2489 for a discussion on the options.

JSON Schema

The OpenAPI 3.1 schema defined here: https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.json

Sample data

the OpenApi v3.1 webhook example here: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.json

Your code

See: https://runkit.com/essential-randomness/612d87df07ae0a00092a3492.

This simply call ajv with the given options, passes the OpenApiv3.1 schema and tries to validate the OpenApi Webhook example.

Validation result, data AFTER validation, error messages

Error message:

Invalid: 
data/webhooks/newPet/post/requestBody/content/application~1json/schema must NOT have unevaluated properties, 
data/webhooks/newPet/post/requestBody must match "else" schema,
data/webhooks/newPet must match "else" schema, 
data/components/schemas/Pet must NOT have unevaluated properties, 
data/components/schemas/Pet must NOT have unevaluated properties

---

Thank you! Hopefully the errors are more understandable if you can read schemas :)

This is a bug in ajv related to $dynamicRef. Here's your minimal reproduction.

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",

  "type": "object",
  "properties": {
    "schema": { "$dynamicRef": "#meta" }
  },
  "unevaluatedProperties": false,

  "$defs": {
    "schema": {
      "$dynamicAnchor": "meta",
      "type": ["object", "boolean"]
    }
  }
}

instance

{
  "schema": { "type": "string" }
}

It appears that the $dynamicRef is resolving to the root of the schema rather than /$defs/schema where the $dynamicAnchor is located.

Thank you so much for you help! Will follow up with them and hopefully we can get 3.1 working :)

@essential-randomness can you cross-link the ajv ticket here so others can follow its progress?

Absolutely! Here it is

https://github.com/ajv-validator/ajv/issues/1745

See also https://github.com/ajv-validator/ajv/issues/1573 by @seriousme. @epoberezkin originally closed https://github.com/ajv-validator/ajv/issues/1745 as a duplicate of that one, but 8 days later reopened it

@essential-randomness : see also: https://github.com/seriousme/openapi-schema-validator ;-)

@essential-randomness : see also: https://github.com/seriousme/openapi-schema-validator ;-)

Oh I use this! (Thanks for making it)

Fairly sure it doesn't catch everything though. I've had to use 2-3 different validators to get most of the errors out and even then stuff still slips through. I've also not been able to make 3.1 schemas pass for other JS libraries, and when I looked at why yours worked there was a reason for why yours would and theirs wouldn't that I have now forgotten.

I see that @seriousme/openapi-schema-validator modifies the official meta-schemas to work around the ajv bug.

@hyperjump/oas-schema-validator works properly without workarounds and can validate the schemas against the OpenAPI JSON Schema vocabulary or whatever JSON Schema dialect you choose. Here's a quick example.

const OasSchema = require("@hyperjump/oas-schema-validator");
const example = require("./example.openapi.json");

(async function () {
  const schema = await OasSchema.get("https://spec.openapis.org/oas/3.1/schema-base");
  const validate = await OasSchema.validate(schema);

  const result = validate(example, OasSchema.BASIC);
  console.log(result);
}()); 

Yes, working on a fix here too… It’s a tricky one, at the time it was implemented the spec didn’t settle yet, but should be ok soon.

any updates?

@MatanYemini check https://github.com/cdimascio/express-openapi-validator/pull/713

Just tested, openapi-schema-validator validation failed at the raw spec containing the "$dynamicRef": "#meta" hence it still uses a modified 3.1 schema where "$dynamicRef": "#meta" has been converted to "$ref": "#/$defs/schema"

With the modified 3.1 schema validation tests succeed as before.

@seriousme @MatanYemini try with https://github.com/cdimascio/express-openapi-validator/pull/713#issuecomment-1140492669, or newer?

@no-identd Upgrading AJV won't fix this problem until AJV fixes the bug responsible for the problem.

Since the only problems here are with JSON Schema validators, and not the OAS itself, I'm going to close this- there are plenty of issues tracking the validator bugs/missing features.