Finish migration guide.

documentation/schema_object.md

@@ -54,6 +54,48 @@ let buildOut = stringSchema
   .with(allowedValues: "red", "green", "blue")
 ```
 
+### Simplifying Schemas
+The support for this feature is in its early stages with some gaps in what can be successfully simplified and a lot of room for additional heuristics.
+
+You can take any `JSONSchema` and dereference it with `.dereferenced()` or `.derefererenced(in:)`. You can then take the `DereferencedJSONSchema` and simplify it with `.simplified()`. Simplification will try to take a schema and make it into the simplest alternative schema that still has the same meaning. Many schemas are already in their simplest form, but when you start using schema components like `any`, `all`, `one`, etc. you open the door to schemas that are more complicated than other equivalent schemas.
+
+For example, the following schema with `.all(of:)` the given fragments add up to a simpler `.object` schema with the same rules:
+```json
+{
+  "allOf": [
+    {
+      "type": "object",
+      "properties": {
+        "hello": {
+          "type": "string"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer"
+      }
+    }
+  ]
+}
+```
+
+The above schema gets simplified to the below schema.
+```json
+{
+  "type": "object",
+  "properties": {
+    "hello": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": {
+    "type": "integer"
+  }
+}
+```
+
 ### Generating Schemas from Swift Types
 
 Some schemas can be easily generated from Swift types. Many of the fundamental Swift types support schema representations out-of-box.

documentation/v2_migration_guide.md

@@ -1,3 +1,5 @@
+## OpenAPIKit v2 Migration Guide
+For general information on the v2 release, see the release notes on GitHub. The rest of this guide will be formatted as a series of changes and what options you have to migrate code from v1 to v2. Many people will not need to do anything to switch to OpenAPIKit v2, but if you find yourself curious or facing a compilation error, take a look at this guide.
 
 ### `OpenAPI.Server` `url` property removed
 In order to support server URLs with variables in them, you can no longer access a Foundation `URL` on the `Server` type. The `url` property has been replaced with the `urlTemplate` property. You will need to account for the possibility that the given `urlTemplate` is not a valid Foundation `URL` (because it can have variables for which values are not known yet).
@@ -12,6 +14,17 @@ The OpenAPI Specification does not require the `schema` property on the Media Ty
 #### Options
 - Handle the optionality of the `OpenAPI.Content` and `OpenAPI.DereferencedContent` `schema` property.
 
+### `OpenAPI.Components` dereferencing methods refactored.
+In OpenAPIKit v1, the `OpenAPI.Components` type offered the methods `dereference(_:)` and `forceDereference(_:)` to perform lookup of components by their references. These were overloaded to allow looking up `Either` types representing either a reference to a component or the component itself.
+
+In OpenAPIKit v1.4, true dereferencing was introduced. True dereferencing does not just turn a reference into the value it refers to, it removes references deeply for all properties of the given value. That made the use of the word dereference in the `OpenAPI.Components` type's methods misleading -- these methods "looked up" values but did not "dereference" them.
+
+OpenAPIKit v2 fixes this confusing naming by supporting component lookup via `subscript` (non-throwing) and `lookup(_:)` (throwing) methods. It no longer offers any methods that truly (deeply) dereference types. At the same time, OpenAPIKit v2 adds the `dereferenced(in:)` method to most OpenAPI types. This new method takes an `OpenAPI.Components` value and returns a fully dereferenced version of `self`. The `dereferenced(in:)` method offers the same deep dereferencing behavior exposed by the `OpenAPI.Document` `locallyDereferenced()` method that was added in OpenAPIKit v1.4.
+
+#### Options
+- Switch from `components.dereference(resourceReference)` to `components[resourceReference]` and from `try components.forceDereference(resourceReference)` to `components.lookup(resourceReference)`.
+- Consider deep dereferencing with `try resource.dereferenced(in: components)`.
+
 ### `DereferencedJSONSchema` underlying schema property renamed
 The `DereferencedJSONSchema` property previously named `underlyingJSONSchema` has been renamed `jsonSchema` to better reflect the fact that the schema is _built_ from the dereferenced schema rather than being stored as an underlying type from which the dereferenced schema was built.
 
@@ -26,6 +39,12 @@ The new names align with that of the `LocallyDereferenceable` protocol that is c
 #### Options
 - Rename `schema.dereferencedSchemaObject()` to `schema.dereferenced()` and `schema.dereferencedSchemaObject(resolvingIn:)` to `schema.dereferenced(in:)`.
 
+### `JSONSchema` and `DereferencedJSONSchema` `Context` types renamed
+The `JSONSchema.Context` and `DereferencedJSONSchema.Context` types have both been renamed to `CoreContext`. Accordingly, the `JSONSchema` `generalContext` property has been renamed to `coreContext`. This new naming was originally inspired by naming chosen for the now-removed `JSONSchemaFragment` type (see below) but I kept them because the names `coreContext`/`CoreContext` do a good job of describing the context shared by all schema types.
+
+#### Options
+- Rename `generalContext` property uses to `coreContext` and rename `Context` type uses to `CoreContext`.
+
 ### `JSONSchema` context optionality
 In order to support schema fragments as part of the `JSONSchema` type (or in other words just make the `JSONSchema` type actually expressive enough to handle all schemas), a number of properties on some schema contexts needed to become optional. This was accomplished without changing the encoding/decoding behavior or indeed even the results returned by public accessors. However, the fact remains that whereas schemas could previously have `nullable` of `true` or `false`, they can now have `nullable` of `true`, `false`, and `nil` (interpreted as `false` at the time of encoding/decoding). 
 
@@ -36,3 +55,9 @@ In OpenAPIKit v1.x there was a type `JSONSchemaFragment` that represented schema
 
 #### Options
 - Anywhere you have explicitly named the `JSONSchemaFragment` type, rename to `JSONSchema`. Update `JSONSchema.undefined` to `JSONSchema.fragment`. Update `JSONSchemaFragment.general` to `JSONSchema.fragment`.
+
+### `JSONSchema` compound cases gained a full `CoreContext`
+Whereas the `all(of:)`, `any(of:)`, and `one(of:)` cases used to have a `discriminator` as their second associated value and the `not()` case did not have a second associated value at all, they all have gained a full `CoreContext` as their second associated value. This allows `JSONSchema` to express more valid OpenAPI schemas without too much sacrifice. There is an opportunity to add some `Validations` in the future to get back some of the strictness for which the OpenAPIKit library strives.
+
+#### Options
+- Update your case matching for these cases. If you need to access the discriminator, it now lives within the `CoreContext` of each case.