Release v3.1.1 #4082
Draft
Release v3.1.1 #4082
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: Mike Kistler <[email protected]>
…3.1.1 small typo fix
3.1.1 discriminator improvements
Move Mutual TLS example from 3.1.0 to 3.1.1 to prepare for patch release
Update 3.1.1 Spec for Style Values
Spec links to https://path.id - v3.1.1
Includes an example. This intentionally does not explain how dynamic referencing works, as there are better resources available in both the spec and (more readably) the official JSON Schema blog.
Co-authored-by: Ralf Handl <[email protected]>
Most 2020-12 validators do not validate it, which is a regular point of confusion worth highlighting.
This reorganizes binary data-related guidance into a "Working With Binary Data" section, as has already been done in 3.0.4. This includes more detailed guidance on when various approaches to binary data make sense (e.g. you cannot stuff raw binary into JSON no matter what you put in your Schema Object, and while you can base64-encode entire message bodies, it takes up a lot more space for no clear benefit). Also note that only `multipart` media types with named parts are supported, as they are modeled as an object.
As discovered through the OASComply project, certain referencing scenarios are ambiguous, with different authorities holding contradictory interpretations regarding whether and how they are to be supported. As a result, it is impossible to define compliance, as all of the interpretations can be argued to be "correct" in some sense. This change excludes some particularly challenging scenarios from compliance testing by making their behavior explicitly implementation-defined. This has several benefits: * No current implementation is rendered non-compliant * No currently usable OAD is rendered invalid * New implementers need not put effort into handling these scenarios * User expectations are set to _not_ expect consistent behavior * Linters can write a rule to match these expectations * Everyone is guided towards straightforwad best practices
The Structural Interoperability section should be a subsection of the OpenAPI Description Structure section.
Co-authored-by: Mike Kistler <[email protected]>
These should have the parameter name in the resulting string (see issue #3737).
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Limit interoperable parsing expectations (avoid type conflicts)
While the Markdown links don't behave quite like either category, they definitely belong more in the "API Description URIs" part as the text even compares their behavior to "the context of the API description" rather than the actual API's server URL.
Markdown links are API Description, not API URLs
3.1.1: update from main
Was tested on Windows, comment unnecessary
3.1.1: align format-markdown.sh with v3.0.4-dev
Also give Appendix C a better name because it is relevant whether you are using an actual RFC6570 implementation or not.
There are even more ways this can go wrong!
* Explicitly set `explode: false` in an example as the default with `style: form` is `explode: true`; the `explode: true` example was also left explicit to reduce confusion. * Tidy up overly conversational (e.g. "our document") language that I'd meant to revisit but forgot about. * Include the Header Object as one of the places where the `style` keyword is used (even if it is the simplest case) * Minor grammar fix. * Fix a missing space before an RFC reference.
Style guide conformance.
Port of last-minute 3.0.4 changes to 3.1.1
The extended example with a multi-document OAD and a Security Requirement in the referenced document did to fit well where it was, and there wasn't room in the Resolving Implicit Connections area. So this moves it to an Appendix linked from both locations.
3.1.1 port of Move complex Sec Req example to appendix F
darrelmiller
previously approved these changes
Sep 19, 2024
This tidies up the increasingly long Schema Object section and adds explanations of what I've been calling "extended validation", including validating `readOnly` and `writeOnly`, and also using a `oneOf` or `anyOf` with `const` plus annotations for enumerated types with additional information. There are many OAS issues/discussions where we have recommended these techniques, so it makes sense to include them in 3.1.1 where draft 2020-12's formal collection of annotations enables tools to build support for them.
Co-authored-by: Ralf Handl <[email protected]>
3.1.1: use specific custom languages uri and uritemplate
Annotated enums and extended validation
|
Thanks to everyone for the work on this! Is there any ETA on when this will get merged? |
|
@ross-paypay Thanks! We decided to add #4100 to 3.0.4 and its port to 3.1.1, and it may take us a few weeks to polish that change. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR will merge
v3.1.1-devintomain.Still to do: