Skip to content

Add meta-schema for 3.1 base vocab and dialect #2467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from

Conversation

jdesrosiers
Copy link
Contributor

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 $ids. Both the dialect and the vocabulary are called "base", which is awkward, but it seemed the most accurate based on the language in the spec. Let me know if you prefer different names or flatter structure.

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 discriminator. In that case, the discriminator keyword will be quietly skipped by a validator. If you prefer users get an error in this case, let me know and I'll switch that to true.

In JSON Schema, format is an annotation-only by default. I wasn't sure if OpenAPI 3.1 expects format to be annotation-only or for it to validate against the format. Currently, it's set to annotation-only. Let me know if you rather it validate.

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 [+] button next to the "Schema" tab. Add one of the schemas in this PR to each tab. In the original tab, change the value of the $schema keyword to https://spec.openapis.org/oas/3.1/dialect/base. That schema will then meta-validate using these meta-schemas. For example, you can add a discriminator and see that you get an error if the propertyName field is missing. You can also modify the meta-schemas if you want to try to modify anything. You can leave the "Instance" tab(s) empty, validating an instance works, but it's not relevant to the meta-schemas.

@MikeRalphson MikeRalphson linked an issue Feb 18, 2021 that may be closed by this pull request
@MikeRalphson MikeRalphson self-requested a review February 18, 2021 04:05
@jdesrosiers
Copy link
Contributor Author

As I read more about discriminator it appears that it's only used as a hint and ignoring it wouldn't change the final result of validation. If that's correct, there's should be no problem with leaving the base vocabulary set to false.

@jdesrosiers
Copy link
Contributor Author

I'm closing this because it's included in #2489. Please direct any feedback to that issue instead.

@jdesrosiers jdesrosiers closed this Mar 8, 2021
@jdesrosiers jdesrosiers deleted the 31-schema-vocab branch March 8, 2021 19:44
@jdesrosiers jdesrosiers mentioned this pull request Mar 10, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create a complete meta schema for 3.1
3 participants