Everything but the guide

This marks a shift from introducing breaking changes to fixing bugs and writing a migration guide for moving from OpenAPIKit v3.x to OpenAPIKit v4.0.0. There may be more breaking changes, but my goal is to get to a stable place to release the next major version and save most improvements requiring breaking changes for the following major version.

What's Changed

Non-breaking

• Fix URLTemplate stack overflow (#384)
• Fix typo in symbol name for server variable validations by @theoriginalbit (#385)
• Add support for new patch versions of OAS (#386)

Breaking

• New OAS versions do modify an enum so if you are switching on the value of the OpenAPI version, this is a breaking change.
• Update the default version for new documents and documents converted from OAS 3.0 to OAS 3.1. This isn't likely to cause problems, but if you don't specify the version, it will be changing in future output of this library. The newer versions are mostly clarifications of the specification, so this does not have any impact on the actual definitions OpenAPIKit produces, just the OpenAPI Specification version indicated in the output.

New Contributors

• @theoriginalbit made their first contribution in #385

Full Changelog: 4.0.0-alpha.6...4.0.0-beta.1

And whereas this update clarifies prior statements

(clarifications to the OpenAPI specification, that is)

What's Changed

• Fix typo in symbol name for server variable validations by @theoriginalbit (#385)
• Add support for new patch versions of OAS (3.0.4, 3.1.1) (#386)

⚠️ Heads up

• From a Swift standpoint, adding OAS v3_0_4 and v3_1_1 is a breaking change if you have any switch statements that match on the version enumeration and don't allow for future additions to the enumeration. This is regrettable but it is not practical to release a new major version of OpenAPIKit when the OAS standard introduces clarification patch versions like is the case this time.
• OpenAPIKit does not consider the introduction of deprecation warnings a breaking change but if you treat warnings as errors then this update will be breaking if you use the serverVarialbeEnumIsValid or serverVarialbeDefaultExistsInEnum builtin validations explicitly in your code. These have been renamed to serverVariableEnumIsValid and serverVariableDefaultExistsInEnum to fix the spelling errors in their names.

New Contributors

• @theoriginalbit made their first contribution in #385

Full Changelog: 3.2.2...3.2.3

Dig Deep

What's Changed

• Fix URLTemplate stack overflow (#384)

Full Changelog: 3.2.1...3.2.2

The Times They Are A-Changin'

What's Changed

• Functionality and Unit Tests were fixed for latest versions of Swift and the Foundation LIibrary (#381)

Full Changelog: 3.2.0...3.2.1

Sometimes One Isn't Enough (4)

What's Changed

• Fix typo: secutity -> security by @timimahoney (#375)
• Add JSON Schema $defs encoding & decoding (#376)
• Add support for multiple content types on one content encoding object (#379)

Breaking Changes

• Removed the contentType property on OpenAPI.Content.Encoding. Use the newer contentTypes property (and constructor argument) for the same purpose.
• Removed the fallback implementations of inferred, anchor, and dynamicAnchor in the JSONSchemaContext. 99% of code will not change as a result of this because they were only there to make any pre-existing third-party conformances to JSONSchemaContext continue to work throughout the v3 releases.

New Contributors

• @timimahoney made their first contribution in #375

Full Changelog: 4.0.0-alpha.5...4.0.0-alpha.6

Sometimes One Isn't Enough

What's Changed

• Add JSONSchema support for anchors (#360)
• Fix equality comparison of URL AnyCodables (#371)
• Fix typo: secutity -> security by @timimahoney (#375)
• Add JSON Schema $defs encoding & decoding (#376)
• Add support for multiple content types on one content encoding object (#379)

Deprecations

Support for multiple content types on encoding objects was added via a new contentTypes property; with that, the existing contentType (singular) property has been deprecated and will be removed in the next major version.

New Contributors

• @timimahoney made their first contribution in #375

Full Changelog: 3.1.3...3.2.0

Leave A Message

What's Changed

• Port of ExternallyDereferenceable to OpenAPIKit30 (#373)
• Support arbitrary messaging from external loaders (#374)

Breaking Changes

• The Document externallyDereference() function's first argument label has been renamed from in to with. This fits the language better: "dereference a document with a particular Loader."
• The ExternalLoader protocol's load() function needs to return an array of "messages" now. If you don't have use for these messages, you can set the type of the message to Void and always return an empty array. The new return is there to facilitate you passing information back to yourself from the load() function.

Big Picture

Now external loading (a.k.a. external dereferencing of JSON references) is supported by both modules of OpenAPIKit. Check out the README, OpenAPI.Document's externallyDereference() docs, and ExternalLoader docs.

Full Changelog: 4.0.0-alpha.4...4.0.0-alpha.5

The grass is always greener (in another file)

What's Changed

Non-Breaking

• Add JSONSchema support for anchors (#360)
• Fix equality comparison of URL AnyCodables (#371)

Breaking

• Raise minimum Yams version. by @brandonbloom in #366
• Load external references (OAS 3.1 documents only) (#369)
• Raise minimum MacOS version to v10_15

Highlights

This version introduces preliminary support for resolving external JSON references (to other files). Initially this is only supported by the OpenAPIKit module, both support for OpenAPIKit30 is planned.

See the README and the ExternalLoader protocol documentation for details on how to use the new functionality.

Full Changelog: 4.0.0-alpha.3...4.0.0-alpha.4

Null Happens (4)

What's Changed

• fix "nullable" decoding by @brandonbloom in #356

Technically nullable decoding was not broken for v3.1 documents, but this patch version introduces some leniency which allows decoding documents that contain the nullable keyword. This keyword was the way of specifying nullability in v3.0 of the spec but in v3.1 the keyword was removed entirely. OpenAPIKit will now warn but automatically translate the nullable keyword into a valid v3.1 representation.

New Contributors

• @brandonbloom made their first contribution in #356

Full Changelog: 4.0.0-alpha.2...4.0.0-alpha.3

Null Happens

What's Changed

• fix "nullable" decoding by @brandonbloom in #356

Technically nullable decoding was not broken for v3.1 documents, but this patch version introduces some leniency which allows decoding documents that contain the nullable keyword. This keyword was the way of specifying nullability in v3.0 of the spec but in v3.1 the keyword was removed entirely. OpenAPIKit will now warn but automatically translate the nullable keyword into a valid v3.1 representation.

New Contributors

• @brandonbloom made their first contribution in #356

Full Changelog: 3.1.2...3.1.3