Merge pull request #476 from mattpolzin/feature/474/update-oas-links

mattpolzin · web-flow · commit d267e29373b3 · 2025-12-30T09:54:43.000-06:00
update documentation around OAS versions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,22 +2,23 @@ Thank you for considering contributing to OpenAPIKit!
 
 Take a look at the [Code of Conduct](https://github.com/mattpolzin/OpenAPIKit/blob/master/CODE_OF_CONDUCT.md) and note the [MIT license](https://github.com/mattpolzin/OpenAPIKit/blob/master/LICENSE.txt) associated with this project.
 
-If you are preparing a change for the current release of OpenAPIKit (major version 4), branch off of the `main` branch of this repositroy. If you are preparing a fix for version 3 of OpenAPIKit, branch off of the `release/3_x` branch of this repository. If you are preparing a change for the next major release of OpenAPIKit (major version `5`), branch off of the `release/5_0` branch of this repository.
+If you are preparing a change for the current release of OpenAPIKit (major version 5), branch off of the `main` branch of this repositroy. If you are preparing a fix for version 4 of OpenAPIKit, branch off of the `release/4_x` branch of this repository. If you are preparing a change for the next major release of OpenAPIKit (major version `6`), branch off of the `release/6_0` branch of this repository.
 
 Please do the following in the course of preparing a branch and pull request for this project.
 
 - Create an issue motivating the changes you want to make if one does not already exist. If you are unsure of how to adress an issue, seek out converstation on the issue before committing to a strategy.
 - Add test cases that cover the logical branches of your addition. For bug fixes, at least one of your test cases should fail prior to your change to serve as a regression test against the bug being fixed.
 - If relevant, cite the OpenAPI specification in describing your changes.
-- If your changes only apply for OpenAPI 3.1.x documents, modify the `OpenAPIKit` module. If your changes only apply for OpenAPI 3.0.x documents, modify the `OpenAPIKit30` module. If your changes apply to both, please port your changes from one to the other so both are updated if you have time. If you don't have time to apply changes to both modules, create a PR and ask for assistance with porting your changes. If you are not sure whether your changes apply to both modules, you can also create a PR and then ask for clarification.
+- If your changes only apply for OpenAPI 3.1.x and 3.2.x documents, modify the `OpenAPIKit` module. If your changes only apply for OpenAPI 3.0.x documents, modify the `OpenAPIKit30` module. If your changes apply to both, please port your changes from one to the other so both are updated if you have time. If you don't have time to apply changes to both modules, create a PR and ask for assistance with porting your changes. If you are not sure whether your changes apply to both modules, you can also create a PR and then ask for clarification.
+- If your changes only apply to OpenAPI 3.2.x documents, add "conditional warnings" so that the `OpenAPIKit` module can support the OAS 3.2.x feature but also warn if an OAS 3.1.x document uses that feature. See existing types with `HasConditionalWarnings` protocol conformance for examples.
 
 ### Goals for each currently maintained major version
 
-`3.x`: Non-breaking changes that fix bugs or add improvements to the support of either OpenAPI Spec v3.0.x or OpenAPI Spec v3.1.x.
-`4.x`: Non-breaking changes that fix bugs or add improvements to the support of OpenAPI Spec v3.0.x, OpenAPI Spec v3.1.x, external dereferencing, or Swift concurrency.
+`4.x`: Non-breaking changes that fix bugs or add improvements to the support of either OpenAPI Spec v3.0.x or OpenAPI Spec v3.1.x.
+`5.x`: Non-breaking changes that fix bugs or add improvements to the support of OpenAPI Spec v3.0.x, OpenAPI Spec v3.1.x, or OpenAPI Spec v3.2.x.
 
 #### Goals for the Next/unreleased version
-The next major version will be `5.0`.
+The next major version will be `6.0`.
 
 Priorities for this release have not been settled on yet.
 
diff --git a/Sources/OpenAPIKit/Callbacks.swift b/Sources/OpenAPIKit/Callbacks.swift
@@ -13,7 +13,7 @@ extension OpenAPI {
     /// A map from runtime expressions to path items to be used as
     /// callbacks for the API. The OpenAPI Spec "Callback Object."
     ///
-    /// See [OpenAPI Callback Object](https://spec.openapis.org/oas/v3.1.1.html#callback-object).
+    /// See [OpenAPI Callback Object](https://spec.openapis.org/oas/v3.2.0.html#callback-object).
     ///
     public typealias Callbacks = OrderedDictionary<CallbackURL, Either<OpenAPI.Reference<PathItem>, PathItem>>
 
diff --git a/Sources/OpenAPIKit/Components Object/Components.swift b/Sources/OpenAPIKit/Components Object/Components.swift
@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "Components Object".
     ///
-    /// See [OpenAPI Components Object](https://spec.openapis.org/oas/v3.1.1.html#components-object).
+    /// See [OpenAPI Components Object](https://spec.openapis.org/oas/v3.2.0.html#components-object).
     /// 
     /// This is a place to put reusable components to
     /// be referenced from other parts of the spec.
diff --git a/Sources/OpenAPIKit/Content/Content.swift b/Sources/OpenAPIKit/Content/Content.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Media Type Object"
     /// 
-    /// See [OpenAPI Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object).
+    /// See [OpenAPI Media Type Object](https://spec.openapis.org/oas/v3.2.0.html#media-type-object).
     public struct Content: HasConditionalWarnings, CodableVendorExtendable, Sendable {
         /// A schema describing the complete content of the request, response,
         /// parameter, or header.
diff --git a/Sources/OpenAPIKit/Content/ContentEncoding.swift b/Sources/OpenAPIKit/Content/ContentEncoding.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI.Content {
     /// OpenAPI Spec "Encoding Object"
     ///
-    /// See [OpenAPI Encoding Object](https://spec.openapis.org/oas/v3.1.1.html#encoding-object).
+    /// See [OpenAPI Encoding Object](https://spec.openapis.org/oas/v3.2.0.html#encoding-object).
     public struct Encoding: Equatable, CodableVendorExtendable, Sendable {
         public typealias Style = OpenAPI.Parameter.SchemaContext.Style
 
diff --git a/Sources/OpenAPIKit/Document/DereferencedDocument.swift b/Sources/OpenAPIKit/Document/DereferencedDocument.swift
@@ -105,7 +105,7 @@ extension DereferencedDocument {
     /// each path, traversed in the order the paths appear in
     /// the document.
     ///
-    /// See [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) in the specifcation.
+    /// See [Operation Object](https://spec.openapis.org/oas/v3.2.0.html#operation-object) in the specifcation.
     ///
     public var allOperationIds: [String] {
         return paths.values
diff --git a/Sources/OpenAPIKit/Document/Document.swift b/Sources/OpenAPIKit/Document/Document.swift
@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// The root of an OpenAPI 3.1 document.
     /// 
-    /// See [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.1.html).
+    /// See [OpenAPI Specification](https://spec.openapis.org/oas/v3.2.0.html).
     ///
     /// An OpenAPI Document can say a _lot_ about the API it describes.
     /// A read-through of the specification is highly recommended because
@@ -104,7 +104,7 @@ extension OpenAPI {
         ///
         /// Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration.
         /// The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses
-        /// See [OpenAPI Webhook Object](https://spec.openapis.org/oas/v3.1.1.html#fixed-fields)
+        /// See [OpenAPI Webhook Object](https://spec.openapis.org/oas/v3.2.0.html#fixed-fields)
         public var webhooks: OrderedDictionary<String, Either<OpenAPI.Reference<OpenAPI.PathItem>, OpenAPI.PathItem>>
         
         /// A declaration of which security mechanisms can be used across the API.
@@ -262,7 +262,7 @@ extension OpenAPI.Document {
     /// each path, traversed in the order the paths appear in
     /// the document.
     ///
-    /// See [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) in the specifcation.
+    /// See [Operation Object](https://spec.openapis.org/oas/v3.2.0.html#operation-object) in the specifcation.
     ///
     public var allOperationIds: [String] {
       return (paths.values + webhooks.values)
@@ -446,7 +446,7 @@ extension OpenAPI {
     /// Multiple entries in this dictionary indicate all schemes named are
     /// required on the same request.
     ///
-    /// See [OpenAPI Security Requirement Object](https://spec.openapis.org/oas/v3.1.1.html#security-requirement-object).
+    /// See [OpenAPI Security Requirement Object](https://spec.openapis.org/oas/v3.2.0.html#security-requirement-object).
     public typealias SecurityRequirement = [JSONReference<SecurityScheme>: [String]]
 }
 
diff --git a/Sources/OpenAPIKit/Document/DocumentInfo.swift b/Sources/OpenAPIKit/Document/DocumentInfo.swift
@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI.Document {
     /// OpenAPI Spec "Info Object"
     ///
-    /// See [OpenAPI Info Object](https://spec.openapis.org/oas/v3.1.1.html#info-object).
+    /// See [OpenAPI Info Object](https://spec.openapis.org/oas/v3.2.0.html#info-object).
     public struct Info: Equatable, CodableVendorExtendable, Sendable {
         public var title: String
         public var summary: String?
@@ -50,7 +50,7 @@ extension OpenAPI.Document {
 
         /// OpenAPI Spec "Contact Object"
         ///
-        /// See [OpenAPI Contact Object](https://spec.openapis.org/oas/v3.1.1.html#contact-object).
+        /// See [OpenAPI Contact Object](https://spec.openapis.org/oas/v3.2.0.html#contact-object).
         public struct Contact: Equatable, CodableVendorExtendable, Sendable {
             public let name: String?
             public let url: URL?
@@ -78,7 +78,7 @@ extension OpenAPI.Document {
 
         /// OpenAPI Spec "License Object"
         ///
-        /// See [OpenAPI License Object](https://spec.openapis.org/oas/v3.1.1.html#license-object).
+        /// See [OpenAPI License Object](https://spec.openapis.org/oas/v3.2.0.html#license-object).
         public struct License: Equatable, CodableVendorExtendable, Sendable {
             public let name: String
             public let identifier: Identifier?
diff --git a/Sources/OpenAPIKit/ExternalDocumentation.swift b/Sources/OpenAPIKit/ExternalDocumentation.swift
@@ -11,7 +11,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "External Documentation Object"
     /// 
-    /// See [OpenAPI External Documentation Object](https://spec.openapis.org/oas/v3.1.1.html#external-documentation-object).
+    /// See [OpenAPI External Documentation Object](https://spec.openapis.org/oas/v3.2.0.html#external-documentation-object).
     public struct ExternalDocumentation: Equatable, CodableVendorExtendable, Sendable {
         public var description: String?
         public var url: URL
diff --git a/Sources/OpenAPIKit/Header/Header.swift b/Sources/OpenAPIKit/Header/Header.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Header Object"
     ///
-    /// See [OpenAPI Header Object](https://spec.openapis.org/oas/v3.1.1.html#header-object).
+    /// See [OpenAPI Header Object](https://spec.openapis.org/oas/v3.2.0.html#header-object).
     public struct Header: Equatable, CodableVendorExtendable, Sendable {
         public typealias SchemaContext = Parameter.SchemaContext
 
diff --git a/Sources/OpenAPIKit/JSONReference.swift b/Sources/OpenAPIKit/JSONReference.swift
@@ -415,14 +415,14 @@ public extension SummaryOverridable {
 }
 
 /// `OpenAPIDescribable` types allow their descriptions to be overridden to facilitate
-/// the OpenAPI 3.1.x feature that a `$ref` can specify a description to be used instead of
+/// the OpenAPI 3.1.x+ feature that a `$ref` can specify a description to be used instead of
 /// whatever description the referenced object has.
 public protocol OpenAPIDescribable: SummaryOverridable {
     func overriddenNonNil(description: String?) -> Self
 }
 
 /// `OpenAPISummarizable` types allow their summaries to be overridden to facilitate
-/// the OpenAPI 3.1.x feature that a `$ref` can specify a summary to be used instead of
+/// the OpenAPI 3.1.x+ feature that a `$ref` can specify a summary to be used instead of
 /// whatever summary the referenced object has.
 public protocol OpenAPISummarizable: OpenAPIDescribable {
     func overriddenNonNil(summary: String?) -> Self
diff --git a/Sources/OpenAPIKit/Link.swift b/Sources/OpenAPIKit/Link.swift
@@ -15,7 +15,7 @@ import Foundation
 extension OpenAPI {
     /// OpenAPI Spec "Link Object"
     ///
-    /// See [OpenAPI Link Object](https://spec.openapis.org/oas/v3.1.1.html#link-object).
+    /// See [OpenAPI Link Object](https://spec.openapis.org/oas/v3.2.0.html#link-object).
     public struct Link: Equatable, CodableVendorExtendable, Sendable {
         /// The **OpenAPI**` `operationRef` or `operationId` field, depending on whether
         /// a `URL` of a remote or local Operation Object or a `operationId` (String) of an
@@ -24,7 +24,7 @@ extension OpenAPI {
         /// A map from parameter names to either runtime expressions that evaluate to values or
         /// constant values (`AnyCodable`).
         ///
-        /// See the docuemntation for the [OpenAPI Link Object](https://spec.openapis.org/oas/v3.1.1.html#link-object) for more details.
+        /// See the docuemntation for the [OpenAPI Link Object](https://spec.openapis.org/oas/v3.2.0.html#link-object) for more details.
         ///
         /// Empty dictionaries will be omitted from encoding.
         public var parameters: OrderedDictionary<String, Either<RuntimeExpression, AnyCodable>>
diff --git a/Sources/OpenAPIKit/Operation/Operation.swift b/Sources/OpenAPIKit/Operation/Operation.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Operation Object"
     /// 
-    /// See [OpenAPI Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object).
+    /// See [OpenAPI Operation Object](https://spec.openapis.org/oas/v3.2.0.html#operation-object).
     public struct Operation: Equatable, CodableVendorExtendable, Sendable {
         public var tags: [String]?
         public var summary: String?
diff --git a/Sources/OpenAPIKit/Parameter/Parameter.swift b/Sources/OpenAPIKit/Parameter/Parameter.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Parameter Object"
     /// 
-    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
+    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.2.0.html#parameter-object).
     public struct Parameter: HasConditionalWarnings, CodableVendorExtendable, Sendable {
         public var name: String
 
@@ -463,7 +463,7 @@ extension OpenAPI.Parameter {
     /// containing exactly the things that differentiate
     /// one parameter from another, per the specification.
     ///
-    /// See [Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
+    /// See [Parameter Object](https://spec.openapis.org/oas/v3.2.0.html#parameter-object).
     internal struct ParameterIdentity: Hashable {
         let name: String
         let location: Context.Location
diff --git a/Sources/OpenAPIKit/Parameter/ParameterContext.swift b/Sources/OpenAPIKit/Parameter/ParameterContext.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI.Parameter {
     /// OpenAPI Spec "Parameter Object" location-specific configuration.
     /// 
-    /// See [OpenAPI Parameter Locations](https://spec.openapis.org/oas/v3.1.1.html#parameter-locations).
+    /// See [OpenAPI Parameter Locations](https://spec.openapis.org/oas/v3.2.0.html#parameter-locations).
     ///
     /// Query, Header, and Cookie parameters are
     /// all optional by default unless you pass
diff --git a/Sources/OpenAPIKit/Parameter/ParameterSchemaContext.swift b/Sources/OpenAPIKit/Parameter/ParameterSchemaContext.swift
@@ -10,8 +10,8 @@ import OpenAPIKitCore
 extension OpenAPI.Parameter {
     /// OpenAPI Spec "Parameter Object" schema and style configuration.
     ///
-    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object)
-    /// and [OpenAPI Style Values](https://spec.openapis.org/oas/v3.1.1.html#style-values).
+    /// See [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.2.0.html#parameter-object)
+    /// and [OpenAPI Style Values](https://spec.openapis.org/oas/v3.2.0.html#style-values).
     public struct SchemaContext: HasConditionalWarnings, Sendable {
         public var style: Style
         public var explode: Bool
@@ -216,7 +216,7 @@ extension OpenAPI.Parameter.SchemaContext.Style {
     /// per the OpenAPI Specification.
     ///
     /// See the `style` fixed field under
-    /// [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
+    /// [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.2.0.html#parameter-object).
     public static func `default`(for location: OpenAPI.Parameter.Context.Location) -> Self {
         switch location {
         case .query:
@@ -236,7 +236,7 @@ extension OpenAPI.Parameter.SchemaContext.Style {
     /// per the OpenAPI Specification.
     ///
     /// See the `style` fixed field under
-    /// [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object).
+    /// [OpenAPI Parameter Object](https://spec.openapis.org/oas/v3.2.0.html#parameter-object).
     public static func `default`(for context: OpenAPI.Parameter.Context) -> Self {
         switch context {
         case .query:
diff --git a/Sources/OpenAPIKit/Path Item/PathItem.swift b/Sources/OpenAPIKit/Path Item/PathItem.swift
@@ -12,7 +12,7 @@ extension OpenAPI {
     /// Object also includes reference support which OpenAPIKit implements via
     /// the PathItem.Map type)
     /// 
-    /// See [OpenAPI Path Item Object](https://spec.openapis.org/oas/v3.1.1.html#path-item-object).
+    /// See [OpenAPI Path Item Object](https://spec.openapis.org/oas/v3.2.0.html#path-item-object).
     ///
     /// In addition to parameters that apply to all endpoints under the current path,
     /// this type offers access to each possible endpoint operation under properties
diff --git a/Sources/OpenAPIKit/Request/Request.swift b/Sources/OpenAPIKit/Request/Request.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Request Body Object"
     ///
-    /// See [OpenAPI Request Body Object](https://spec.openapis.org/oas/v3.1.1.html#request-body-object).
+    /// See [OpenAPI Request Body Object](https://spec.openapis.org/oas/v3.2.0.html#request-body-object).
     public struct Request: Equatable, CodableVendorExtendable, Sendable {
         public var description: String?
         public var content: Content.Map
diff --git a/Sources/OpenAPIKit/Response/Response.swift b/Sources/OpenAPIKit/Response/Response.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Response Object"
     ///
-    /// See [OpenAPI Response Object](https://spec.openapis.org/oas/v3.1.1.html#response-object).
+    /// See [OpenAPI Response Object](https://spec.openapis.org/oas/v3.2.0.html#response-object).
     public struct Response: HasConditionalWarnings, CodableVendorExtendable, Sendable {
         public var summary: String?
         public var description: String?
diff --git a/Sources/OpenAPIKit/RuntimeExpression.swift b/Sources/OpenAPIKit/RuntimeExpression.swift
@@ -10,7 +10,7 @@ import OpenAPIKitCore
 extension OpenAPI {
     /// OpenAPI Spec "Runtime Expression"
     ///
-    /// See [OpenAPI Runtime Expression[(https://spec.openapis.org/oas/v3.1.1.html#runtime-expressions).
+    /// See [OpenAPI Runtime Expression[(https://spec.openapis.org/oas/v3.2.0.html#runtime-expressions).
     ///
     public enum RuntimeExpression: RawRepresentable, Equatable, Sendable {
         case url
diff --git a/Sources/OpenAPIKit/Schema Object/JSONSchema.swift b/Sources/OpenAPIKit/Schema Object/JSONSchema.swift
@@ -9,7 +9,7 @@ import OpenAPIKitCore
 
 /// OpenAPI "Schema Object"
 /// 
-/// See [OpenAPI Schema Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object).
+/// See [OpenAPI Schema Object](https://spec.openapis.org/oas/v3.2.0.html#schema-object).
 public struct JSONSchema: JSONSchemaContext, HasWarnings, Sendable {
 
     public let warnings: [OpenAPI.Warning]
diff --git a/Sources/OpenAPIKit/Schema Object/JSONSchemaContext.swift b/Sources/OpenAPIKit/Schema Object/JSONSchemaContext.swift
@@ -60,7 +60,7 @@ public protocol JSONSchemaContext: Sendable {
     /// be placed on a parent object (one level up from an `allOf`, `anyOf`,
     /// or `oneOf`) as a way to reduce redundancy.
     ///
-    /// See [OpenAPI Discriminator Object](https://spec.openapis.org/oas/v3.1.1.html#discriminator-object).
+    /// See [OpenAPI Discriminator Object](https://spec.openapis.org/oas/v3.2.0.html#discriminator-object).
     var discriminator: OpenAPI.Discriminator? { get }
 
     /// Get the external docs, if specified. If unspecified, returns `nil`.
diff --git a/Sources/OpenAPIKit/Schema Object/TypesAndFormats.swift b/Sources/OpenAPIKit/Schema Object/TypesAndFormats.swift
diff --git a/Sources/OpenAPIKit/Security/DereferencedSecurityRequirement.swift b/Sources/OpenAPIKit/Security/DereferencedSecurityRequirement.swift
diff --git a/Sources/OpenAPIKit/Security/SecurityScheme.swift b/Sources/OpenAPIKit/Security/SecurityScheme.swift
diff --git a/Sources/OpenAPIKit/Server.swift b/Sources/OpenAPIKit/Server.swift
diff --git a/Sources/OpenAPIKit/Tag.swift b/Sources/OpenAPIKit/Tag.swift
diff --git a/Sources/OpenAPIKit/Validator/Validation+Builtins.swift b/Sources/OpenAPIKit/Validator/Validation+Builtins.swift
diff --git a/Sources/OpenAPIKit30/Link.swift b/Sources/OpenAPIKit30/Link.swift
diff --git a/documentation/schema_object.md b/documentation/schema_object.md
diff --git a/documentation/specification_coverage.md b/documentation/specification_coverage.md
