Relax

Relax the version requirement for the Yams test dependency so that downstream projects can use more than 1 major version of Yams.

`Link` And Subscribe

Well, mostly just Link.

This release introduces the Link type to support OpenAPI Link Objects where previously those objects were quietly ignored.

The release also fixes a bug where certain String values coming from YAML files could be accidentally parsed as non-string values (like the string 'inf' being parsed as infinity rather than simply the string "inf"). The bug is addressed by specifically looking for a string value (rather than letting AnyCodable decide) when we know the OpenAPI schema specifies a string type is expected. Thanks to @kean for finding and fixing the bug and then backporting it from the pre-release 3.0.0 branch to the main branch!

Just do your best

Among the other changes listed below, this release swaps out some errors that used to cause decoding to fail for warnings so that more documents can be decoded even if they don't quite follow the specification. The warnings are stored and you can get at them all easily by calling document.validate(strict: false) which returns all warnings that were produced. By default, validate() will be strict and all warnings will become validation failures, so validation still serves to determine whether a document really follows the spec. to the letter.

Big thanks to @kean for both the direct contributions to the code in this release and also the immensely helpful suggestions and bug reports.

Enhancements

• A few parsing errors have been turned into warnings when there is still some way to finish parsing a document despite a problem being found.
• OpenAPI 3.1 support (the OpenAPIKit module) for multiple examples on JSONSchema as specified by JSON Schema.
• You can disable VendorExtensions from being decoded or encoded (which can be a big boost to performance) by setting VendorExtensionsConfiguration.isEnabled = false. (@kean)
• OpenAPIKit retains the order of more decoded objects (including properties in JSONSchema objects). (@kean)

Bug Fixes

• Fix mistaken decoding of AnyCodable values that aren't strings when a JSONSchema's type is specified to be string. (@kean)

⚠️ Breaking Changes ⚠️

• The OpenAPIKit module (but not the OpenAPIKit30 module) now exposes only an examples property on JSONSchemas and their contexts. This is backwards compatible with example when decoding, but code that references example will need to be updated to use the new examples array instead.
• The externally available ContentType is changing from an enum to a struct. Equality checks for all of the previous enum's cases will still work against new static constructors but switch statements will no longer be possible.
• Code that works with the newly converted OrderedDictionary properties will likely work without modification, but there are some methods supported by Dictionary but not OrderedDictionary so some code may need to be tweaked. See #233 if you are curious what properties have changed.
• Response.StatusCode is changing from an enum to a struct. Code won't necessarily need to change, but switching on it will need to instead switch on its value property.
• JSONSchema is changing from an enum to a struct (as usual, to facilitate storage of warnings). For most code, use will not change, but if you switch over any JSONSchemas, you should change to switching over the newly exposed value property of JSONSchema instead.

A Linkable Moment

This release adds the missing Link Object to both the OpenAPI 3.1 and OpenAPI 3.0 modules.

Describe it to me differently

The biggest change since alpha 1 is that all occurrences of JSONReference outside of JSONSchema have been replaced by a new OpenAPI.Reference type.

This change only impacts the OpenAPIKit module that targets v3.1 of the specification. This alpha does not change the OpenAPIKit30 module that targets v3.0 of the spec.

This new type attempts to expose all of the same conveniences of JSONReference but it additionally introduces support for overriding the summary or description of the object being referenced. These overrides only apply when the referenced object would have already supported the summary or description field (otherwise the override is ignored). You can also find the JSONReference at the jsonReference property of an OpenAPI.Reference.

This move comes with a couple of small but definitely breaking changes to code that uses JSONReference directly. For example, anywhere you used to create a reference with JSONReference.internal(.path(...)) you will now use OpenAPI.Reference.internal(path: ...).

We're seeing double now

NOTE: The following will refer to both OpenAPIKit v3.0.0 (this library's upcoming version) and also OpenAPI v3.0/v3.1 (two versions of the specification this library implements). Notice the Kit suffix is the easiest way to tell if I am talking about this library. It can be confusing to keep these straight, because this library follows semantic versioning (wherein v3.0.0 is a major version bump associated with breaking changes) and the specification itself does not follow semantic versioning (the move from v3.0 to v3.1 of the specification is associated with breaking changes) -- and, what's worse, it is merely coincidental that the specification is on v3.1 and the library is on v3.0.

Here's a table that might help:

OpenAPIKit	OpenAPI v3.0	OpenAPI v3.1
v1.x	✅	❌
v2.x	✅	❌
v3.x	✅	✅

Release Notes

Version 3.0.0 of OpenAPIKit primarily focuses on supporting the new v3.1 of the OpenAPI specification. It will, however, also make some small breaking changes to support for the OpenAPI v3.0 specification where those changes fix bugs, drastically clean things up, or support really beneficial new features.

The release notes for this first alpha of OpenAPIKit 3.0.0 will not go into details on the differences between OpenAPIKit's implementation of v3.0 and v3.1 of the OpenAPI specification. It will, however, describe the biggest difference going into this major version of the OpenAPIKit library:

Two Modules. The two public modules are OpenAPIKit30 (support for v3.0 of the specification) and OpenAPIKit (support for v3.1 of the specification).

v3.0.0 of OpenAPIKit splits support for OpenAPI v3.0 and OpenAPI v3.1 into separate modules because there are incompatibilities between the two versions that are most easily handled by either picking which version of the specification to use or explicitly referring to the version being used if both are needed.

Migrating from OpenAPIKit v2.x

V3.0 of the specification

To use the OpenAPI v3.0 specification much like it has been supported in past versions of this library, change your imports as follows:

// before:
import OpenAPKit

// after:
import OpenAPIKit30

If you are using Swift Package Manager, also change your dependency from the string "OpenAPIKit" or the product .product(name: "OpenAPIKit", package: "OpenAPIKit") to .product(name: "OpenAPIKit30", package: "OpenAPIKit").

Beyond that, the only change you currently need to look out for is that JSONReferences inside JSONSchema has gained a context so that it can support optionality. This means switches that match may need to change as follows:

// before:
case .reference(let ref) ...

// after:
case .reference(let ref, let context) ...

The new context contains the required boolean. This boolean defaults to true, but can be made false if a reference should be optional (which means it will be left out of its parent's required array on serialization to JSON/YAML).

You can also access this context with the new referenceContext accessor on JSONSchema and you can now reliably test whether a reference schema is required with the JSONSchema required accessor (boolean for whether or not any particular schema is required).

v3.1 of the specification

As noted above, the release notes for this alpha won't go into details on the differences between OpenAPIKit's support for v3.0 and v3.1 of the OpenAPI specification. Future alpha & beta releases will detail some of these differences; for now, this release serves as a way to test some of those differences for practicality.

To use the new version, you use the OpenAPIKit module (as opposed to the OpenAPIKit30 module that supports v3.0 of the specification).

Thanks

Thanks goes to @siemensikkema for implementing support of required/optional reference schemas and @mihaelamj for implementing numerous changes required by the OpenAPI v3.1 specification.

A Path To Validation

• Add lookup() and unwrapAndLookup() validation helpers to make it easier to work with JSON references during validation (see Validation Documentation).
• Add filteringPaths() method to OpenAPI.PathItem.Map and OpenAPI.Document to assist in quickly filtering the paths in the documentation down to a subset (producing a new path item map or a new document).

Reference cycles are reference cycles are reference...

JSON Schema (OpenAPI Schema Object) reference cycles were not previously handled by the OpenAPIKit dereferencing logic; this bug fix handles reference cycles by producing an error message instead of crashing after running out of stack space.

Serve Up Some Variables

The URLTemplate type used for the OpenAPI.Server urlTemplate property now exposes information on the variables contained within it in two ways and will fail if the URL used to create it has malformed variables.

You can access an array of variable names within the template via the variables property or an array of components (variables and constants) via the components property.

You can now use the optional serverVariablesAreDefined validation to assert that if a variable exists in the template for a Server Object's URL, then that same Server Object gives the variable a definition (See the OpenAPI Server Variable and the variables property on the OpenAPIKit Server type).

You can replace URL template variables with values to turn a template into a valid fully formed URL. The URLTemplate type exposes a replacing(_:) method for just this purpose. Once all variables have been replaced by constant values, you can use the url property of URLTemplate to attempt to retrieve a valid Foundation URL if possible.

Other Additions

• ValidationErrorCollection now uses a newline separated list of its errors as its description (you can use String(describing: errors) to get this description).
• The JSONSchema type has a series of properties to check if a given schema is of a particular type. isBoolean, isNumber, isInteger, etc.
• A new all(_:) has been added to the validation helpers. This function accepts any number of Validations and produces a function of the type expected by a check clause of another Validation. See the Validation Documentation for more.

Everyone gets a default

Schema Objects were missing the JSON Schema default property that allows you to define a default for values. This release adds defaultValue to the CoreContext and the JSONSchema type.

The defaultValue property is an AnyCodable so that you are not tied to one Swift way of representing each JSON type when defining default values.