Put together notes on OpenAPI 3.1

This is an attempt to try catalogue the changes that are needed - the
most substantial of which seem to be in the Schema object.

Author: kevindew

TODO.md

@@ -49,3 +49,15 @@ For OpenAPI 3.1
 - [ ] Support the switch to a fixed schema dialect
 - [x] Support summary field on Info node
 - [ ] Create a maxi OpenAPI 3.1 integration test to collate all the known changes
+- [ ] jsonSchemaDialect should default to OAS one
+- [ ] Allow summary and description in Reference objects
+- [ ] Add identifier to License node, make mutually exclusive with URL
+- [ ] ServerVariable enum must not be empty
+- [ ] Add pathItems to components
+- [ ] Callbacks can now reference a PathItem - previously required them
+- [ ] Check out whether pathItem references match the rules for relative resolution
+- [ ] Parameter object can have space delimited or pipeDelimited styles
+- [ ] Discriminator object can be extended
+- [ ] mutualTLS as a security scheme
+- [ ] I think strictness of Security Requirement rules has changed
+

json-schema-for-3.1.md

@@ -0,0 +1,92 @@
+# JSON schema with 3.1
+
+Temporary document to be removed with the merge of support for OpenAPI 3.1
+
+Things have got complex with schemas in OpenAPI 3.1
+
+How things might work:
+
+- when a schema factory is created, it determines whether the dialect is suported
+- it then creates a factory based on the dialect
+- if there is a reference in it this is resolved
+- there could be complexities in the resolving process because of the id field - does it become relative to this?
+- skip dynamicAnchor and dynamicRef for now - they are quite complex: https://stackoverflow.com/questions/69728686/explanation-of-dynamicref-dynamicanchor-in-json-schema-as-opposed-to-ref-and
+- lets allow extra properties for schema since it's complex
+- there's all the $defs stuff but this might just work as being a type of reference - presumably not used in OpenAPI anyway really
+
+So how might we start:
+
+- Perhaps add a class method to Schema which can identify which Schema factory is used: a OAS 3.1 one, an optionally referenced OAS 3.0 one, or non optional reference (if such a need exists), based on context. Error if given an unexpected dialect
+- Learn whether you have to care about $id for resolving
+- Create a node factory for OAS 3.1 Schema:
+  - allow arbitrary fields perhaps? Probably not needed, just a pain to keep up with JsonSchema
+  - load a merged reference
+  - perhaps have context support a merge concept for source location
+- Think about dealing with recursive defined as "#"
+
+Dealing with the new JSON Schema approach for OpenAPI 3.1.
+
+There is some meta fields:
+
+$ref
+$dynamicRef
+$defs
+$schema
+$id
+$comment
+$anchor
+$dynamicAnchor
+
+Then a ton of fields:
+
+type: string
+enum: array
+const: any type
+multipleOf: number
+maximum: number
+exclusiveMaximum: number
+minimum: number
+exclusiveMinimum: number
+maxLength: integer >= 0
+minLength: integer >= 0
+pattern: string
+maxItems: integer >= 0
+minItems: integer >= 0
+uniqueItems: boolean
+maxContains: integer >= 0
+minContains: integer >= 0
+maxProperties: integer >= 0
+minProperties: integer >= 0
+required: array, strings, unique
+dependentRequired: something complex
+contentEncoding: string
+contentMediaType: string / media type
+contentSchema: schema
+title: string
+description: string
+default: any
+deprecated: boolean (default false)
+readOnly: boolean (default false)
+writeOnly: boolean (default false)
+examples: array
+
+
+allOf - non empty array of schemas
+anyOf - non empty array of schemas
+oneOf - non empty array of schemas
+not - schema
+
+if - single schema
+then - single schema
+else - single schema
+
+prefixItems: schema
+items: schema
+contains: schema
+
+properties: object, each value json schema
+patternProperties: object each value JSON schema
+additionalProperties: single json schema
+
+unevaluatedItems - single schema
+unevaluatedProperties: single schema

spec/integration/open_v3.1_examples_spec.rb

@@ -32,4 +32,16 @@
       expect(document.openapi).to eq "3.1.0"
     end
   end
+
+  context "when using the schema I created to demonstrate changes" do
+    let(:path) { File.join(__dir__, "..", "support", "examples", "v3.1", "changes.yaml") }
+
+    xit "is a valid document" do
+      expect(document).to be_valid
+    end
+
+    xit "can access the version" do
+      expect(document.openapi).to eq "3.1.0"
+    end
+  end
 end

spec/support/examples/v3.1/changes.yaml

@@ -0,0 +1,80 @@
+openapi: 3.1.0
+info:
+  title: Examples of changes in OpenAPI 3.1
+  summary: 3.1 introduced a summary field to the Info node
+  version: 1.0.0
+  # license:
+  #   name: Apache 2.0
+  #   identifier: Apache-2.0
+# jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
+components:
+  schemas:
+    BasicSchema:
+      description: "My basic schema"
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    ReferencedSchema:
+      description: "My referenced schema"
+      $ref: "#/components/schemas/BasicSchema"
+    DoubleReferencedSchema:
+      description: "My double referenced schema"
+      $ref: "#/components/schemas/ReferencedSchema"
+    AnotherSchema:
+      $ref: "#/components/schemas/DoubleReferencedSchema"
+    AndAnotherSchema:
+      $ref: "#/components/schemas/AnotherSchema"
+    SelfReferencingSchema:
+      type: object
+      properties:
+        recursive_item:
+          $ref: "#/components/schemas/SelfReferencingSchema"
+    # WithDialect:
+    #   $schema: https://spec.openapis.org/oas/3.1/dialect/base
+    #   type: string
+    # Const:
+    #   const: "test"
+    # MultipleTypes:
+    #   type:
+    #     - string
+    #     - null
+    # Number:
+    #   type: integer
+    #   multipleOf: 5
+    #   maximum: 110
+    #   exclusiveMaximum: 111
+    #   minimum: 10
+    #   exclusiveMinimum: 9
+    # String:
+    #   type: string
+    #   maxLength: 10
+    #   minLength: 5
+    #   pattern: "[a-z]*"
+    # Array:
+    #   type: array
+    #   maxItems: 10
+    #   minItems: 1
+    #   uniqueItems: true
+    #   contains:
+    #     const: "test"
+    #   minContains: 1
+    #   maxContains: 1
+    #   prefixItems:
+    #     - const: "item"
+    #     type: string
+    #   items:
+    #     type: string
+    #   unevaluatedItems:
+    #     type: string
+     # Add object
+     # Add content types
+     # Add $ref usage (plain, merged, defs)
+     # Add compound things: anyOf, oneOf, not, if, then, else