From 14e56678aa8d444580658d23f05498f106a79f42 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 22 Aug 2025 10:11:27 -0700 Subject: [PATCH 1/5] Merge Versions and Deprecation sections --- src/oas.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/oas.md b/src/oas.md index 99f5302255..94f9f68cd4 100644 --- a/src/oas.md +++ b/src/oas.md @@ -16,20 +16,18 @@ For examples of OpenAPI usage and additional documentation, please visit [[?Open For extension registries and other specifications published by the OpenAPI Initiative, as well as the authoritative rendering of this specification, please visit [spec.openapis.org](https://spec.openapis.org/). -### Versions +### Versions and Deprecation The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example `3.1`) SHALL designate the OAS feature set. _`.patch`_ versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.1.0` and `3.1.1` for example. -Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. - -### Deprecation - Certain fields or features may be marked **Deprecated**. These fields and features remain part of the specification and can be used like any other field or feature. However, OpenAPI Description authors should use newer fields and features documented to replace the deprecated ones whenever possible. At this time, such elements are expected to remain part of the OAS until the next major version, although a future minor version of this specification may define a policy for later removal of deprecated elements. +Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. + ### Undefined and Implementation-Defined Behavior This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. @@ -94,7 +92,7 @@ This is the root object of the [OpenAPI Description](#openapi-description). | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Document. This is _not_ related to the API [`info.version`](#info-version) string. | +| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI Document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Document. This is _not_ related to the API [`info.version`](#info-version) string. | | $self | `string` | This string MUST be in the form of a URI-reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix G]((#appendix-g-examples-of-base-uri-determination-and-reference-resolution)) for examples of using `$self` to resolve references. | | info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. | | jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. | From 2c56b007c3f64a7d8f5cc80938bff8d6c1cb649e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 22 Aug 2025 10:13:27 -0700 Subject: [PATCH 2/5] Remove outdated Server Object crossref The topic is now in the next section under the Server Object --- src/oas.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 94f9f68cd4..bb94ae3018 100644 --- a/src/oas.md +++ b/src/oas.md @@ -321,8 +321,6 @@ An object representing a Server. This object MAY be extended with [Specification Extensions](#specification-extensions). -See [Examples of API Base URL Determination](#examples-of-api-base-url-determination) for examples of resolving relative server URLs. - #### Relative References in API URLs API endpoints are by definition accessed as locations, and are described by this specification as **_URLs_**. From 445d76f62da3ed15bb2002118c183448bee45bc5 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 22 Aug 2025 13:25:32 -0700 Subject: [PATCH 3/5] Rename "Schema" to "Objects and Fields" --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index bb94ae3018..0dc33c781a 100644 --- a/src/oas.md +++ b/src/oas.md @@ -49,7 +49,7 @@ Examples in this specification will be shown in YAML for brevity. All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. -The [schema](#schema) exposes two types of fields: _fixed fields_, which have a declared name, and _patterned fields_, which have a declared pattern for the field name. +OAS [Objects](#objects-and-fields) expose two types of fields: _fixed fields_, which have a declared name, and _patterned fields_, which have a declared pattern for the field name. Patterned fields MUST have unique names within the containing object. @@ -75,7 +75,7 @@ Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown While the framing of CommonMark 0.27 as a minimum requirement means that tooling MAY choose to implement extensions on top of it, note that any such extensions are by definition implementation-defined and will not be interoperable. OpenAPI Description authors SHOULD consider how text using such extensions will be rendered by tools that offer only the minimum support. -## Schema +## Objects and Fields This section describes the structure of the OpenAPI Description format. This text is the only normative description of the format. From f80a4cd49fc31ac140b142de1c392b6d6991848e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 27 Aug 2025 09:03:05 -0700 Subject: [PATCH 4/5] Add links to Introduction. This adds some links to key sections that introduce major concepts that used to be in the introductory sections of the OAS. It insures that concepts like the difference between serialized and in-memory data, as well as the multi-document structure of OADs, are quickly noticed in a top-to-bottom reading (rare as those may be). --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 0dc33c781a..0408555572 100644 --- a/src/oas.md +++ b/src/oas.md @@ -8,9 +8,9 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service by [parsing and serializing](#parsing-and-serializing) HTTP messages to and from a [data model](#data-types) with a minimal amount of implementation logic. -An OpenAPI Description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. +An [OpenAPI Description](#openapi-description-structure) (OAD) can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. For examples of OpenAPI usage and additional documentation, please visit [[?OpenAPI-Learn]]. From 2b4c061afa03d0ca5af74581f59096a6795c588e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 28 Aug 2025 10:52:35 -0700 Subject: [PATCH 5/5] Remove counter-intuitive section name hack. --- src/oas.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index 0408555572..b1d4f002e6 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1396,9 +1396,7 @@ The `maxLength` keyword MAY be used to set an expected upper bound on the length For unencoded binary data, the length is the number of octets. For this use case, `maxLength` MAY be implemented outside of regular JSON Schema evaluation as JSON Schema does not directly apply to binary data, and an encoded binary stream may be impractical to store in memory in its entirety. - - -#### Special Considerations for `text/event-stream` Content +#### Special Considerations for Server-Sent Events For `text/event-stream`, implementations MUST work with event data after it has been parsed according to the [`text/event-stream` specification](https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream), including all guidance on ignoring certain fields (including comments) and/or values, and on combining values split across multiple lines. @@ -1641,7 +1639,7 @@ Our `application/json-seq` example has to be an external document because of the ##### Server-Sent Event Streams -For this example, assume that the generic event schema provided in the [Special Considerations for `text/event-stream` Content](#considerations-event-stream) section is available at `#/components/schemas/Event`: +For this example, assume that the generic event schema provided in the [Special Considerations for `text/event-stream` Content](#special-considerations-for-server-sent-events) section is available at `#/components/schemas/Event`: ```yaml description: A request body to add a stream of typed data.