Maximize Goodness

Bug Fixes

• Fix integer max/min parsing and improve inconsistency errors (#342)

Full Changelog: 3.0.0...3.0.1

A Whole New World

This release of OpenAPIKit brings support for OpenAPI 3.1 in addition to numerous other improvements and a fair number of breaking changes (hopefully all worth their weight!).

The biggest thing to know up front is that you will need to choose between one of two modules:
OpenAPIKit30 is a new module that continues to support the OAS 3.0 (OpenAPI 3.0 standard).
OpenAPIKit is the module that supports the OAS 3.1 (OpenAPI 3.1 standard).

I suggest migrating your code to the OpenAPIKit module if possible. You will need to do a bit more work (in some cases, not all) but this will set you up for the broadest support of OpenAPI Documents.

OpenAPIKit 3.0.0 ships with another module named OpenAPIKitCompat that allows you to turn an OpenAPIKit30.OpenAPI.Document into an OpenAPIKit.OpenAPI.Document (i.e. convert from OAS 3.0 to OAS 3.1). There is not yet support for converting from OAS 3.1 to OAS 3.0, though that is a desirable (if not planned) addition. There is documentation on how to use this conversion to write your code against the OpenAPIKit module but support loading in both OAS 3.0 and OAS 3.1 documents here.

There are two ways to explore the changes between OpenAPIKit v2.x and OpenAPIKit v3.0.0:

1. Read the release notes for each v3.0.0 pre-release (best way to see new features added, most granular information on changes including breaking changes).
2. Read the migration guide (fastest way to get yourself going against the new version).

Formats on Formats (release candidate)

What's Changed

• Adds missing contentMediaType and contentEncoding properties to JSONSchema.string() convenience constructor functions (#334)
• Adds a few more builtin content types I was surprised to have not included already (#335)
• JSON Schema String Format Updates (#337)

Breaking Changes

There are no breaking changes to the OpenAPIKit30 module. The following all apply to the OpenAPIKit module.

• There is no longer .extended formats for .string JSON Schemas. Instead, all existing .extended formats are now just regular .string formats (e.g. you can just replace .extended(.uuid) with .uuid).
• There are no longer .byte or .binary formats for .string JSON Schemas. Instead, use the contentEncodings of .base64 and .binary, respectively.
• The .uriReference .extended JSON Schema .string format used to serialize to uriref whereas the new .uriReference JSON Schema .string format serializes to uri-reference, per the JSON Schema standard.
• The new builtin ContentTypes will not compare equally to custom types created previously (e.g. ContentType.gif is not equal to ContentType.other("image/gif"). If you need such things to compare equally, compare their .rawValue properties.

Full Changelog: 3.0.0-rc.3...3.0.0-rc.4

Niche Content (release candidate)

What's Changed

• Made private helpers private again.
• Added Media Type (contentMediaType) and Encoding (contentEncoding) on JSONSchema in the StringContext.

Full Changelog: 3.0.0-rc.2...3.0.0-rc.3

Well Read (release candidate)

Big thanks to @simonbility for jumping in and making another part of OpenAPIKit order-stable when encoding/decoding.

What's Changed

• Use OrderedDictionary for discriminator mapping (#320)
• propagate nullability from subschemas where appropriate (#322)

Breaking Changes

It is very unlikely, but possible, that the change to OrderedDictionary for the mapping property of the Discriminator type could cause compiler errors if your code is using methods specific to the Dictionary type when working with these mappings.

New Contributors

• @simonbility made their first contribution in #320

Full Changelog: 3.0.0-rc.1...3.0.0-rc.2

Noted (release candidate)

The first v3.0.0 Release Candidate.

This release comes with no breaking changes, bug fixes, or features above and beyond the latest Beta release but it introduces the first draft of a migration guide from v2.x to v3.x of OpenAPIKit.

Full Changelog: 3.0.0-beta.5...3.0.0-rc.1

Inline Skates

Big thanks to @nexon for jumping in and fixing a bug related to dereferencing callbacks within operations!

What's Changed

• fix double-validation error reporting (#309)
• Validation error improvements (#308)
• Support JSON Schema const. (#310)
• Dereference Links (#311)
• Refactor vendor extensions on JSONSchema (#312)
• Dereference Callbacks (#314)

New Contributors

• @nexon made their first contribution in #314

Noteworthy Differences

• Dereferenced JSON Schemas now have Vendor Extension support (only OpenAPIKit module, not OpenAPIKit30).
• Links and CallbacksMaps are now dereferenced when calling the dereferenced(in:) and locallyDereferenced() methods.
• JSON Schemas now support const (which is decoded as a single entry in the JSONSchema type's CoreContext's allowedValues array). (only OpenAPIKit, not OpenAPIKit30).

Breaking Changes

1. JSONSchema's initializers no longer take vendorExtensions; instead, use the .with(vendorExtensions:) function to add vendor extensions to a schema or build the vendor extensions into the schema's CoreContext to begin with. (only OpenAPIKit module, not OpenAPIKit30).
2. The DereferencedOperation type's callbacks property is now an OpenAPI.DereferencedCallbacksMap instead of an OpenAPI.CallbacksMap.
3. The DereferencedResponse type's links property is now an OrderedDictionary<String, OpenAPI.Link> instead of an OpenAPI.Link.Map.
4. When a JSONSchema only has one allowedValue, it will now be encoded as const rather than enum. (only OpenAPIKit module, not OpenAPIKit30).
5. The JSONSchema type's coreContext accessor now gives a non-optional value because all cases have a CoreContext. (only OpenAPIKit module, not OpenAPIKit30).

---

Full Changelog: 3.0.0-beta.4...3.0.0-beta.5

Flexibility is Key

What's Changed

• Optional responses within operations (#303)
• Add core context for null schemas (#305)
• Optional paths within documents (#275)

New Contributors

• @noamalffasy made their first contribution in #275

Noteworthy Differences

Now paths within documents and responses within operations can both be omitted from documents (as they should be by the OpenAPI 3.1 specification). This only applies to the OpenAPIKit module, the OpenAPIKit30 module represents the OpenAPI 3.0 specification where these properties are still required. Instead of making the properties on the respective OpenAPIKit types Optional, the empty collection of either paths or responses is now entirely omitted when encoding and an omitted value of either is decoded as the empty collection.

Breaking Changes

The following only apply to the OpenAPIKit module, not the OpenAPIKit30 module.

1. The .operationsContainResponses validation is now opt-in instead of applied by default when validating. If you still want to ensure documents have responses in all Operation objects, tack the .operationsContainResponses validation onto your validator, e.g.: try document.validate(using: Validator().validating(.operationsContainResponses)).
2. The null case of JSONSchema.Value now has a CoreContext property associated with it. If you pattern match on it, your code may need to change (though you are still allowed to match against just .null and ignore the associated value if desirable).
3. The JSONSchema.null property that used to serve as a convenient way of creating a null-type JSONSchema is now a function. You can call it as .null() which means most code will just need to gain the () parens.

---

Full Changelog: 3.0.0-beta.3...3.0.0-beta.4

When Nothing is Everything

What's Changed

• fix bug with conversion of Server Variable enum from OAS 3.0 to 3.1 (#304)

Noteworthy Differences

N/A

Breaking Changes

N/A

---

Full Changelog: 3.0.0-beta.2...3.0.0-beta.3

Dynamite (3)

What's Changed

• Store component name as x-component-name when locally dereferencing an object (#295 / #296)
• Add vendor extension support to JSONSchema (#297)
• Support schema reference description overrides (#299)
• Fix decoding of explode property on Headers (#302)

Noteworthy Differences

Dereferencing

When locally dereferencing part or all of the schema with the OpenAPIKit dereferenced(in:)/dereferenced()/locallyDereferenced() functions, OpenAPIKit will store the name of the Component (the key within the Components Object) under a new x-component-name vendor extension on the dereferenced value.

Example

        let components = OpenAPI.Components(
            examples: [
                "test1": .init(value: .init("hello world"))
            ]
        )
        let content = try OpenAPI.Content(
            schema: .string,
            examples: [
                "ex1": .reference(.component(named: "test1"))
            ]
        ).dereferenced(in: components)
        XCTAssertEqual(
            content.examples, [
                "ex1": .init(
                    value: .init("hello world"),
                    vendorExtensions: ["x-component-name": "test1"]
                )
            ]
        )

Overriding description on schema $refs

OpenAPIKit module only. Does not apply to OpenAPIKit30 module.

See the PR that introduced this change for some comments on why the current implementation was chosen.

OpenAPIKit will now encode/decode any CoreContext JSONSchema property alongside $ref properties. This includes the description, default, examples, deprecated properties, and more.

If you use an OpenAPIKit method for locally dereferencing (e.g. the OpenAPI.Document type's locallyDerefenced() method) then any description found next to a $ref will automatically override any description found within the schema being dereferenced at that location.

If you want to have finer grained control over looking up references (likely you are looking JSONReference types up in the Components Object in your code), you may need to do a little work to get the overriding behavior. When case matching on a reference JSONSchema.Schema, you can now pull the CoreContext out as the second element of the case and access properties like description on it. Alternatively, you can call the coreContext method on JSONSchema to access the CoreContext without switching over the cases of its value. Carry any part or all of this CoreContext along with the JSONReference to the location where your code looks the reference up, and then override the properties you want to override.

This may sound a bit inconvenient relative to, say, OpenAPI.Reference (which handles overriding of description internally without any extra work on your part). As discussed in the notes on the PR linked to above, there are a few reasons for this design. Perhaps the most undeniable argument for this design is that unlike with OpenAPI reference overriding which only supports description and summary, JSON Schema leaves the door open for any properties to live alongside a $ref and it doesn't explicitly state that overriding should be the behavior when dereferencing and it specifically notes that if you try to perform dereferencing where you handle all possible properties alongside $refs then you will almost certainly end up misrepresenting the original author's intent in some cases. Therefore, it is left up to the project using OpenAPIKit to decide which properties to override and which to ignore.

Example

        let components = OpenAPI.Components(
            schemas: ["test": .string(description: "generic description")]
        )

        let data = """
        {
            "type": "object",
            "properties": {
                "prop1": {
                    "$ref": "#/components/schemas/test",
                    "description": "specialized description"
                }
            }
        }
        """.data(using: .utf8)!

        let schema = try JSONDecoder().decode(JSONSchema.self, from: data)
        let property = schema.objectContext?.properties["prop1"]?.value
        switch property {
            case .reference(let ref, let context):
                let result = try components.lookup(ref)
                    .overriddenNonNil(description: context.description)

                XCTAssertEqual(result, .string(description: "specialized description"))
            default:
                break
        }

Breaking Changes

OpenAPIKit module only. Does not apply to OpenAPIKit30 module.
In order to support new versions of the JSON Schema specification that allow $ref properties to live alongside other annotations like description, the JSONSchema type's reference case had its ReferenceContext replaced with a full CoreContext.

Because the ReferenceContext contained only a required property and the CoreContext also has a required property, some code bases will not need to change at all. However, if you did use the ReferenceContext by name in your code, you will need to address compiler errors because of this change.

Another way this change may break code is if you have used the JSONSchema referenceContext accessor. This accessor has been removed and you can now use the coreContext accessor on JSONSchema to get the CoreContext when it is relevant (which includes reference cases going forward).

---

Full Changelog: 3.0.0-beta.1...3.0.0-beta.2