Add schemas for 3.1 #2489
Add schemas for 3.1 #2489
Conversation
jdesrosiers
force-pushed
the
oas31-schema-2
branch
from
6d4a64f to
e9e4b4c
Compare
jdesrosiers
force-pushed
the
oas31-schema-2
branch
from
703acb5 to
8c57bcc
Compare
|
Looking good - could we move non-test scripts into Just a note that the |
I think it would be best to bring those in rather than use a submodule. I used a submodule for now because I figured it was the easiest way to pull in your updates until this PR gets merged. |
The main schema no longer validates schemas other than verifying that they are either a schema or an object.
jdesrosiers
force-pushed
the
oas31-schema-2
branch
from
8c57bcc to
bd7a645
Compare
|
I realized that I closed #2467 because those schemas are included here as well, but there were some important questions included there that need to be answered, so I'm copying them over to this issue. Here's a candidate for the OAS 3.1 Base Schema vocabulary and dialect meta-schemas. I wasn't quite sure what to names things. The directory and file names are intended to match the The "base" vocabulary is set to false in the dialect schema. This allows validators to validate instances against this meta-schema even if it doesn't know about the OpenAPI extensions. This is no concern for most of the extensions because they are just annotations and don't affect validation. The exception is In JSON Schema, I didn't explicitly add the additional format values that OpenAPI 3.1 adds because JSON Schema Draft 2020-10 already allows any value, so there was nothing to do. If you want to run this through its paces, head over to https://json-schema.hyperjump.io. Add two additional schema tabs using the |
|
@jdesrosiers Quick question about something that was mentioned in the TSC today:
Is there a way to do this with this pr? |
|
@kadeatfox I think what was meant there was that we are now expressing some of the dependencies between parameters in the schema. The hope is that more people will answer their own question by validating against the schema and seeing if it passes or fails. |
|
@jdesrosiers could you give me an example of how those dependencies could be expressed? I must've missed it in the meeting. |
|
@kadeatfox Remember all those That's what I thought he was talking about, but I could be mistaken. |
|
Thanks @jdesrosiers that's what I was following as well. For a moment though, I took it to mean define dependencies between parameters for the API an OAS Document means to describe. Sounds like he was referring to the ability to define the OAS itself. |
jdesrosiers
force-pushed
the
oas31-schema-2
branch
from
cdf72ca to
84ea4a0
Compare
|
@jdesrosiers perhaps if you're interested in more testing, you could use: https://github.com/APIs-guru/openapi-directory/tree/master/APIs as a good bank of examples for valid api specs. At least the most recent documents that conform to OAS 3.0+ @MikeRalphson would that be a good repository of "test fixtures" for this PR? |
|
They would need to be upgraded to v3.1 first, and my converter is still a work-in-progress. |
|
Status Update Since we're not getting much feedback on this, it was decided to release what we have and release fixes when issues come up. Before this is merged, here are some things everyone should be aware of including some decisions I've made because no one else has expressed an opinion.
Well, that was much longer than I expected, so I hope it actually gets read. |
|
Hi, I have tried to validate a 3.1 spec against 3.1 schema using Ajv-cli using This resulted in 79 errors because Ajv thinks the 3.1 spec schema is not a valid draft-2020 spec. The errors are listed below. Kind regards, |
|
@seriousme The schema is valid. Ajv appears to be applying some non-standard linting rules. It seems that it requires For example, here's the "specification-extensions" definition. {
"patternProperties": {
"^x-": true
}
}It's not intended to be used by itself, it's a mix-in to be combined with other schemas. If we included {
"type": "object",
"patternProperties": {
"^/": { "$ref": "#/$defs/path-item" }
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
}Ajv does these extra linting rules as part of "strict mode". Clearly the strict mode linting rules still need some tweaking. I suggest turning strict mode off for now. |
|
Thx for the quick response ! turning off strictTypes by using: solves most of the issues except for one: error: strict mode: property schemas matches pattern ^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$ (use allowMatchingProperties)Maybe I'm wrong but what I think you are trying to specify here is:
If that is the case then this regexp works for me:
Once I replace the regexp Ajv starts parsing petstore.json from the 3.0 examples, so the openapi version triggers an error on 3.0 as expected. Kind regards, |
|
The schema is correct. Again, this looks like another strict mode linting rule. It appears that this rule ensures that properties only match the The Components Object is the toughest part of the schema to understand because it has some complex constraints. The Components Object is an object with several defined properties whose values are objects whose keys match {
"type": "object",
"properties": {
"schemas": {
"type": "object",
"additionalProperties": { "$dynamicRef": "#meta" },
"propertyNames": { "pattern": "^[a-zA-Z0-9._-]+$" }
},
"responses": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/response-or-reference" },
"propertyNames": { "pattern": "^[a-zA-Z0-9._-]+$" }
},
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
}Notice how "patternProperties": {
"^(schemas|responses)$": {
"propertyNames": { "pattern": "^[a-zA-Z0-9._-]+$" }
}We can't have the {
"type": "object",
"properties": {
"schemas": {
"type": "object",
"additionalProperties": { "$dynamicRef": "#meta" },
"$ref": "#/$defs/component-names"
},
"responses": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/response-or-reference" },
"$ref": "#/$defs/component-names"
},
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
}This would have been more verbose, but effectively the same amount of duplication and easier to understand. In retrospect, maybe that would have been better, but either way, the schema is valid and works as intended despite ajv's overzealous linting rules. |
|
Many thanks again for taking the time to write the elaborate explanation ! Kind regards, |
Progress on #2474 has stalled out while @philsturgeon is busy saving the world, so this is an alternative so we can keep things moving.
The
schema.yamlschema doesn't validate the JSON Schemas in your OpenAPI document because 3.1 allows you to use any JSON Schema dialect you choose. I also includedschema-base.yamlthat extends the main schema to validate that all schemas use the default OAS base vocabulary.The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples.
You can also validate a document individually.