dev: update from main #4971
Closed
dev: update from main #4971
+5,961
−1,643
Conversation
This file contains hidden or 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
![oai-spec-publisher[bot]](https://avatars.githubusercontent.com/u/16343502?s=80&v=4){kind=small}
Provide examples of narrowing multiple types, and make it clear that every schema without a `type` keyword allows all types. Also note that implementations MAY go beyond these requirements, but set boundaries on what they can do.
Percent-Encdoing is mind-boggling, make a TL;DR section. Also clarify that `format` has to be enabled to impact validation.
This adds two fields to the Example Object and partially deprecates the existing `value` field. `dataValue` applies to the data that would be passed to schema validation. `serializedValue` (which MUST be a string), like `externalValue`, applies to the serialized form. Guidance is provided that `value` (and the shorthand singluar `example`) are safe for JSON serialization targets and for strings serialized to targets that do not apply further escaping, but are otherwise deprecated due to ambiguous behavior.
The rules for this have not been clear, and are not always intuitive. This states and explains them directly and ensures that the Style Examples table matches the rules. Unlike past efforts, this provides a rule system regarding what is and is not included, based on a combination of what is produced by RFC6570 (or the nearest RFC6570 equivalent), modified by removing leading delimiters that are not correct for our usage due to differences from the assuptions made by RFC6570. This also shows some uses of the new Example Object fields, including some that would be redundant but are included to clarify the different options; the redundancy is noted in the text.
This updates for both the new example fields and for examples with `content`
Parameter and Header serialization is complex, particularly when using the `content` field to use a Media Type Object. In such scenarios, the serialization occurs in two steps: The first step is to serialize the data to the media type, which can be captured by the `examples` field of the Media Type Object. The second is the encoding/escaping of the media type document for use in a URI, HTTP header, or other location with its own rules. Sometimes the part needing illustration with an example is at one level, sometimes at another, and sometimes it is helpful to show both. For simplicity, the "data" examples are always treated as the overall input data, so they would be the same at both levels. This is also because it is not always possible to show each step, particularly when there are binary serializations. This allows showing either step (or both steps) with both data and serialization, depending on what makes sense for the use case.
The Set-Cookie response header breaks the normal rules for headers with multiple values and requires special handling.
Co-authored-by: Phil Sturgeon <[email protected]>
Also remove a stray line from an example that didn't really hurt but wasn't needed and could have been confusing.
Co-authored-by: Lorna Jane Mitchell <[email protected]>
Explain when Set-Cookie workaround is needed Also remove a stray line from an example that didn't really hurt but wasn't needed and could have been confusing.
Co-authored-by: Ralf Handl <[email protected]>
v3.2: Move URI/URL resolution sections, *UNCHANGED*, under OAD Structure
v3.2: Editorial improvements to Appendix E (Percent-Encoding)
v3.2: Clarify JSON-compatible YAML
Let's only explain the validation requirements in one place. Also, header example fields were supposed to be moved rather than duplicatd but I missed the removal of the old ones.
Co-authored-by: Ralf Handl <[email protected]>
Add the Media Type Object to the Components Object, and allow a Reference Object anywhere it is allowed. To ensure that re-usable Objects can be documented clearly, add a `description` field.
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
…, explode, allowReserved are present see #4899
v3.1-dev: update from dev
v3.2-dev: update from dev
UTF-8 is not a character set; it is an encoding. The character set we are using is Unicode (the full range of integers from \x00 to \x10FFFF), so revert to using the correct terminology. ref.: https://www.rfc-editor.org/rfc/rfc6570#section-2.1 uses "any Unicode character except..."
updates for the "xml" and "example" keywords
fix character terminology in ABNF comments
v3.2 schema edits
v3.1 schema edits
Official 3.1.2 release branch
Official 3.2.0 release branch
|
Merging this would apparently delete our schemas and test cases. Something is wrong here. |
|
Because we made a commit that deleted all those files (on the rel branch) and then merged it to main. So that commit does the same thing when applied here. |
|
Those files were never on main, and the 3.1.2 PR correctly showed that: https://github.com/OAI/OpenAPI-Specification/pull/4969/files. The 3.2.0 PR originally looked the same - just two files added and two changed. Now it contains deletions of files that never existed on main https://github.com/OAI/OpenAPI-Specification/pull/4970/files. 🤷♂️ We can do a release dry run for 3.3.0 or 3.2.1 later without actually merging the PRs to see how they look. |
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.
Merge
mainintodev.