scorpio 0.6.4 → 0.7.0

data/lib/scorpio/openapi/tag.rb

@@ -1,14 +1,30 @@
 module Scorpio
   module OpenAPI
     module Tag
+      include(Document::Descendent)
+
       # operations in the openapi document which have a tag with this tag's name
       # @return [Enumerable<Scorpio::OpenAPI::Operation>]
       def operations
-        unless jsi_root_node.is_a?(OpenAPI::Document)
-          raise("Tag#operations cannot be used on a Tag that is not inside an OpenAPI document")
+        return(@operations) if instance_variable_defined?(:@operations)
+        @operations = OperationsScope.new(each_operation)
+      end
+
+      # @yield [OpenAPI::Operation]
+      def each_operation(&block)
+        return(to_enum(__method__)) unless block
+
+        openapi_document.each_operation do |op|
+          yield(op) if op.tags.respond_to?(:to_ary) && op.tags.include?(name)
         end
+      end
+    end
 
-        jsi_root_node.operations.select { |op| op.tags.respond_to?(:to_ary) && op.tags.include?(name) }
+    module Tags
+      # a tag with the given name
+      # @return [OpenAPI::Tag, nil]
+      def named(name)
+        detect { |tag| tag.name == name }
       end
     end
   end

data/lib/scorpio/openapi/v2/dialect.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI::V2
+    VOCABULARY = JSI::Schema::Vocabulary.new(
+      elements: [
+        JSI::Schema::Elements::SELF[],
+
+        JSI::Schema::Elements::REF[exclusive: true],
+
+        JSI::Schema::Elements::MULTIPLE_OF[],
+
+        JSI::Schema::Elements::MAXIMUM_BOOLEAN_EXCLUSIVE[],
+
+        JSI::Schema::Elements::MINIMUM_BOOLEAN_EXCLUSIVE[],
+
+        JSI::Schema::Elements::MAX_LENGTH[],
+
+        JSI::Schema::Elements::MIN_LENGTH[],
+
+        JSI::Schema::Elements::PATTERN[],
+
+        # TODO this should not include additionalItems
+        JSI::Schema::Elements::ITEMS[],
+
+        JSI::Schema::Elements::MAX_ITEMS[],
+
+        JSI::Schema::Elements::MIN_ITEMS[],
+
+        JSI::Schema::Elements::UNIQUE_ITEMS[],
+
+        JSI::Schema::Elements::MAX_PROPERTIES[],
+
+        JSI::Schema::Elements::MIN_PROPERTIES[],
+
+        JSI::Schema::Elements::REQUIRED[],
+
+        # TODO this should not include patternProperties
+        JSI::Schema::Elements::PROPERTIES[],
+
+        JSI::Schema::Elements::ENUM[],
+
+        JSI::Schema::Elements::TYPE[],
+
+        JSI::Schema::Elements::ALL_OF[],
+
+        JSI::Schema::Elements::INFO_STRING[keyword: 'title'],
+        JSI::Schema::Elements::INFO_STRING[keyword: 'description'],
+
+        JSI::Schema::Elements::INFO_BOOL[keyword: 'readOnly'],
+
+        JSI::Schema::Elements::DEFAULT[],
+
+        JSI::Schema::Elements::FORMAT[],
+
+        JSI::Schema::Element.new(keyword: 'example') { }, # no actions
+      ],
+    )
+
+    # https://spec.openapis.org/oas/v2.0.html#schema-object
+    DIALECT = JSI::Schema::Dialect.new(
+      vocabularies: [VOCABULARY],
+      integer_disallows_0_fraction: true,
+    )
+  end
+end

data/lib/scorpio/openapi/v2.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI
+    module V2
+      autoload(:DIALECT, 'scorpio/openapi/v2/dialect')
+
+      describe_schema_ptrs = Set[
+        # this schema (Scorpio::OpenAPI::V2::Schema) describes schemas in an OpenAPI document.
+        JSI::Ptr['definitions', 'schema'],
+        # this schema describes a boolean schema, only allowed for 'additionalProperties'
+        JSI::Ptr['definitions', 'schema', 'properties', 'additionalProperties', 'anyOf', 1],
+      ].freeze
+
+      Document = JSI.new_schema_module(JSON.parse(Scorpio.root.join(
+        'documents/swagger.io/v2/schema.json'
+      ).read, freeze: true))
+
+      describe_schema_ptrs.each do |ptr|
+        (Document / ptr).describes_schema!(DIALECT)
+      end
+
+      # naming these is not strictly necessary, but is nice to have.
+      # generated: `puts Scorpio::OpenAPI::V2::Document.schema.definitions.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+
+
+      Info            = Document.definitions['info']
+      Contact          = Document.definitions['contact']
+      License           = Document.definitions['license']
+      Paths              = Document.definitions['paths']
+      Definitions         = Document.definitions['definitions']
+      ParameterDefinitions = Document.definitions['parameterDefinitions']
+      ResponseDefinitions = Document.definitions['responseDefinitions']
+      ExternalDocs       = Document.definitions['externalDocs']
+      Examples          = Document.definitions['examples']
+      MimeType         = Document.definitions['mimeType']
+      Operation       = Document.definitions['operation']
+      PathItem         = Document.definitions['pathItem']
+      Responses         = Document.definitions['responses']
+      ResponseValue      = Document.definitions['responseValue']
+      Response            = Document.definitions['response']
+      Headers              = Document.definitions['headers']
+      Header                = Document.definitions['header']
+      VendorExtension        = Document.definitions['vendorExtension']
+      BodyParameter           = Document.definitions['bodyParameter']
+      HeaderParameterSubSchema = Document.definitions['headerParameterSubSchema']
+      QueryParameterSubSchema   = Document.definitions['queryParameterSubSchema']
+      FormDataParameterSubSchema = Document.definitions['formDataParameterSubSchema']
+      PathParameterSubSchema    = Document.definitions['pathParameterSubSchema']
+      NonBodyParameter         = Document.definitions['nonBodyParameter']
+      Parameter               = Document.definitions['parameter']
+      Schema                 = Document.definitions['schema']
+      FileSchema            = Document.definitions['fileSchema']
+      PrimitivesItems       = Document.definitions['primitivesItems']
+      Security               = Document.definitions['security']
+      SecurityRequirement     = Document.definitions['securityRequirement']
+      Xml                      = Document.definitions['xml']
+      Tag                       = Document.definitions['tag']
+      SecurityDefinitions        = Document.definitions['securityDefinitions']
+      BasicAuthenticationSecurity = Document.definitions['basicAuthenticationSecurity']
+      ApiKeySecurity             = Document.definitions['apiKeySecurity']
+      OAuth2ImplicitSecurity    = Document.definitions['oauth2ImplicitSecurity']
+      OAuth2PasswordSecurity   = Document.definitions['oauth2PasswordSecurity']
+      OAuth2ApplicationSecurity = Document.definitions['oauth2ApplicationSecurity']
+      OAuth2AccessCodeSecurity = Document.definitions['oauth2AccessCodeSecurity']
+      OAuth2Scopes            = Document.definitions['oauth2Scopes']
+      MediaTypeList          = Document.definitions['mediaTypeList']
+      ParametersList         = Document.definitions['parametersList']
+      SchemesList             = Document.definitions['schemesList']
+      CollectionFormat         = Document.definitions['collectionFormat']
+      CollectionFormatWithMulti = Document.definitions['collectionFormatWithMulti']
+      Title                    = Document.definitions['title']
+      Description             = Document.definitions['description']
+      Default                = Document.definitions['default']
+      MultipleOf            = Document.definitions['multipleOf']
+      Maximum              = Document.definitions['maximum']
+      ExclusiveMaximum    = Document.definitions['exclusiveMaximum']
+      Minimum            = Document.definitions['minimum']
+      ExclusiveMinimum  = Document.definitions['exclusiveMinimum']
+      MaxLength        = Document.definitions['maxLength']
+      MinLength       = Document.definitions['minLength']
+      Pattern        = Document.definitions['pattern']
+      MaxItems      = Document.definitions['maxItems']
+      MinItems     = Document.definitions['minItems']
+      UniqueItems = Document.definitions['uniqueItems']
+      Enum         = Document.definitions['enum']
+      JsonReference = Document.definitions['jsonReference']
+
+      module Operation
+        include(OpenAPI::Operation::V2Methods)
+      end
+
+      # A document that defines or describes an API conforming to the OpenAPI Specification v2 (aka Swagger).
+      #
+      # The root document is known as the Swagger Object.
+      module Document
+        include(OpenAPI::Document::V2Methods)
+      end
+
+      module JsonReference
+        include(OpenAPI::Reference)
+      end
+
+      module Tag
+        include(OpenAPI::Tag)
+      end
+
+      Document.properties["tags"].include(OpenAPI::Tags)
+
+      module Paths
+        include(OpenAPI::Paths)
+      end
+
+      module PathItem
+        include(OpenAPI::PathItem)
+        include(OpenAPI::Reference)
+      end
+
+      module Response
+        include(OpenAPI::Response)
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/v3_0/dialect.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI::V3_0
+    VOCABULARY = JSI::Schema::Vocabulary.new(
+      elements: [
+        JSI::Schema::Elements::SELF[],
+
+        JSI::Schema::Elements::REF[exclusive: true],
+
+        JSI::Schema::Elements::MULTIPLE_OF[],
+
+        JSI::Schema::Elements::MAXIMUM_BOOLEAN_EXCLUSIVE[],
+
+        JSI::Schema::Elements::MINIMUM_BOOLEAN_EXCLUSIVE[],
+
+        JSI::Schema::Elements::MAX_LENGTH[],
+
+        JSI::Schema::Elements::MIN_LENGTH[],
+
+        JSI::Schema::Elements::PATTERN[],
+
+        JSI::Schema::Elements::MAX_ITEMS[],
+
+        JSI::Schema::Elements::MIN_ITEMS[],
+
+        JSI::Schema::Elements::UNIQUE_ITEMS[],
+
+        JSI::Schema::Elements::MAX_PROPERTIES[],
+
+        JSI::Schema::Elements::MIN_PROPERTIES[],
+
+        JSI::Schema::Elements::REQUIRED[],
+
+        JSI::Schema::Elements::ENUM[],
+
+        OpenAPI::SchemaElements::TYPE_NULLABLE,
+
+        JSI::Schema::Elements::ALL_OF[],
+        JSI::Schema::Elements::ONE_OF[],
+        JSI::Schema::Elements::ANY_OF[],
+
+        JSI::Schema::Elements::NOT[],
+
+        # TODO this should not include additionalItems
+        JSI::Schema::Elements::ITEMS[],
+
+        # TODO this should not include patternProperties
+        JSI::Schema::Elements::PROPERTIES[],
+
+        JSI::Schema::Elements::INFO_STRING[keyword: 'title'],
+        JSI::Schema::Elements::INFO_STRING[keyword: 'description'],
+
+        JSI::Schema::Elements::INFO_BOOL[keyword: 'readOnly'],
+        JSI::Schema::Elements::INFO_BOOL[keyword: 'writeOnly'],
+        JSI::Schema::Elements::INFO_BOOL[keyword: 'deprecated'],
+
+        JSI::Schema::Elements::DEFAULT[],
+
+        JSI::Schema::Elements::FORMAT[],
+
+        JSI::Schema::Element.new(keyword: 'externalDocs') { }, # no actions
+        JSI::Schema::Element.new(keyword: 'example') { }, # no actions
+
+        # TODO `discriminator`
+        # TODO `xml`
+      ],
+    )
+
+    # https://spec.openapis.org/oas/v3.0.4.html#schema-object
+    DIALECT = JSI::Schema::Dialect.new(
+      vocabularies: [VOCABULARY],
+      integer_disallows_0_fraction: true,
+    )
+  end
+end

data/lib/scorpio/openapi/v3_0.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI
+    module V3_0
+      autoload(:DIALECT, 'scorpio/openapi/v3_0/dialect')
+
+      describe_schema_ptrs = Set[
+        # this schema (Scorpio::OpenAPI::V3_0::Schema) describes schemas in an OpenAPI document.
+        JSI::Ptr['definitions', 'Schema'],
+        # /definitions/Schema does not allow $ref; this schema describes a schema with a $ref.
+        JSI::Ptr['definitions', 'SchemaReference'],
+        # this schema describes a boolean schema, only allowed for 'additionalProperties'
+        JSI::Ptr['definitions', 'Schema', 'properties', 'additionalProperties', 'oneOf', 2],
+      ].freeze
+
+      Document = JSI::JSONSchemaDraft04.new_schema_module(YAML.safe_load(Scorpio.root.join(
+        'documents/spec.openapis.org/oas/3.0/schema.yaml'
+      ).read))
+
+      describe_schema_ptrs.each do |ptr|
+        (Document / ptr).describes_schema!(DIALECT)
+      end
+
+      # naming these is not strictly necessary, but is nice to have.
+      # generated: `puts Scorpio::OpenAPI::V3_0::Document.schema.definitions.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+
+
+      Reference      = Document.definitions['Reference']
+      SchemaReference = Document.definitions['SchemaReference']
+      Info           = Document.definitions['Info']
+      Contact       = Document.definitions['Contact']
+      License      = Document.definitions['License']
+      Server        = Document.definitions['Server']
+      ServerVariable = Document.definitions['ServerVariable']
+      Components    = Document.definitions['Components']
+      Schema       = Document.definitions['Schema']
+      Discriminator = Document.definitions['Discriminator']
+      XML          = Document.definitions['XML']
+      Response    = Document.definitions['Response']
+      MediaType    = Document.definitions['MediaType']
+      Example       = Document.definitions['Example']
+      Header         = Document.definitions['Header']
+      Paths           = Document.definitions['Paths']
+      PathItem         = Document.definitions['PathItem']
+      Operation         = Document.definitions['Operation']
+      Responses          = Document.definitions['Responses']
+      SecurityRequirement = Document.definitions['SecurityRequirement']
+      Tag                  = Document.definitions['Tag']
+      ExternalDocumentation = Document.definitions['ExternalDocumentation']
+      Parameter           = Document.definitions['Parameter']
+      PathParameter      = Document.definitions['PathParameter']
+      QueryParameter      = Document.definitions['QueryParameter']
+      HeaderParameter      = Document.definitions['HeaderParameter']
+      CookieParameter       = Document.definitions['CookieParameter']
+      RequestBody            = Document.definitions['RequestBody']
+      SecurityScheme          = Document.definitions['SecurityScheme']
+      APIKeySecurityScheme     = Document.definitions['APIKeySecurityScheme']
+      HTTPSecurityScheme        = Document.definitions['HTTPSecurityScheme']
+      OAuth2SecurityScheme       = Document.definitions['OAuth2SecurityScheme']
+      OpenIdConnectSecurityScheme = Document.definitions['OpenIdConnectSecurityScheme']
+      OAuthFlows                 = Document.definitions['OAuthFlows']
+      ImplicitOAuthFlow         = Document.definitions['ImplicitOAuthFlow']
+      PasswordOAuthFlow        = Document.definitions['PasswordOAuthFlow']
+      ClientCredentialsFlow     = Document.definitions['ClientCredentialsFlow']
+      AuthorizationCodeOAuthFlow = Document.definitions['AuthorizationCodeOAuthFlow']
+      Link                      = Document.definitions['Link']
+      Callback                 = Document.definitions['Callback']
+      Encoding                = Document.definitions['Encoding']
+
+      module Response
+        include(OpenAPI::Response)
+      end
+
+      # Describes a single API operation on a path.
+      #
+      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
+      module Operation
+        include(OpenAPI::Operation::V3Methods)
+      end
+
+      # A document that defines or describes an API conforming to the OpenAPI Specification v3.0.
+      #
+      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#oasObject
+      module Document
+        include(OpenAPI::Document::V3Methods)
+
+        # @return [#to_hash] /components/schemas, if present, or an empty hash
+        def components_schemas
+          return JSI::Util::EMPTY_HASH unless key?('components') && components.respond_to?(:to_hash)
+          return JSI::Util::EMPTY_HASH unless components.key?('schemas') && components.schemas.respond_to?(:to_hash)
+          components.schemas
+        end
+      end
+
+      module Reference
+        include(OpenAPI::Reference)
+      end
+
+      module Tag
+        include(OpenAPI::Tag)
+      end
+
+      Document.properties["tags"].include(OpenAPI::Tags)
+
+      # An object representing a Server.
+      #
+      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
+      module Server
+        include(OpenAPI::Server)
+      end
+
+      module Paths
+        include(OpenAPI::Paths)
+      end
+
+      module PathItem
+        include(OpenAPI::PathItem)
+        include(OpenAPI::Reference)
+      end
+
+      module SecurityScheme
+        include(OpenAPI::SecurityScheme)
+      end
+    end
+
+    # @deprecated after v0.7
+    V3 = V3_0
+  end
+end

data/lib/scorpio/openapi/v3_1.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI
+    module V3_1
+      class << self
+        attr_accessor(:document_schema_modules_by_dialect_id)
+      end
+
+      self.document_schema_modules_by_dialect_id = {}
+
+      def self.document_name_subschemas(document_schema_module, namespace)
+        namespace.const_set(:Info,         document_schema_module.defs['info'])
+        namespace.const_set(:Contact,       document_schema_module.defs['contact'])
+        namespace.const_set(:License,        document_schema_module.defs['license'])
+        namespace.const_set(:Server,          document_schema_module.defs['server'])
+        namespace.const_set(:ServerVariable,   document_schema_module.defs['server-variable'])
+        namespace.const_set(:Components,        document_schema_module.defs['components'])
+        namespace.const_set(:Paths,              document_schema_module.defs['paths'])
+        namespace.const_set(:PathItem,            document_schema_module.defs['path-item'])
+        namespace.const_set(:Operation,            document_schema_module.defs['operation'])
+        namespace.const_set(:ExternalDocumentation, document_schema_module.defs['external-documentation'])
+        namespace.const_set(:Parameter,            document_schema_module.defs['parameter'])
+        namespace.const_set(:RequestBody,         document_schema_module.defs['request-body'])
+        namespace.const_set(:Content,            document_schema_module.defs['content'])
+        namespace.const_set(:MediaType,         document_schema_module.defs['media-type'])
+        namespace.const_set(:Encoding,         document_schema_module.defs['encoding'])
+        namespace.const_set(:Responses,       document_schema_module.defs['responses'])
+        namespace.const_set(:Response,       document_schema_module.defs['response'])
+        namespace.const_set(:Callbacks,     document_schema_module.defs['callbacks'])
+        namespace.const_set(:Example,      document_schema_module.defs['example'])
+        namespace.const_set(:Link,         document_schema_module.defs['link'])
+        namespace.const_set(:Header,        document_schema_module.defs['header'])
+        namespace.const_set(:Tag,            document_schema_module.defs['tag'])
+        namespace.const_set(:Reference,       document_schema_module.defs['reference'])
+        namespace.const_set(:Schema,           document_schema_module.defs['schema'])
+        namespace.const_set(:SecurityScheme,    document_schema_module.defs['security-scheme'])
+        namespace.const_set(:OAuthFlows,         document_schema_module.defs['oauth-flows'])
+        namespace.const_set(:SecurityRequirement, document_schema_module.defs['security-requirement'])
+        namespace.const_set(:Examples,            document_schema_module.defs['examples'])
+        namespace.const_set(:MapOfStrings,         document_schema_module.defs['map-of-strings'])
+        namespace.const_set(:ExplodeForForm,        document_schema_module.defs['explode-for-form'])
+        namespace.const_set(:SpecificationExtension, document_schema_module.defs['specification-extensions'].patternProperties["^x-"])
+      end
+
+      def self.set_up_document_schema_module(document_schema_module)
+        document_schema_module.include(OpenAPI::V3_1::Document)
+        document_schema_module.defs['response'].include(OpenAPI::Response)
+        document_schema_module.defs['operation'].include(OpenAPI::Operation::V3Methods)
+        document_schema_module.defs['reference'].include(OpenAPI::Reference)
+        document_schema_module.defs['tag'].include(OpenAPI::Tag)
+        document_schema_module.defs['server'].include(OpenAPI::Server)
+        document_schema_module.defs['paths'].include(OpenAPI::Paths)
+        document_schema_module.defs['path-item'].include(OpenAPI::PathItem)
+        document_schema_module.defs['path-item'].include(OpenAPI::Reference)
+        document_schema_module.defs['security-scheme'].include(OpenAPI::SecurityScheme)
+
+        document_schema_module
+      end
+
+      # This is pretty much: `Unscoped::Document.with_dynamic_scope_from(JSI.registry.find(dialect_id))`
+      # plus {.set_up_document_schema_module}.
+      #
+      # However, this also supports a dialect whose meta-schema isn't aware of dynamic scope and doesn't
+      # have a `$dynamicAnchor: "meta"`, e.g. `jsonSchemaDialect: "http://json-schema.org/draft-07/schema"`.
+      #
+      # A schema like {Ext::ExtDocument} exists to `$ref` to {Unscoped::Document} with anchor `meta`
+      # in dynamic scope, with the `$dynamicAnchor: "meta"` schema `$ref`ing to {Ext::MetaSchema}.
+      # This method obviates the need for such a schema, directly applying dynamic scope.
+      def self.document_schema_module_by_dialect_id(dialect_id)
+        dialect_uri = JSI::Util.uri(dialect_id)
+        document_schema_modules_by_dialect_id[dialect_uri] ||= begin
+          metaschema = JSI.registry.find(dialect_uri)
+          dynamic_anchor_map = metaschema.jsi_next_schema_dynamic_anchor_map
+          unless dynamic_anchor_map.key?('meta')
+            # hax: pretend that the identified meta-schema has `$dynamicAnchor: "meta"`
+            # this enables e.g. `jsonSchemaDialect: "http://json-schema.org/draft-07/schema"` to work
+            # this is non-API JSI internals.
+            dynamic_anchor_map = dynamic_anchor_map.merge({
+              'meta' => [metaschema, [].freeze].freeze,
+            }).freeze
+          end
+          document_schema = Unscoped::Document.schema.jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
+          set_up_document_schema_module(document_schema.jsi_schema_module)
+        end
+      end
+
+      # Instantiates `instance` v3.1 OAD with schemas of the dialect indicated by `jsonSchemaDialect`
+      # @param instance [#to_hash]
+      # @return [JSI::Base + Scorpio::OpenAPI::V3_1::Document]
+      def self.new_document(instance, **new_param)
+        #jsonSchemaDialect = Scorpio::OpenAPI::V3_1::Unscoped::Document.new_jsi(instance, **new_param).jsonSchemaDialect(use_default: true)
+        jsonSchemaDialect = instance.fetch('jsonSchemaDialect') { Unscoped::Document.properties['jsonSchemaDialect'].default }
+        document_schema_module = document_schema_module_by_dialect_id(jsonSchemaDialect)
+
+        document_schema_module.new_jsi(instance, **new_param)
+      end
+
+
+      module Document
+        include(OpenAPI::Document::V3Methods)
+      end
+
+
+      # namespace
+      module Unscoped
+      end
+
+      Unscoped::Document = JSI.new_schema_module(
+        YAML.safe_load(Scorpio.root.join('documents/spec.openapis.org/oas/3.1/schema.yaml').read),
+      )
+      # Schema module: describes an OpenAPI document, but not normally instantiated.
+      #
+      # This document schema has no dynamic scope pointing `$dynamicAnchor: "meta"` to a real
+      # meta-schema. Schemas in the document described by this are just `type: [object, boolean]`,
+      # have no dialect, and are not usable schemas.
+      #
+      # - $id: `https://spec.openapis.org/oas/3.1/schema/2025-11-23`
+      module Unscoped::Document
+      end
+
+
+      # "Ext" is abbreviation for the "OpenAPI extension schema dialect" that extends JSON Schema draft 2020-12
+      # and defines keywords: `discriminator`, `example`, `externalDocs`, `xml`.
+      # This module is a namespace for that.
+      module Ext
+      end
+
+      # vocabulary for implementation of keywords: `discriminator`, `example`, `externalDocs`, `xml`
+      Ext::VOCAB = JSI::Schema::Vocabulary.new(
+        id: "https://spec.openapis.org/oas/3.1/vocab/base",
+        elements: [
+          # TODO:
+          # - discriminator
+          # - example
+          # - externalDocs
+          # - xml
+        ],
+      )
+      JSI.registry.register_vocabulary(Ext::VOCAB)
+
+
+      Ext::ExtDocument = JSI.new_schema_module(
+        YAML.safe_load(Scorpio.root.join('documents/spec.openapis.org/oas/3.1/schema-base.yaml').read),
+      )
+      # Schema module: Describes an OAD with schemas of the OpenAPI extension schema dialect.
+      # This exists to dynamically scope the `meta` anchor
+      # for {Unscoped::Document} `<https://spec.openapis.org/oas/3.1/schema/2025-11-23>`
+      # to {Ext::MetaSchema} `<https://spec.openapis.org/oas/3.1/dialect/2024-11-10>`
+      # via `<#/$defs/schema>` {Ext::ExtDocument::Schema}.
+      #
+      # - $id: `https://spec.openapis.org/oas/3.1/schema-base/2025-11-23`
+      # - $ref: {Ext::Document} `<https://spec.openapis.org/oas/3.1/schema/2025-11-23>`
+      # - $dynamicAnchor: `meta` in `/$defs/schema` ({Ext::ExtDocument::Schema})
+      # - properties: jsonSchemaDialect const {Ext::MetaSchema} `<https://spec.openapis.org/oas/3.1/dialect/2024-11-10>`
+      module Ext::ExtDocument
+      end
+
+      Ext::ExtDocument::Schema = Ext::ExtDocument["$defs"]["schema"]
+      # Schema module: Describes schemas in an Ext::Document
+      #
+      # - $dynamicAnchor: `meta`
+      # - $ref: {Ext::MetaSchema} `<https://spec.openapis.org/oas/3.1/dialect/2024-11-10>`
+      # - properties: $schema const {Ext::MetaSchema} `<https://spec.openapis.org/oas/3.1/dialect/2024-11-10>`
+      module Ext::ExtDocument::Schema
+      end
+
+
+      # Some Ext schemas are used with dynamic scope from {Ext::ExtDocument}; Ext::Unscoped namespace
+      # contains those schemas without that dynamic scope. These are not normally instantiated.
+      module Ext::Unscoped
+      end
+
+      Ext::Unscoped::VocabSchema = JSI.new_schema_module(
+        YAML.safe_load(Scorpio.root.join('documents/spec.openapis.org/oas/3.1/meta/base.schema.yaml').read),
+      )
+      module Ext::Unscoped::VocabSchema
+      end
+
+      Ext::VocabSchema = Ext::Unscoped::VocabSchema.with_dynamic_scope_from(Ext::ExtDocument)
+      # Schema module: vocabulary schema for {Ext::VOCAB}
+      #
+      # - $id: `https://spec.openapis.org/oas/3.1/meta/2024-11-10`
+      # - $dynamicAnchor: `meta` (unused)
+      # - properties (schema keywords) discriminator, example, externalDocs, xml
+      module Ext::VocabSchema
+      end
+
+      Ext::Unscoped::MetaSchema = JSI.new_schema_module(
+        YAML.safe_load(Scorpio.root.join('documents/spec.openapis.org/oas/3.1/dialect/base.schema.yaml').read),
+      )
+      module Ext::Unscoped::MetaSchema
+      end
+
+      Ext::MetaSchema = Ext::Unscoped::MetaSchema.with_dynamic_scope_from(Ext::ExtDocument)
+      Ext::MetaSchema.describes_schema!
+      # Schema module: Meta-schema describing schemas within an OpenAPI document with the OpenAPI extension schema dialect
+      #
+      # - $id: `https://spec.openapis.org/oas/3.1/dialect/2024-11-10`
+      # - $dynamicAnchor: `meta` (overridden by dynamic scope with `meta` → {Ext::ExtDocument::Schema})
+      # - $vocabulary:
+      #   - The draft/2020-12 vocabularies - core, applicator, validation, etc (required: true)
+      #   - {Ext::VOCAB} `<https://spec.openapis.org/oas/3.1/vocab/base>` (required: false)
+      # - allOf:
+      #   - $ref: {Ext::JSONSchemaDraft202012} `<https://json-schema.org/draft/2020-12/schema>`
+      #   - $ref: {Ext::VocabSchema} `<https://spec.openapis.org/oas/3.1/meta/2024-11-10>`
+      module Ext::MetaSchema
+      end
+
+      Ext::Document = Unscoped::Document.with_dynamic_scope_from(Ext::ExtDocument)
+      # Schema module: Describes an OpenAPI document containing schemas of the Ext dialect.
+      # This is {Unscoped::Document}, with dynamic scope pointing `$dynamicAnchor: "meta"` to {Ext::ExtDocument::Schema}.
+      module Ext::Document
+      end
+
+      set_up_document_schema_module(Ext::Document)
+      document_name_subschemas(Ext::Document, Ext)
+      # note: without this mapping set, document_schema_module_by_dialect_id(Ext::MetaSchema.schema_uri)
+      # would be   Unscoped::Document.with_dynamic_scope_from(Ext::Unscoped::MetaSchema)
+      # instead of Unscoped::Document.with_dynamic_scope_from(Ext::ExtDocument)
+      # schemas in OADs with this jsonSchemaDialect would have the right dialect, but
+      # Ext::ExtDocument does also validate OAD jsonSchemaDialect and schema $schema properties.
+      document_schema_modules_by_dialect_id[Ext::MetaSchema.schema_uri] = Ext::ExtDocument
+
+      Ext::JSONSchemaDraft202012 = JSI::JSONSchemaDraft202012.with_dynamic_scope_from(Ext::ExtDocument)
+      JSI::JSONSchemaDraft202012.name_vocab_schemas(Ext::JSONSchemaDraft202012)
+      # JSI::JSONSchemaDraft202012, with dynamic scope pointing `$dynamicAnchor: "meta"` to {Ext::ExtDocument::Schema}.
+      module Ext::JSONSchemaDraft202012
+      end
+
+
+      module JSONSchemaDraft202012
+      end
+
+      JSONSchemaDraft202012::Document = Unscoped::Document.with_dynamic_scope_from(JSI::JSONSchemaDraft202012)
+      # Describes an OAD with `jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"`
+      module JSONSchemaDraft202012::Document
+      end
+
+      document_name_subschemas(JSONSchemaDraft202012::Document, JSONSchemaDraft202012)
+    end
+  end
+end