versponse 0.1.0 → 0.2.0

data/lib/versponse/properties/field.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # A scalar value
+    #
+    # @api private
+    class Field < Base
+      # @return [Boolean] true: nil values can be replaced
+      def self.default_option? = true
+
+      # @param type [Symbol, String, Array<Symbol, String>] a built-in type ({FieldType::BUILT_IN}; "object" is a free-form map whose
+      #   value passes through), a custom one from config.custom_field_types, or a union of two or more built-in types
+      # @param options [Hash] see {Base#initialize}; they win over the custom type's schema options
+      # @raise [Versponse::DefinitionError] for an unknown type or an invalid union
+      def initialize(type:, **options)
+        super(**options)
+        @type, type_options = FieldType.resolve(type, key)
+        @schema_options = type_options.merge(schema_options)
+        check_default!
+      end
+
+      # @param context [Versponse::SchemaContext, nil] schema generation context
+      # @return [Hash] JSON Schema of the field; a type union is a type array, or an anyOf of single types in
+      #   OpenAPI 3.0 documents, with keywords on the outer node and nullable on each branch. nullable: never
+      #   changes a declared any_of, so a nullable field's any_of must list {"type" => "null"} itself.
+      def schema(context)
+        options = (nullable? && schema_options["enum"]) ? schema_options.merge("enum" => schema_options["enum"] | [nil]) : schema_options
+        return nullable_type({"type" => @type}.merge(options), context) unless openapi30_union?(@type, context)
+
+        FieldType.openapi30_union(@type, options, nullable: nullable?)
+      end
+
+      # @param version [String] unused by scalars
+      # @param formatters [Hash{String => #call}] formatters by JSON Schema format, for the compiling class and version
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Value] compiled step with the formatter of its format
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        value_step(formatter: formatters[schema_options["format"]], policies:)
+      end
+    end
+  end
+end

data/lib/versponse/properties/item_one_of.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # The unnamed one_of inside a collection block: types each item of the collection
+    #
+    # @api private
+    class ItemOneOf < OneOf
+      # @return [Boolean] false: the collection's context: covers the items
+      def self.context_option? = false
+
+      # @param _block [Proc] unused
+      # @raise [Versponse::DefinitionError] always, the collection owns the value source
+      def source=(_block)
+        raise DefinitionError, "#{key}: source belongs to the collection, declare it outside the unnamed one_of"
+      end
+    end
+  end
+end

data/lib/versponse/properties/object.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # An inline object; its source is read by name or with map: ("." for the same object)
+    #
+    # @api private
+    class Object < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[properties required].freeze
+
+      # @return [Boolean] true: the subtree can render with its own context
+      def self.context_option? = true
+
+      include Container
+
+      # @param context [Versponse::SchemaContext] schema generation context
+      # @return [Hash] object schema
+      def schema(context)
+        nullable_type(inline_schema(context).merge(schema_options), context)
+      end
+
+      # @param version [String] requested version name
+      # @param formatters [Hash{String => #call}] formatters by JSON Schema format, for the compiling class and version
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Nested] compiled step with an inline child plan
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        Steps::Nested.new(key:, extractor:, condition:, plan: inline_plan(version, formatters, policies), collection: false, context_override:)
+      end
+    end
+  end
+end

data/lib/versponse/properties/one_of.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # A polymorphic value whose variants are other response classes, picked with match: (===)
+    #
+    # @api private
+    class OneOf < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[oneOf anyOf discriminator].freeze
+
+      # @return [Boolean] true: the subtree can render with its own context
+      def self.context_option? = true
+
+      # One variant: response class, matcher, view and context override
+      Variant = Data.define(:from, :match, :view, :context_override)
+
+      # @param discriminator [String, Symbol, nil] OpenAPI discriminator property
+      # @param expandable [Boolean] render variants collapsed unless expanded
+      # @param options [Hash] see {Base#initialize}
+      def initialize(discriminator: nil, expandable: false, **options)
+        super(**options)
+        @discriminator = discriminator&.to_s
+        @expandable = expandable
+        @variants = []
+      end
+
+      # @param _property [Versponse::Properties::Base] unused
+      # @raise [Versponse::DefinitionError] always, variants are declared with reference
+      def add(_property)
+        raise DefinitionError, "#{key}: declare one_of variants with reference from:, match:"
+      end
+
+      # @param from [Class] Versponse response class
+      # @param match [Class, Proc, Array<Class, Proc>] compared with === against the value
+      # @param view [Symbol] view of from
+      # @param context [Hash, #call, nil] the variant's context: (a callable gets the matched value)
+      # @return [void]
+      # @raise [Versponse::DefinitionError] without match: or with a non-Versponse class
+      def add_variant(from:, match:, view: :default, context: nil)
+        raise DefinitionError, "#{key}: a one_of variant needs match:" if match.nil?
+        raise DefinitionError, "#{key}: one_of variants must be Versponse response classes" unless References.versponse?(from)
+
+        @variants << Variant.new(from:, match:, view: view.to_sym, context_override: ContextOverride.build(context, key:))
+      end
+
+      # @return [Boolean] true when at least one variant is declared
+      def variants?
+        !@variants.empty?
+      end
+
+      # @return [Boolean] true when variants render collapsed unless expanded
+      def expandable?
+        @expandable
+      end
+
+      # @param context [Versponse::SchemaContext] schema generation context
+      # @return [Hash] oneOf schema (anyOf of full and collapsed forms when expandable); the discriminator,
+      #   with a mapping built from each variant's const, is left out of validation schemas and of expandable
+      #   one_of schemas (a collapsed payload carries the same value as the full form, so a mapping would
+      #   send it to the full schema)
+      #   A nullable one_of with a documented discriminator keeps null outside the discriminated oneOf, which
+      #   would otherwise reject it.
+      # @raise [Versponse::DefinitionError] when a variant lacks the discriminator const or two variants share a value
+      def schema(context)
+        schemas = @variants.flat_map { |variant| variant_schemas(variant, context) }
+        keyword = expandable? ? "anyOf" : "oneOf"
+        schema = if @discriminator && !expandable? && !context.validation?
+          discriminator = {"propertyName" => @discriminator, "mapping" => discriminator_mapping(context.version)}
+          nullable_ref({keyword => schemas, "discriminator" => discriminator}, context)
+        else
+          nullable_choice(keyword, schemas, context)
+        end
+        SchemaMerge.call(schema, schema_options)
+      end
+
+      # @param version [String] canonical version name
+      # @return [Versponse::VariantDispatcher] matching to the variants' full plans
+      def dispatcher(version)
+        variants = @variants.map { |variant| [Array(variant.match).freeze, with_context(variant, References.lazy_plan(variant.from, version:, view: variant.view, key:))] }
+        VariantDispatcher.new(variants, nullable: nullable?)
+      end
+
+      # @param version [String] canonical version name
+      # @return [Versponse::VariantDispatcher] matching to the variants' collapsed plans (full plans when a variant's collapse_if is false)
+      # @raise [Versponse::DefinitionError] when a variant class has no identifier
+      def collapsed_dispatcher(version)
+        variants = @variants.map { |variant| [Array(variant.match).freeze, with_context(variant, collapsed_variant_plan(variant, version))] }
+        VariantDispatcher.new(variants, nullable: nullable?)
+      end
+
+      # @param version [String] canonical version name
+      # @param formatters [Hash{String => #call}] unused; variant classes compile with their own
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::OneOf] compiled step
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        collapsed_dispatcher = (collapsed_dispatcher(version) if expandable?)
+        Steps::OneOf.new(key:, extractor:, condition:, dispatcher: dispatcher(version), collapsed_dispatcher:, context_override:)
+      end
+
+      # @param version [String] canonical version name
+      # @param prefix [Array<String>] output keys leading here
+      # @param stack [Array<Array(Class, Symbol)>] classes and views being walked
+      # @return [Array<Array(Array<String>, Array<Class>)>] this path with every variant's class when expandable,
+      #   plus every variant's entries
+      def expandable_entries(version:, prefix:, stack:)
+        path = prefix + [key]
+        own = expandable? ? [[path, @variants.map(&:from).uniq]] : []
+        own + @variants.flat_map { |variant| References.nested_entries(variant.from, view: variant.view, version:, prefix: path, stack:) }
+      end
+
+      # @return [Boolean] true when expandable
+      def expandable_path?
+        expandable?
+      end
+
+      # @param version [String] canonical version name
+      # @return [Array<Versponse::Properties::Base>] properties of every variant's view
+      def path_children(version)
+        @variants.flat_map { |variant| variant.from.versponse.resolve(version).properties_for(variant.view) }
+      end
+
+      # @return [Array<Array(Class, Symbol, String)>] every variant's class and view
+      def reference_targets
+        @variants.filter_map { |variant| [variant.from, variant.view, key] if References.versponse?(variant.from) }
+      end
+
+      private
+
+      def with_context(variant, plan)
+        variant.context_override ? ContextPlan.new(plan, variant.context_override) : plan
+      end
+
+      def variant_schemas(variant, context)
+        full = References.schema(variant.from, view: variant.view, property: nil, context:, key:)
+        expandable? ? [full, collapsed_variant_schema(variant, context)] : [full]
+      end
+
+      def collapsed_variant_schema(variant, context)
+        References.ensure_identifier!(variant.from, context.version)
+        return References.schema(variant.from, view: :collapsed, property: nil, context:) unless @discriminator
+
+        schema = variant.from.versponse.object_schema(version: context.version, view: :collapsed, context:)
+        discriminator = {@discriminator => discriminator_property(variant, context.version).schema(context)}
+        schema.merge("required" => [@discriminator, *schema["required"]], "properties" => discriminator.merge(schema["properties"]))
+      end
+
+      # Decides per value: an item one_of lets each item pick its own variant and shape
+      def collapsed_variant_plan(variant, version)
+        plan = References.collapsed_plan(variant.from, version)
+        plan = DiscriminatedPlan.new(plan, key: @discriminator, value: discriminator_property(variant, version).value) if @discriminator
+        collapse_if = References.collapse_if(variant.from, version)
+        return plan unless collapse_if
+
+        CollapseIfPlan.new(collapse_if, collapsed: plan, full: LazyPlan.new(variant.from, version:, view: variant.view))
+      end
+
+      def discriminator_mapping(version)
+        @variants.each_with_object({}) do |variant, mapping|
+          value = discriminator_property(variant, version).value.to_s
+          raise DefinitionError, "#{key}: two variants share the discriminator value #{value.inspect}" if mapping.key?(value)
+
+          mapping[value] = variant.from.to_ref(view: variant.view)
+        end
+      end
+
+      def discriminator_property(variant, version)
+        property = variant.from.versponse.resolve(version).properties_for(variant.view).find { |candidate| candidate.key == @discriminator }
+        raise DefinitionError, "#{key}: #{variant.from.name} has no const #{@discriminator} for the discriminator" if property.nil?
+        raise DefinitionError, "#{key}: #{variant.from.name}'s #{@discriminator} must be a const for the discriminator" unless property.is_a?(Const)
+
+        property
+      end
+    end
+  end
+end

data/lib/versponse/properties/reference.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # Another response class rendered in place, or a non-Versponse schema whose value passes through.
+    # With property:, a Versponse class's property is reused as if it were declared here.
+    #
+    # @api private
+    class Reference < Base
+      # @return [Boolean] true: the subtree can render with its own context
+      def self.context_option? = true
+
+      # @param from [Class] class implementing the reference protocol
+      # @param view [Symbol] view of from
+      # @param property [Symbol, nil] reuse one property of from instead of the whole class
+      # @param expandable [Boolean] render collapsed unless expanded
+      # @param options [Hash] see {Base#initialize}
+      # @raise [Versponse::DefinitionError] for an invalid from:, nullable: with a versponse property:,
+      #   expandable: on a foreign class or with property:, or context: with a non-Versponse class
+      def initialize(from:, view: :default, property: nil, expandable: false, **options)
+        super(**options)
+        raise DefinitionError, "#{key}: from: must respond to to_ref and to_validation_schema" unless from.respond_to?(:to_ref) && from.respond_to?(:to_validation_schema)
+
+        @from = from
+        @view = view.to_sym
+        @property = property&.to_s
+        @expandable = expandable
+        raise DefinitionError, "#{key}: nullable comes from the referenced property" if versponse_property? && nullable?
+        raise DefinitionError, "#{key}: expandable: needs a Versponse class without property:" if expandable && (!References.versponse?(from) || @property)
+        raise DefinitionError, "#{key}: context: needs a Versponse class to render with it" if context_override && !References.versponse?(@from)
+      end
+
+      # @return [Boolean] true when the reference renders collapsed unless expanded
+      def expandable?
+        @expandable
+      end
+
+      # @param context [Versponse::SchemaContext] schema generation context
+      # @return [Hash] $ref or inlined schema (anyOf full/collapsed when expandable); keywords sit on the outer node,
+      #   beside an allOf around a bare $ref in OpenAPI 3.0 documents, which ignore $ref siblings
+      # @raise [Versponse::DefinitionError] when a property: does not exist
+      def schema(context)
+        return with_options(referenced_property_schema(context), context) if versponse_property?
+
+        check_foreign_property!(context.version) if @property
+        return SchemaMerge.call(nullable_choice("anyOf", References.expandable_schemas(@from, view: @view, context:, key:), context), schema_options) if expandable?
+
+        with_options(nullable_ref(References.schema(@from, view: @view, property: @property, context:, key:), context), context)
+      end
+
+      # @param version [String] canonical version name
+      # @param formatters [Hash{String => #call}] formatters of the compiling class, used by a property: reference;
+      #   a nested class compiles with its own
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Nested, Versponse::Steps::Value, #call] compiled step
+      # @raise [Versponse::DefinitionError] when a versponse property: does not exist
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        return referenced_property(version).step(version:, formatters:, policies:) if versponse_property?
+        return value_step unless References.versponse?(@from)
+
+        collapsed_plan = (References.collapsed_plan(@from, version) if expandable?)
+        collapse_if = (References.collapse_if(@from, version) if expandable?)
+        Steps::Nested.new(key:, extractor:, condition:, plan: References.lazy_plan(@from, version:, view: @view, key:), collapsed_plan:, collapse_if:, collection: false, context_override:)
+      end
+
+      # @param version [String] canonical version name
+      # @param prefix [Array<String>] output keys leading here
+      # @param stack [Array<Array(Class, Symbol)>] classes and views being walked
+      # @return [Array<Array(Array<String>, Array<Class>)>] this path with from: when expandable, plus the
+      #   referenced class's entries
+      def expandable_entries(version:, prefix:, stack:)
+        return referenced_property(version).expandable_entries(version:, prefix:, stack:) if versponse_property?
+
+        path = prefix + [key]
+        (expandable? ? [[path, [@from]]] : []) + References.nested_entries(@from, view: @view, version:, prefix: path, stack:)
+      end
+
+      # @return [Boolean] true when expandable
+      def expandable_path?
+        expandable?
+      end
+
+      # @param version [String] canonical version name
+      # @return [Array<Versponse::Properties::Base>] properties of the referenced class's view
+      def path_children(version)
+        References.versponse?(@from) ? @from.versponse.resolve(version).properties_for(@view) : []
+      end
+
+      # @param version [String] canonical version name
+      # @return [Versponse::Properties::Base] the reused copy for a versponse property:, otherwise self
+      def path_target(version)
+        versponse_property? ? referenced_property(version) : self
+      end
+
+      # @return [Array<Array(Class, Symbol, String)>] the referenced Versponse class and view (none for property:)
+      def reference_targets
+        (References.versponse?(@from) && @property.nil?) ? [[@from, @view, key]] : []
+      end
+
+      private
+
+      def versponse_property?
+        !@property.nil? && References.versponse?(@from)
+      end
+
+      def referenced_property(version)
+        original = @from.versponse.resolve(version).properties_for(@view).find { |property| property.key == @property } ||
+          raise(DefinitionError, "#{key}: property #{@property} not found in #{@from.name} #{version}/#{@view}")
+        original.renamed(name:, map:, block:, condition:, context_override:)
+      end
+
+      # OpenAPI 3.0 ignores keywords next to a $ref, so a bare $ref with keywords is wrapped in allOf
+      def with_options(schema, context)
+        schema = {"allOf" => [schema]} if schema.key?("$ref") && schema_options.any? && nullable_keyword?(context)
+        SchemaMerge.call(schema, schema_options)
+      end
+
+      # A foreign class (a verquest request) answers nil for a property it doesn't have
+      def check_foreign_property!(version)
+        return unless @from.to_validation_schema(version:, property: @property).nil?
+
+        raise DefinitionError, "#{key}: property #{@property} not found in #{@from.name} #{version}"
+      end
+
+      def referenced_property_schema(context)
+        copy = referenced_property(context.version)
+        return {"$ref" => @from.to_ref(view: @view, property: @property)} unless context.validation?
+
+        copy.schema(context)
+      end
+    end
+  end
+end

data/lib/versponse/references.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Schemas of referenced classes: Versponse classes, or any class implementing the reference
+  # protocol (to_ref(property:) and to_validation_schema(version:, property:)), such as verquest requests.
+  # A foreign class that references back to the class being generated (A -> verquest -> A) re-enters
+  # A's schema cache and raises ThreadError; such cross-gem cycles are not supported.
+  #
+  # @api private
+  module References
+    # @param klass [Object] referenced class
+    # @return [Boolean] true for Versponse response classes
+    def self.versponse?(klass)
+      klass.is_a?(Class) && klass < Base
+    end
+
+    # Checks a referenced Versponse class serves the version and view, so a definition mistake raises
+    # DefinitionError wherever the reference compiles (serialize, schemas, eager_load!, documents)
+    #
+    # @param klass [Class] referenced class (anything but a Versponse class passes)
+    # @param version [String] canonical version name
+    # @param view [Symbol] referenced view
+    # @param key [String] referencing property, for the message
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the class declares nothing at or before the version, or lacks the view
+    # @raise [Versponse::VersionNotFoundError] when its supported_versions leave the version out (a runtime answer)
+    def self.check_target!(klass, version:, view:, key:)
+      return unless versponse?(klass)
+
+      definition = target_version(klass, version, key)
+      return if definition.view_names.include?(view.to_sym)
+
+      raise DefinitionError, "#{key}: view #{view} not found in #{klass.name || "AnonymousResponse"} #{version}"
+    end
+
+    def self.target_version(klass, version, key)
+      klass.versponse.resolve(version)
+    rescue VersionNotFoundError
+      raise if Versponse.configuration.version_resolver.call(Registry.canonical(version), klass.versponse.versions.sorted_names)
+
+      raise DefinitionError, "#{key}: #{klass.name || "AnonymousResponse"} has no version at or before #{version}"
+    end
+    private_class_method :target_version
+
+    # @param klass [Class] Versponse response class
+    # @param version [String] canonical version name
+    # @param view [Symbol] view to render
+    # @param key [String] referencing property, for errors
+    # @return [Versponse::LazyPlan] the class's plan, compiled on first use
+    # @raise [Versponse::DefinitionError] see {.check_target!}
+    def self.lazy_plan(klass, version:, view:, key:)
+      check_target!(klass, version:, view:, key:)
+      LazyPlan.new(klass, version:, view:)
+    end
+
+    # @param klass [Class] referenced class
+    # @param view [Symbol] view of a Versponse class
+    # @param property [Symbol, nil] property of a non-Versponse class
+    # @param context [Versponse::SchemaContext] schema generation context
+    # @param key [String, nil] referencing property; given, the target is checked with {.check_target!}
+    # @return [Hash] a $ref, or the inlined schema in validation mode
+    def self.schema(klass, view:, property:, context:, key: nil)
+      return foreign_schema(klass, property:, context:) unless versponse?(klass)
+
+      check_target!(klass, version: context.version, view:, key:) if key
+      return {"$ref" => klass.to_ref(view:)} unless context.validation?
+
+      context.inline([klass, view], klass.component_name(view:)) { klass.versponse.object_schema(version: context.version, view:, context:) }
+    end
+
+    # @param klass [Class] non-Versponse class implementing the protocol
+    # @param property [Symbol, nil] referenced property
+    # @param context [Versponse::SchemaContext] schema generation context
+    # @return [Hash] a $ref, or its validation schema
+    def self.foreign_schema(klass, property:, context:)
+      check_dialect!(klass)
+      return {"$ref" => klass.to_ref(property:)} unless context.validation?
+
+      klass.to_validation_schema(version: context.version, property:)
+    end
+
+    # JSON Schema versions that write const, nullability and anchors alike (OpenAPI 3.1 uses the 2020-12 dialect),
+    # so verquest and versponse schemas from the same group can be mixed
+    COMPATIBLE_VERSIONS = [%i[draft4], %i[openapi30], %i[draft6 draft7], %i[draft2019_09 draft2020_12 openapi31]].freeze
+
+    # A verquest request's schemas follow verquest's json_schema_version; embedded in versponse documents and
+    # validation they must be compatible with versponse's. Checked when schemas are built, so it sees the current config.
+    #
+    # @param klass [Object] referenced class
+    # @return [void]
+    # @raise [Versponse::DefinitionError] for a verquest request when the two gems' json_schema_version aren't compatible
+    def self.check_dialect!(klass)
+      return unless defined?(::Verquest::Base) && klass.is_a?(Class) && klass < ::Verquest::Base
+
+      theirs = ::Verquest.configuration.json_schema_version
+      ours = Versponse.configuration.json_schema_version
+      return if COMPATIBLE_VERSIONS.any? { |group| group.include?(theirs) && group.include?(ours) }
+
+      raise DefinitionError, "#{klass.name} is a verquest request with json_schema_version :#{theirs}, versponse uses :#{ours}; set both to the same"
+    end
+
+    # @param klass [Class] Versponse response class
+    # @param version [String] canonical version name
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the class has no identifier in that version (a class that
+    #   lacks the version entirely is left alone, like a plain $ref)
+    def self.ensure_identifier!(klass, version)
+      definition = klass.versponse.resolve(version)
+    rescue VersionNotFoundError
+      nil
+    else
+      return if definition.identifiers?
+
+      raise DefinitionError, "#{klass.name} has no identifier in #{version}; expandable associations need one"
+    end
+
+    # @param klass [Class] Versponse response class
+    # @param version [String] canonical version name
+    # @return [Versponse::LazyPlan] plan of the class's collapsed view
+    # @raise [Versponse::DefinitionError] when the class has no identifier
+    def self.collapsed_plan(klass, version)
+      ensure_identifier!(klass, version)
+      LazyPlan.new(klass, version:, view: :collapsed)
+    end
+
+    # @param klass [Class] Versponse response class
+    # @param version [String] canonical version name
+    # @return [#call, nil] the class's identifier collapse_if in that version; nil without one or without the version
+    def self.collapse_if(klass, version)
+      klass.versponse.resolve(version).collapse_if
+    rescue VersionNotFoundError
+      nil
+    end
+
+    # @param klass [Class] Versponse response class
+    # @param view [Symbol] view of the full form
+    # @param context [Versponse::SchemaContext] schema generation context
+    # @return [Array(Hash, Hash)] the full and the collapsed schema
+    # @raise [Versponse::DefinitionError] when the class has no identifier
+    def self.expandable_schemas(klass, view:, context:, key: nil)
+      check_target!(klass, version: context.version, view:, key:) if key
+      ensure_identifier!(klass, context.version)
+      [schema(klass, view:, property: nil, context:), schema(klass, view: :collapsed, property: nil, context:)]
+    end
+
+    # @param klass [Class] referenced class
+    # @param view [Symbol] view to walk
+    # @param version [String] canonical version name
+    # @param prefix [Array<String>] output keys leading here
+    # @param stack [Array<Array(Class, Symbol)>] classes and views being walked, to stop recursion
+    # @return [Array<Array(Array<String>, Array<Class>)>] expandable paths under the class's view, each with the
+    #   classes it renders
+    def self.nested_entries(klass, view:, version:, prefix:, stack:)
+      return [] unless versponse?(klass)
+      return [] if stack.include?([klass, view])
+
+      klass.versponse.resolve(version).properties_for(view).flat_map do |property|
+        property.expandable_entries(version:, prefix:, stack: [*stack, [klass, view]])
+      end
+    end
+  end
+end