Work towards OpenAPI 3.1 support

TODO.md

@@ -39,3 +39,25 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [ ] Support validating a Server URL based on default values
 - [ ] Validate paths to check path parameters within them appear in paths
       see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#fixed-fields-10
+
+For OpenAPI 3.1
+
+- [x] Conditional nodes
+- [x] Support webhooks
+- [x] No longer require responses field on an Operation node
+- [x] Require OpenAPI node to have webhooks, paths or components
+- [x] 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
+- [x] jsonSchemaDialect should default to OAS one
+- [x] Allow summary and description in Reference objects
+- [x] Add identifier to License node, make mutually exclusive with URL
+- [x] ServerVariable enum must not be empty
+- [x] 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
+- [x] Discriminator object can be extended
+- [x] mutualTLS as a security scheme
+- [ ] I think strictness of Security Requirement rules has changed
+

json-schema-for-3.1.md

@@ -0,0 +1,118 @@
+# 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 supported
+- 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 - in 3.0
+$dynamicRef
+$defs
+$schema
+$id
+$comment
+$anchor
+$dynamicAnchor
+
+Then a ton of fields:
+
+type: string - in 3.0
+enum: array - in 3.0
+const: any type - done
+multipleOf: number - in 3.0
+maximum: number - in 3.0
+exclusiveMaximum: number - done
+minimum: number - in 3.0
+exclusiveMinimum: number - done
+maxLength: integer >= 0 - in 3.0 (missing >= val)
+minLength: integer >= 0 - in 3.0
+pattern: string - in 3.0
+maxItems: integer >= 0 - in 3.0
+minItems: integer >= 0 - in 3.0
+uniqueItems: boolean - in 3.0
+maxContains: integer >= 0 - done
+minContains: integer >= 0 - done
+maxProperties: integer >= 0 - in 3.0
+minProperties: integer >= 0 - in 3.0
+required: array, strings, unique - in 3.0 (missing unique)
+dependentRequired: something complex done
+contentEncoding: string - done
+contentMediaType: string / media type - done
+contentSchema: schema - done
+title: string - in 3.0
+description: string - in 3.0
+default: any - in 3.0
+deprecated: boolean (default false) - in 3.0
+readOnly: boolean (default false) - in 3.0
+writeOnly: boolean (default false) - in 3.0
+examples: array - done
+format: any - in 3.0
+
+allOf - non empty array of schemas - in 3.0
+anyOf - non empty array of schemas - in 3.0
+oneOf - non empty array of schemas - in 3.0
+not - schema - in 3.0
+
+if - single schema - done
+then - single schema - done
+else - single schema - done
+dependentSchemas - map of schemas - done
+
+prefixItems: array of schema - done
+items: schema - in 3.0
+contains: schema - done
+
+properties: object, each value json schema - in 3.0
+patternProperties: object each value JSON schema key regex - done
+additionalProperties: single json schema - done
+
+unevaluatedItems - single schema - done
+unevaluatedProperties: single schema - done
+
+
+## Returning to this in 2025
+
+Assumption: it'll be extremely rare for usage of the advanced schema fields like dynamicRefs and dynamicAnchors, let's see what we can implement that meets most use cases and hopefully doesn't crash on complex ones
+
+Current idea is create a Schema::Common which can share methods between both schema objects that are shared, then add distinctions for differences
+
+At point of shutting down on 10th January 2025 I was wondering about how schemas merge. I also decided to defer thinking about referenceable node object factory.
+
+I learnt that merging seems largely undefined in JSON Schema, as far as I can tell and I'm just going with a strategy of most recent field wins.
+
+I've set up a Node::Schema class for common schema methods and Node::Schema::v3_0 and v3_1Up classes for specific changes. Need to flesh out
+tests and then behaviour that differs between them.
+
+Little things:
+- schema integer fields generally are required to be non-negative
+- quite common for arrays to be invalid if not unique (required, type)
+- probably want a quick way to get coverage of the methods on nodes
+- could validate that pattern and patternProperties contain regexs
+
+JSON Schema specs:
+
+meta: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+validation: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00

lib/openapi3_parser.rb

@@ -7,32 +7,44 @@ module Openapi3Parser
   # For a variety of inputs this will construct an OpenAPI document. For a
   # String/File input it will try to determine if the input is JSON or YAML.
   #
-  # @param  [String, Hash, File]  input Source for the OpenAPI document
+  # @param  [String, Hash, File]  input           Source for the OpenAPI document
+  # @param [Boolean]              emit_warnings   Whether to call Kernel.warn when
+  #                                               warnings are output, best set to
+  #                                               false when parsing specification
+  #                                               files you've not authored
   #
   # @return [Document]
-  def self.load(input)
-    Document.new(SourceInput::Raw.new(input))
+  def self.load(input, emit_warnings: true)
+    Document.new(SourceInput::Raw.new(input), emit_warnings:)
   end
 
   # For a given string filename this will read the file and parse it as an
   # OpenAPI document. It will try detect automatically whether the contents
   # are JSON or YAML.
   #
-  # @param  [String]  path  Filename of the OpenAPI document
+  # @param  [String]  path            Filename of the OpenAPI document
+  # @param [Boolean]  emit_warnings   Whether to call Kernel.warn when
+  #                                   warnings are output, best set to
+  #                                   false when parsing specification
+  #                                   files you've not authored
   #
   # @return [Document]
-  def self.load_file(path)
-    Document.new(SourceInput::File.new(path))
+  def self.load_file(path, emit_warnings: true)
+    Document.new(SourceInput::File.new(path), emit_warnings:)
   end
 
   # For a given string URL this will request the resource and parse it as an
   # OpenAPI document. It will try detect automatically whether the contents
   # are JSON or YAML.
   #
-  # @param  [String]  url URL of the OpenAPI document
+  # @param  [String]  url             URL of the OpenAPI document
+  # @param [Boolean]  emit_warnings   Whether to call Kernel.warn when
+  #                                   warnings are output, best set to
+  #                                   false when parsing specification
+  #                                   files you've not authored
   #
   # @return [Document]
-  def self.load_url(url)
-    Document.new(SourceInput::Url.new(url.to_s))
+  def self.load_url(url, emit_warnings: true)
+    Document.new(SourceInput::Url.new(url.to_s), emit_warnings:)
   end
 end

lib/openapi3_parser/document.rb

@@ -6,17 +6,19 @@ module Openapi3Parser
   # Document is the root construct of a created OpenAPI Document and can be
   # used to navigate the contents of a document or to check it's validity.
   #
-  # @attr_reader  [String]        openapi_version
-  # @attr_reader  [Source]        root_source
-  # @attr_reader  [Array<String>] warnings
+  # @attr_reader  [OpenapiVersion]  openapi_version
+  # @attr_reader  [Source]          root_source
+  # @attr_reader  [Array<String>]   warnings
+  # @attr_reader  [Boolean]         emit_warnings
+  # rubocop:disable Metrics/ClassLength
   class Document
     extend Forwardable
     include Enumerable
 
-    attr_reader :openapi_version, :root_source, :warnings
+    attr_reader :openapi_version, :root_source, :emit_warnings
 
     # A collection of the openapi versions that are supported
-    SUPPORTED_OPENAPI_VERSIONS = %w[3.0].freeze
+    SUPPORTED_OPENAPI_VERSIONS = %w[3.0 3.1].freeze
 
     # The version of OpenAPI that will be used by default for
     # validation/construction
@@ -37,6 +39,10 @@ class Document
     #   The value of the info field on the OpenAPI document
     #   @see Node::Openapi#info
     #   @return [Node::Info]
+    # @!method jsonSchemaDialect
+    #   The value of the jsonSchemaDialect field on the OpenAPI document
+    #   @see Node::Openapi#json_schema_dialect
+    #   @return [String, nil]
     # @!method servers
     #   The value of the servers field on the OpenAPI document
     #   @see Node::Openapi#servers
@@ -74,15 +80,21 @@ class Document
     #   Iterate through the attributes of the root object
     # @!method keys
     #   Access keys of the root object
-    def_delegators :root, :openapi, :info, :servers, :paths, :components,
-                   :security, :tags, :external_docs, :extension, :[], :each,
-                   :keys
-
-    # @param [SourceInput] source_input
-    def initialize(source_input)
+    def_delegators :root, :openapi, :info, :json_schema_dialect, :servers,
+                   :paths, :components, :security, :tags, :external_docs,
+                   :extension, :[], :each, :keys
+
+    # @param [SourceInput]  source_input
+    # @param [Boolean]      emit_warnings   Whether to call Kernel.warn when
+    #                                       warnings are output, best set to
+    #                                       false when parsing specification
+    #                                       files you've not authored
+    def initialize(source_input, emit_warnings: true)
       @reference_registry = ReferenceRegistry.new
       @root_source = Source.new(source_input, self, reference_registry)
-      @warnings = []
+      @emit_warnings = emit_warnings
+      @build_warnings = []
+      @unsupported_schema_dialects = Set.new
       @openapi_version = determine_openapi_version(root_source.data["openapi"])
       @build_in_progress = false
       @built = false
@@ -152,15 +164,35 @@ def node_at(pointer, relative_to = nil)
       look_up_pointer(pointer, relative_to, root)
     end
 
+    # An array of any warnings enountered in the initialisation / validation
+    # of the document. Reflects warnings related to this gems ability to parse
+    # the document.
+    #
+    # @return [Array<String>]
+    def warnings
+      @warnings ||= begin
+        factory.errors # ensure factory has completed validation
+        @build_warnings.freeze
+      end
+    end
+
     # @return [String]
     def inspect
       %{#{self.class.name}(openapi_version: #{openapi_version}, } +
         %{root_source: #{root_source.inspect})}
     end
 
+    #  :nodoc:
+    def unsupported_schema_dialect(schema_dialect)
+      return if @build_warnings.frozen? || unsupported_schema_dialects.include?(schema_dialect)
+
+      unsupported_schema_dialects << schema_dialect
+      add_warning("Unsupported schema dialect (#{schema_dialect}), it may not parse or validate correctly.")
+    end
+
     private
 
-    attr_reader :reference_registry, :built, :build_in_progress
+    attr_reader :reference_registry, :built, :build_in_progress, :unsupported_schema_dialects, :build_warnings
 
     def look_up_pointer(pointer, relative_pointer, subject)
       merged_pointer = Source::Pointer.merge_pointers(relative_pointer,
@@ -169,7 +201,8 @@ def look_up_pointer(pointer, relative_pointer, subject)
     end
 
     def add_warning(text)
-      @warnings << text
+      warn("Warning: #{text} Disable these warnings by opening a document with emit_warnings: false.") if emit_warnings
+      @build_warnings << text
     end
 
     def build
@@ -179,29 +212,28 @@ def build
       context = NodeFactory::Context.root(root_source.data, root_source)
       @factory = NodeFactory::Openapi.new(context)
       reference_registry.freeze
-      @warnings.freeze
       @build_in_progress = false
       @built = true
     end
 
     def determine_openapi_version(version)
       minor_version = (version || "").split(".").first(2).join(".")
 
-      if SUPPORTED_OPENAPI_VERSIONS.include?(minor_version)
-        minor_version
-      elsif version
+      return OpenapiVersion.new(minor_version) if SUPPORTED_OPENAPI_VERSIONS.include?(minor_version)
+
+      if version
         add_warning(
           "Unsupported OpenAPI version (#{version}), treating as a " \
-          "#{DEFAULT_OPENAPI_VERSION} document"
+          "#{DEFAULT_OPENAPI_VERSION} document."
         )
-        DEFAULT_OPENAPI_VERSION
       else
         add_warning(
           "Unspecified OpenAPI version, treating as a " \
-          "#{DEFAULT_OPENAPI_VERSION} document"
+          "#{DEFAULT_OPENAPI_VERSION} document."
         )
-        DEFAULT_OPENAPI_VERSION
       end
+
+      OpenapiVersion.new(DEFAULT_OPENAPI_VERSION)
     end
 
     def factory
@@ -214,4 +246,5 @@ def reference_factories
       reference_registry.factories.reject { |f| f.context.source.root? }
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

lib/openapi3_parser/node/array.rb

@@ -40,7 +40,7 @@ def each(&)
       # @return [Boolean]
       def ==(other)
         other.instance_of?(self.class) &&
-          node_context.same_data_and_source?(other.node_context)
+          node_context.same_data_inputs?(other.node_context)
       end
 
       # Used to access a node relative to this node