Skip to content

Commit

Permalink
3.1.0 Release (#2462)
Browse files Browse the repository at this point in the history
* 3.1.0 prep

* Update README

* Allow specification extensions in discriminator object

* Note that specification extensions beginning x-oas- are reserved

* security; add mutualTLS securityScheme type

* 832 add info.summary (#1779)

* Fix: #832. Add info.summary.

* Fix: summary is shord, description is verbose.

Be consistent with other definitions of summary and description.

* fix OIDC url and OAuth2 requirements

Signed-off-by: Axel Nennker <[email protected]>

* Update Schema Object to proper JSON Schema

* update vocab and arbitrary props

* another go at arbitrary keywords

* feedback from @handrews

* Support style, explode, allowReserved encoding for multipart/form-data (#2066)

* Extend style, explode, allowReserved in encoding to multipart-formdata (#2018)

* Update versions/3.1.0.md

Co-Authored-By: Ron <[email protected]>

* Replace details of multipart/form-data format with referce to RFC 7578

* Update versions/3.1.0.md

Co-Authored-By: Darrel <[email protected]>

* default should match json schema

* removed json schema keyworld list, its just all of em.

* redundant $ref reference

* Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects.

* Add support for webhooks as a top-level element (#2103)

* Add webhooks as a top-level element to the spec

* Add the changes from #2048 and signpost webhooks

* Add an example of webhooks

* Relocate and expand on webhooks section following feedback

* Better wording to describe expectations on API consumers

* Clearer wording for why the paths element is here

* Update language to make callbacks clearer

* Align the OAS 3.1 nullable language with the 3.0.3 (#2115)

This adapts the language from PR #2046, with minimal wording tweaks
to account for type now being able to have multiple values (type arrays).

* allow, but discourage, requestBody for GET, HEAD, DELETE (#2117)

* Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107)

* Checkpoint of draft

* Fix typo.

Co-Authored-By: Darrel <[email protected]>

* Fix plural anchor

Co-Authored-By: Mike Ralphson <[email protected]>

* Remove superfluous specification

Co-Authored-By: Phil Sturgeon <[email protected]>

Co-authored-by: Darrel <[email protected]>
Co-authored-by: Mike Ralphson <[email protected]>
Co-authored-by: Phil Sturgeon <[email protected]>

* Fix table cell formatting containing `nullable` description (#2152)

* Add SPDX identifier field to license object, fixes #1599 (#2105)

* Add information about objects to the description too

* Make paths object optional (#1781)

* Make paths object optional

* Adding reusable Path Item Objects

Under `components`

* Adopt DM's suggested change to OpenAPI doc definition

* Cleanup use of specification and definition where we mean document

* multipartite>composite, define ACL

* Add ' | Reference Object' to callbacks/webhooks

Co-authored-by: Ron <[email protected]>

* Fwd port v3.0.3 dev to v3.1.0 dev (#2163)

* fix typo in Callback Object

Signed-off-by: Mike Ralphson <[email protected]>

* retain typo in v3.0.2; fix for v3.0.3 (#1899)

Signed-off-by: Mike Ralphson <[email protected]>

* Clarify empty Security Requirement Object usage and validity (#1886)

* Clarify empty Security Requirement Object usage and validity

* Reorder sentences to make clearer.

* Remove wrong text.

* Removed unneeded text.

Co-authored-by: Ron <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* Ron's wording for Darrels feedback

Signed-off-by: Mike Ralphson <[email protected]>

* ted updates

Signed-off-by: Mike Ralphson <[email protected]>

* Replace 'application' by 'API' within the 'Info Object' definition. (#2004)

Signed-off-by: Mike Ralphson <[email protected]>

* Path Templating Clarification - proposed fix for #1830. (#1831)

* Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter.

* #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter.

* Update #1830 fix with suggestion from Darrel

@darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea.

Signed-off-by: Mike Ralphson <[email protected]>

* yaml.org supports https, but www.yaml.org is misconfigured

Signed-off-by: Mike Ralphson <[email protected]>

* Updated text for OperationRef

Signed-off-by: Mike Ralphson <[email protected]>

* fix a typo in the Security Filtering section (#1837)

* fix a typo in the Security Filtering section

* Security filtering slight reword

Co-authored-by: Mike Ralphson <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* Make ABNF for runtime expressions complete

Signed-off-by: Mike Ralphson <[email protected]>

* Explain unclear semantics of property `$ref` in Path Item Object (#1964)

* Explain unclear semantics of property `$ref` in Path Item Object

Currently, as explained in #1038 (comment) the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear.

* Update versions/3.1.0.md

Co-authored-by: Ron <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* Clarify constraints on Security Scheme Object Scheme Property (#1880)

* Wording around scheme extensions

* Clarified that securitySchemeScheme is only a SHOULD be registered scheme

Signed-off-by: Mike Ralphson <[email protected]>

* fix difference between yaml and json in Response Object Examples

Signed-off-by: Mike Ralphson <[email protected]>

* Server Variable Object clarifications (#1809)

* Server Variable Object clarifications

* Toned language down for proper semver versioning

Signed-off-by: Mike Ralphson <[email protected]>

* Fix formatting errors in example (#2132)

Signed-off-by: Mike Ralphson <[email protected]>

* Update 3.0.3 for release (#2149)

* Update README.md for release

* Update release date for 3.0.3

Signed-off-by: Mike Ralphson <[email protected]>

* Update versions/3.1.0.md

Co-Authored-By: Darrel <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* Fixed typo

Signed-off-by: Mike Ralphson <[email protected]>

* explicit 'forward slash'

Signed-off-by: Mike Ralphson <[email protected]>

* fix #2053: `style` keyword is not supported inside Schema object

Signed-off-by: Mike Ralphson <[email protected]>

* OpenAPI not Open API

Signed-off-by: Mike Ralphson <[email protected]>

* backticks

Signed-off-by: Mike Ralphson <[email protected]>

* minor clarification for operationId usage in link objects (#1733)

* minor clarification

it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit.

* use right terminology

Co-Authored-By: Mike Ralphson <[email protected]>

Co-authored-by: Ron <[email protected]>
Co-authored-by: Mike Ralphson <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* Update 3.1.0.md

fixed typo

Signed-off-by: Mike Ralphson <[email protected]>

* Removed confusing comment

Signed-off-by: Mike Ralphson <[email protected]>

* Clarify the spec to allow optional or unspecified OAuth scopes (#1888)

* Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all.

* Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed.

* For #513, adjusting language and removing examples

For #513, adjusting language and removing examples as suggested by @webron.

* removed unnecessary example header

Co-authored-by: Ron <[email protected]>
Signed-off-by: Mike Ralphson <[email protected]>

* The examples keyword is not supported inside schema (#2042)

* examples not supported inside schema

* figured it out

* a tiny little edit

Signed-off-by: Mike Ralphson <[email protected]>

* Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006)

Signed-off-by: Mike Ralphson <[email protected]>

* Fix formatting errors in example (#2132)

Signed-off-by: Mike Ralphson <[email protected]>

Co-authored-by: seiya <[email protected]>
Co-authored-by: Adam Leventhal <[email protected]>
Co-authored-by: Sebastián Ramírez <[email protected]>
Co-authored-by: Ron <[email protected]>
Co-authored-by: Phil Sturgeon <[email protected]>
Co-authored-by: Patrice Krakow <[email protected]>
Co-authored-by: Ted Epstein <[email protected]>
Co-authored-by: Darrel Miller <[email protected]>
Co-authored-by: Carsten Brandt <[email protected]>
Co-authored-by: Henry Andrews <[email protected]>
Co-authored-by: Sergej <[email protected]>
Co-authored-by: nasa9084 <[email protected]>
Co-authored-by: Erik Wilde <[email protected]>

* security; widen use of scopes array to other securityScheme types (#1829)

Co-authored-by: Ron <[email protected]>

* Allow summary and description as $ref siblings (#2181)

* HTTP not REST (#1946)

Co-authored-by: Phil Sturgeon <[email protected]>

* Missing updates

While going over the changes for the release notes, found two issues:
- The TOC entry for `Relative references in URIs` was not modified to match the change in the spec.
- The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays).

* Remove boolean compatibility for exclusive* (#2226)

This brings exclusiveMinimum, exclusiveMaximum, minimum, and
maximum, into full modern JSON Schema compatibility.

There are no edits directly mentioning minimum and maximum,
but removing the boolean form simplifies their processing
by making it context-independent.

* Update "format" and "content*" for new JSON Schema (#2200)

* Update "format" and "content*" for new JSON Schema

This removes OAS formats and examples that are now superfluous
as they are part of the 2019-09 JSON Schema draft.

Similarly it deprecates the "byte" and "binary" formats in favor
of JSON Schema's "contentEncoding" and "contentMediaType" keywords,
and updates various related exapmles and other guidance.

It also removes confusingly blank rows in the OAS format table.

* "format" is an annotation

* Fix broken table, type, in Encoding Object

Broke some things while updating for "content*"

* Fix format of `format`

Backticks, not double quotes.

* Remove unneeded detail on "format"

This was just duplicating info from the JSON Schema spec.

Co-authored-by: Darrel <[email protected]>

* Remove "byte" and "binary" formats altogether.

Instead of just deprecating.  The "content*" keywords now
cover these use cases.

* Harmonize JSON Schema content* + Media Type Object

Includes harmonizing with the Encoding Object.  In general,
OpenAPI objects set the media type, although there is a case
for `contentMediaType` with multipart/form-data.  Otherwise,
`contentEncoding` replaces the now-removed custom formats.

A possibly controversial change is to indicate unencoded binary
data by omitting `type` (or omitting the schema altogether), as
binary data does not conform to JSON string requirements.

This could still be done with `type: string` if that is preferred.
It's going to be a bit weird either way.

I can add wording in the next JSON Schema draft to clarify
whichever approach makes more sense.

* Fix typos from review

* Remove stray {}

* Fix inconsistencies contentMediaType and Encoding Object

Co-authored-by: Darrel <[email protected]>

* [3.1.0-dev] drop OAS semver requirement (#2243)

* drop OAS semver requirement

* Update versions/3.1.0.md

Co-authored-by: Darrel <[email protected]>

* Remove "nullable" entirely (#2246)

* x-oas- to x-oai- (v3.1.0-dev)

* Update version for release (#2269)

* $schema Guidance (#2266)

* chore: explain how $schema might work

* reordered and made it specifically only schema resources

* Update versions/3.1.0.md

Co-authored-by: Karen Etheridge <[email protected]>

* Update versions/3.1.0.md

Co-authored-by: Ben Hutton <[email protected]>

* new approach

Co-authored-by: Phil Sturgeon <[email protected]>
Co-authored-by: Karen Etheridge <[email protected]>
Co-authored-by: Ben Hutton <[email protected]>

* x-oai- / x-oas-; reserve both

* v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (#2302)

* The JSON schema specification states the format keyword can be used for any data type, not just primitive types

* The JSON schema specification states the format keyword can be used for any data type, not just primitive types

* Added change to address #2287 (#2328)

Co-authored-by: Darrel Miller <[email protected]>

* Make Server Variable Object's properties more strict (#2335)

Followup to #1809, now that we allow breaking changes.

* docs(Components): fix typo in schemas field type (#2337)

* Fix indentation of a YAML comment

* Removed required constraint on responses object (#2329)

Co-authored-by: Darrel Miller <[email protected]>

* 3.1.0-rc1 Release prep (#2369)

* Update 3.1.0.md

* Merge branch 'master' into v3.1.0-dev

* Added words relating to adopting semantics of JSON Schema (#2330)

* Added words relating to adopting semantics of JSON Schema

* Update versions/3.1.0.md

Co-authored-by: Mike Ralphson <[email protected]>

* Update versions/3.1.0.md

Co-authored-by: Mike Ralphson <[email protected]>

Co-authored-by: Darrel Miller <[email protected]>
Co-authored-by: Mike Ralphson <[email protected]>

* fix typo in release history table

* fix link to style values in serialization table

* Fix misspelling of a keyword in text (#2389)

* Update wording that referred to the year 2019 as the current year (#2390)

* Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (#2394)

* Added link to JSON Schema Validation docs explain which formats are included in JSON Schema

* Update verbiage to be more accurate

Co-authored-by: Mike Ralphson <[email protected]>

Co-authored-by: Mike Ralphson <[email protected]>

* Update 3.1.0.md (#2405)

Improve wording about 'summary' and 'description' in Reference Object

* long descriptions are cool too (#2408)

Co-authored-by: Phil Sturgeon <[email protected]>

* Unescaped Slashes Aint Welcome Around 'Ere (#2218)

* oas 3.0 doesn't mention slashes not allowed

* none of those either

Co-authored-by: Phil Sturgeon <[email protected]>

* Add missing field and use same summaries in Request Body Examples. (#2362)

* Add missing schema type in Operation Object YAML Example. (#2361)

* OAS schema dialect clarifications (#2399)

* OAS schema dialect clarifications

* OAS schema dialect clarifications

Signed-off-by: Mike Ralphson <[email protected]>

* $schema is allowed in subschemas when bundling

Co-authored-by: Ben Hutton <[email protected]>

* Schema dialect clarifications from Ben

Signed-off-by: Mike Ralphson <[email protected]>

* Use top-level jsonSchemaDialect field

Co-authored-by: Ben Hutton <[email protected]>

* Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (#2437)

* fix http link to json-schema.org

Signed-off-by: Mike Ralphson <[email protected]>

* fix http link to spec.commonmark.org

Signed-off-by: Mike Ralphson <[email protected]>

* Specify rules for $ref resolution

Signed-off-by: Mike Ralphson <[email protected]>

* Specify relative resolution rules for pathItem $ref and example externalValue

Signed-off-by: Mike Ralphson <[email protected]>

* Update JSON Schema draft links to 2020-12 IETF pages

Signed-off-by: Mike Ralphson <[email protected]>

* Make language about 'MUST be in the form of a ...' consistent

Signed-off-by: Mike Ralphson <[email protected]>

* Make it clear pathItem $refs don't need to be external now

Signed-off-by: Mike Ralphson <[email protected]>

* Make RFC links consistent with regard to spacing

Signed-off-by: Mike Ralphson <[email protected]>

* Allow a URI for example.externalValue fields

This makes it fall under the rules for relative references.

Signed-off-by: Mike Ralphson <[email protected]>

* Explicitly call out $ref as a Relative Reference

* Remove wording about what implementations SHOULD/MAY do with a $ref

* Prefer 'referenced document' to 'referrant document' for clarity

* Fix JSON Schema $ref resolution fallback rule

* Add links back to #relativeReferences definition

* Split #relativeReferences definition into URL and URI sections

Signed-off-by: Mike Ralphson <[email protected]>

* Clean-up wording about $refs in responsesObjects, fixes #1679 (#2442)

* Clean-up wording about $refs in responsesObjects, fixes #1679

* Agreed to remove explicit verbiage around $refs in responseObjects, fixes #1679

* fix: two typos in versions/3.1.0.md (#2452)

* Fix, clarify, and simplify content type schemas (#2351)

* Fix, clarify, and simplify content type schemas

This fixes #2349, which caught that an encoded PNG image
is encoded into a text media type.

In the process I realized some other errors, and simplified things.

* HTTP `Content-Type` is always handled by OAS
    * Media Type Object key in most cases
    * Encoding object (possibly inferred from schema) in `multipart/form-data`
* HTTP-level `Content-Encoding` is always handled by the OAS Header Object
* JSON Schema "content*" is used for embedding one media type into another
    * the encoded resource is of media type `text/plain`
    * `"contentMediaType"` is the embedded media type after decoding
    * `"contentEncoding"` is how to encode/decode binary to/from text

This removes any chance of `"contentMediaType"` conflicting with
the Media Type Object key or with `contentType` in the Encoding Object,
as they now always do different things.

Likewise, the HTTP `Content-Encoding` header (with values like
gzip, deflate, etc.) does different things than `"contentEncoding"`
(which has values like base64, base64url, quoted-printable, etc.).

The deprecated part header `Content-Transfer-Encoding` is likewise
handled in the Encoding Object, but is probably never used.

* Fix Content-Type to indicate semantics

...rather than literal content format on the wire.

* Update 3.1.0.md

Fixed a typo and changed a SHOULD to MAY.

* Update versions/3.1.0.md

* clarify default encoding content type value.

* Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header

Co-authored-by: Mike Kistler <[email protected]>

Co-authored-by: Darrel <[email protected]>
Co-authored-by: Mike Kistler <[email protected]>

* 3.1.0 release prep (#2461)

* 3.1.0 release prep

* Update README.md

* reframing `user` as `author` (#2463)

Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled.

* fixed the dash character

Co-authored-by: Mike Ralphson <[email protected]>
Co-authored-by: Roberto Polli <[email protected]>
Co-authored-by: Axel Nennker <[email protected]>
Co-authored-by: Phil Sturgeon <[email protected]>
Co-authored-by: Mike Kistler <[email protected]>
Co-authored-by: Darrel <[email protected]>
Co-authored-by: Arhimenrius <[email protected]>
Co-authored-by: Lorna Jane Mitchell <[email protected]>
Co-authored-by: Henry Andrews <[email protected]>
Co-authored-by: Alan Crosswell <[email protected]>
Co-authored-by: Helen Kosova <[email protected]>
Co-authored-by: seiya <[email protected]>
Co-authored-by: Adam Leventhal <[email protected]>
Co-authored-by: Sebastián Ramírez <[email protected]>
Co-authored-by: Patrice Krakow <[email protected]>
Co-authored-by: Ted Epstein <[email protected]>
Co-authored-by: Carsten Brandt <[email protected]>
Co-authored-by: Sergej <[email protected]>
Co-authored-by: nasa9084 <[email protected]>
Co-authored-by: Erik Wilde <[email protected]>
Co-authored-by: Marsh Gardiner <[email protected]>
Co-authored-by: Phil Sturgeon <[email protected]>
Co-authored-by: Karen Etheridge <[email protected]>
Co-authored-by: Ben Hutton <[email protected]>
Co-authored-by: Sebastien Rosset <[email protected]>
Co-authored-by: Darrel Miller <[email protected]>
Co-authored-by: Vladimir Gorej <[email protected]>
Co-authored-by: Helen Kosova <[email protected]>
Co-authored-by: Deven Phillips <[email protected]>
Co-authored-by: Vladimir <[email protected]>
Co-authored-by: Quint Daenen <[email protected]>
  • Loading branch information
1 parent f1adc84 commit 42a9e3d
Show file tree
Hide file tree
Showing 2 changed files with 107 additions and 81 deletions.
18 changes: 7 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,32 +11,28 @@ The OpenAPI Specification (OAS) defines a standard, programming language-agnosti

Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an APIs services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application.

The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API.
The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API.

This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project.

## Current Version - 3.0.3
## Current Version - 3.1.0

The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md).

## Current Release Candidate Version - 3.1.0-RC1

We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC1](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev).
The current version of the OpenAPI specification is [OpenAPI Specification 3.1.0](versions/3.1.0.md).

### Previous Versions

This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications.
This repository also contains all [previous versions](versions).

Each folder in this repository, such as [examples](examples) and [schemas](schemas), should contain folders pertaining to the current and previous versions of the specification.

## See It in Action

If you just want to see it work, check out the [list of current examples](examples/v3.0).
If you just want to see it work, check out the [list of current examples](examples).

## Tools and Libraries

Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing
[list of 3.0 implementations](IMPLEMENTATIONS.md).
[list of implementations](IMPLEMENTATIONS.md).

## Participation

Expand All @@ -48,7 +44,7 @@ The TSC holds weekly web conferences to review open pull requests and discuss op

The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:

* Review the [current specification](versions/3.0.3.md). The human-readable markdown file _is the source of truth_ for the specification.
* Review the [current specification](versions/3.1.0.md). The human-readable markdown file _is the source of truth_ for the specification.
* Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving.
* Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR.
* Create an issue to describe a new concern. If possible, propose a solution.
Expand Down
Loading

0 comments on commit 42a9e3d

Please sign in to comment.