jentic-openapi-datamodels 1.0.0a11__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

jentic/apitools/openapi/datamodels/low/v30/schema.py

@@ -1,626 +1,335 @@
-"""
-OpenAPI 3.0.4 Schema Object model.
-
-The Schema Object allows the definition of input and output data types.
-These types can be objects, but also primitives and arrays.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping, Sequence
-from typing import Any
-
+from dataclasses import dataclass, field
+from typing import Any, TypeAlias, get_args
+
+from ruamel import yaml
+
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.extractors import extract_extension_fields
+from jentic.apitools.openapi.datamodels.low.fields import fixed_field, fixed_fields
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+    YAMLInvalidValue,
+    YAMLValue,
+)
 from jentic.apitools.openapi.datamodels.low.v30.discriminator import Discriminator
+from jentic.apitools.openapi.datamodels.low.v30.discriminator import build as build_discriminator
 from jentic.apitools.openapi.datamodels.low.v30.external_documentation import (
     ExternalDocumentation,
 )
+from jentic.apitools.openapi.datamodels.low.v30.external_documentation import (
+    build as build_external_documentation,
+)
 from jentic.apitools.openapi.datamodels.low.v30.reference import Reference
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.v30.reference import build as build_reference
 from jentic.apitools.openapi.datamodels.low.v30.xml import XML
+from jentic.apitools.openapi.datamodels.low.v30.xml import build as build_xml
+
+
+__all__ = ["Schema", "NestedSchema", "build"]
 
 
-__all__ = ["Schema"]
+# Type alias for nested schema references
+# A schema node that can be nested within another schema, representing:
+# - Schema: A valid schema object
+# - Reference: A $ref reference to another schema
+# - ValueSource[YAMLInvalidValue]: Invalid/malformed data preserved for validation
+NestedSchema: TypeAlias = "Schema | Reference | ValueSource[YAMLInvalidValue]"
 
 
-class Schema(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class Schema:
+    """
+    Schema Object representation for OpenAPI 3.0.
+
+    The Schema Object allows the definition of input and output data types. These types can be
+    objects, but also primitives and arrays. This object is an extended subset of the JSON Schema
+    Specification Wright Draft 00.
+
+    Attributes:
+        root_node: The top-level node representing the entire Schema object in the original source file
+
+        # JSON Schema Core validation keywords
+        title: A title for the schema
+        multipleOf: A numeric instance is valid only if division by this value results in an integer
+        maximum: Upper limit for a numeric instance
+        exclusiveMaximum: If true, the value must be strictly less than maximum
+        minimum: Lower limit for a numeric instance
+        exclusiveMinimum: If true, the value must be strictly greater than minimum
+        maxLength: Maximum length of a string instance
+        minLength: Minimum length of a string instance
+        pattern: A string instance is valid if the regular expression matches the instance successfully
+        maxItems: Maximum number of items in an array instance
+        minItems: Minimum number of items in an array instance
+        uniqueItems: If true, array items must be unique
+        maxProperties: Maximum number of properties in an object instance
+        minProperties: Minimum number of properties in an object instance
+        required: List of required property names
+        enum: Fixed set of allowed values
+
+        # JSON Schema Type and Structure
+        type: Value type (string, number, integer, boolean, array, object)
+        allOf: Must be valid against all of the subschemas
+        oneOf: Must be valid against exactly one of the subschemas
+        anyOf: Must be valid against any of the subschemas
+        not_: Must not be valid against the given schema
+        items: Schema for array items (or array of schemas for tuple validation)
+        properties: Property name to schema mappings
+        additionalProperties: Schema for properties not defined in properties, or boolean to allow/disallow
+
+        # JSON Schema Metadata
+        description: A short description. CommonMark syntax MAY be used for rich text representation.
+        format: Additional format hint for the type (e.g., "email", "uuid", "uri", "date-time")
+        default: Default value
+
+        # OpenAPI-specific extensions
+        nullable: Allows sending a null value
+        discriminator: Adds support for polymorphism
+        readOnly: Relevant only for Schema "properties" definitions - sent in response but not in request
+        writeOnly: Relevant only for Schema "properties" definitions - sent in request but not in response
+        xml: Additional metadata for XML representations
+        externalDocs: Additional external documentation
+        example: Example of the media type
+        deprecated: Specifies that the schema is deprecated
+
+        extensions: Specification extensions (x-* fields)
     """
-    Represents a Schema Object from OpenAPI 3.0.4.
 
-    The Schema Object allows the definition of input and output data types.
-    Based on a subset of JSON Schema Draft 4/5 with OpenAPI-specific extensions.
+    root_node: yaml.Node
+
+    # JSON Schema Core validation keywords
+    title: FieldSource[str] | None = fixed_field()
+    multipleOf: FieldSource[int | float] | None = fixed_field()
+    maximum: FieldSource[int | float] | None = fixed_field()
+    exclusiveMaximum: FieldSource[bool] | None = fixed_field()
+    minimum: FieldSource[int | float] | None = fixed_field()
+    exclusiveMinimum: FieldSource[bool] | None = fixed_field()
+    maxLength: FieldSource[int] | None = fixed_field()
+    minLength: FieldSource[int] | None = fixed_field()
+    pattern: FieldSource[str] | None = fixed_field()
+    maxItems: FieldSource[int] | None = fixed_field()
+    minItems: FieldSource[int] | None = fixed_field()
+    uniqueItems: FieldSource[bool] | None = fixed_field()
+    maxProperties: FieldSource[int] | None = fixed_field()
+    minProperties: FieldSource[int] | None = fixed_field()
+    required: FieldSource[list[str]] | None = fixed_field()
+    enum: FieldSource[list[YAMLValue]] | None = fixed_field()
+
+    # JSON Schema Type and Structure (nested schemas)
+    type: FieldSource[str] | None = fixed_field()
+    allOf: FieldSource[list[NestedSchema]] | None = fixed_field()
+    oneOf: FieldSource[list[NestedSchema]] | None = fixed_field()
+    anyOf: FieldSource[list[NestedSchema]] | None = fixed_field()
+    not_: FieldSource[NestedSchema] | None = fixed_field(metadata={"yaml_name": "not"})
+    items: FieldSource[NestedSchema] | None = fixed_field()
+    properties: FieldSource[dict[KeySource[str], ValueSource[NestedSchema]]] | None = fixed_field()
+    additionalProperties: FieldSource["bool | NestedSchema"] | None = fixed_field()
 
-    Supports specification extensions (x-* fields).
+    # JSON Schema Metadata
+    description: FieldSource[str] | None = fixed_field()
+    format: FieldSource[str] | None = fixed_field()
+    default: FieldSource[YAMLValue] | None = fixed_field()
+
+    # OpenAPI-specific extensions
+    nullable: FieldSource[bool] | None = fixed_field()
+    discriminator: FieldSource[Discriminator] | None = fixed_field()
+    readOnly: FieldSource[bool] | None = fixed_field()
+    writeOnly: FieldSource[bool] | None = fixed_field()
+    xml: FieldSource[XML] | None = fixed_field()
+    externalDocs: FieldSource[ExternalDocumentation] | None = fixed_field()
+    example: FieldSource[YAMLValue] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> "Schema | ValueSource[YAMLInvalidValue]":
+    """
+    Build a Schema object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
+
+    Note: Schema is self-referential (can contain other Schema objects in allOf, oneOf, anyOf, not,
+    items, properties, additionalProperties). The builder handles nested Schema objects by preserving
+    them as raw YAML values, letting validation layers interpret them.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A Schema object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
 
     Example:
-        >>> # String schema with constraints
-        >>> schema = Schema({
-        ...     "type": "string",
-        ...     "minLength": 1,
-        ...     "maxLength": 100
-        ... })
-        >>> schema.type
-        'string'
-
-        >>> # Object schema with properties
-        >>> schema = Schema({
-        ...     "type": "object",
-        ...     "required": ["name"],
-        ...     "properties": {
-        ...         "name": {"type": "string"},
-        ...         "age": {"type": "integer"}
-        ...     }
-        ... })
-        >>> schema.required
-        ['name']
-
-        >>> # Schema with discriminator
-        >>> schema = Schema({
-        ...     "discriminator": {
-        ...         "propertyName": "petType"
-        ...     }
-        ... })
-        >>> schema.discriminator.property_name
-        'petType'
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("type: string\\nminLength: 1\\nmaxLength: 100")
+        schema = build(root)
+        assert schema.type.value == 'string'
+        assert schema.minLength.value == 1
     """
-
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset(
-        {
-            # JSON Schema Core
-            "title",
-            "multipleOf",
-            "maximum",
-            "exclusiveMaximum",
-            "minimum",
-            "exclusiveMinimum",
-            "maxLength",
-            "minLength",
-            "pattern",
-            "maxItems",
-            "minItems",
-            "uniqueItems",
-            "maxProperties",
-            "minProperties",
-            "required",
-            "enum",
-            # JSON Schema Type
-            "type",
-            "allOf",
-            "oneOf",
-            "anyOf",
-            "not",
-            "items",
-            "properties",
-            "additionalProperties",
-            # JSON Schema Metadata
-            "description",
-            "format",
-            "default",
-            # OpenAPI Extensions
-            "nullable",
-            "discriminator",
-            "readOnly",
-            "writeOnly",
-            "xml",
-            "externalDocs",
-            "example",
-            "deprecated",
-        }
+    # Initialize context once at the beginning
+    if context is None:
+        context = Context()
+
+    if not isinstance(root, yaml.MappingNode):
+        # Preserve invalid root data instead of returning None
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Build YAML name to Python field name mapping
+    _fixed_fields = fixed_fields(Schema)
+    yaml_to_field = {
+        f.metadata.get("yaml_name", fname): fname for fname, f in _fixed_fields.items()
+    }
+
+    # Accumulate all field values in a single pass
+    field_values: dict[str, Any] = {}
+
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Skip extension fields - handled separately at the end
+        if key.startswith("x-"):
+            continue
+
+        # Map YAML key to Python field name
+        field_name = yaml_to_field.get(key)
+        if not field_name:
+            continue
+
+        # Get field metadata
+        field_info = _fixed_fields[field_name]
+        field_type_args = set(get_args(field_info.type))
+
+        # Simple scalar fields (handled like build_model does)
+        if field_type_args & {
+            FieldSource[str],
+            FieldSource[bool],
+            FieldSource[int],
+            FieldSource[int | float],
+            FieldSource[YAMLValue],
+            FieldSource[list[str]],
+            FieldSource[list[YAMLValue]],
+        }:
+            value = context.yaml_constructor.construct_object(value_node, deep=True)
+            field_values[field_name] = FieldSource(
+                value=value, key_node=key_node, value_node=value_node
+            )
+
+        # Recursive schema list fields (allOf, oneOf, anyOf)
+        elif key in ("allOf", "oneOf", "anyOf"):
+            if isinstance(value_node, yaml.SequenceNode):
+                schemas = []
+                for item_node in value_node.value:
+                    schema_or_ref = _build_schema_or_reference(item_node, context)
+                    schemas.append(schema_or_ref)
+                field_values[field_name] = FieldSource(
+                    value=schemas, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a sequence - preserve as-is for validation
+                value = context.yaml_constructor.construct_object(value_node, deep=True)
+                field_values[field_name] = FieldSource(
+                    value=value, key_node=key_node, value_node=value_node
+                )
+        # Recursive schema single fields (not, items)
+        elif key in ("not", "items"):
+            schema_or_ref = _build_schema_or_reference(value_node, context)
+            field_values[field_name] = FieldSource(
+                value=schema_or_ref, key_node=key_node, value_node=value_node
+            )
+        # additionalProperties (boolean | schema | reference)
+        elif key == "additionalProperties":
+            # Check if it's a boolean or a schema/reference
+            if (
+                isinstance(value_node, yaml.ScalarNode)
+                and value_node.tag == "tag:yaml.org,2002:bool"
+            ):
+                value = context.yaml_constructor.construct_object(value_node)
+                field_values[field_name] = FieldSource(
+                    value=value, key_node=key_node, value_node=value_node
+                )
+            else:
+                # It's a schema or reference
+                schema_or_ref = _build_schema_or_reference(value_node, context)
+                field_values[field_name] = FieldSource(
+                    value=schema_or_ref, key_node=key_node, value_node=value_node
+                )
+        # properties (dict[KeySource[str], ValueSource[NestedSchema]])
+        elif key == "properties":
+            if isinstance(value_node, yaml.MappingNode):
+                properties_dict: dict[KeySource[str], ValueSource[NestedSchema]] = {}
+                for prop_key_node, prop_value_node in value_node.value:
+                    prop_key = context.yaml_constructor.construct_yaml_str(prop_key_node)
+                    # Recursively build each property schema
+                    prop_schema_or_ref = _build_schema_or_reference(prop_value_node, context)
+                    properties_dict[KeySource(value=prop_key, key_node=prop_key_node)] = (
+                        ValueSource(value=prop_schema_or_ref, value_node=prop_value_node)
+                    )
+                field_values[field_name] = FieldSource(
+                    value=properties_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                value = context.yaml_constructor.construct_object(value_node, deep=True)
+                field_values[field_name] = FieldSource(
+                    value=value, key_node=key_node, value_node=value_node
+                )
+        # Nested objects (discriminator, xml, externalDocs)
+        elif key == "discriminator":
+            field_values[field_name] = FieldSource(
+                value=build_discriminator(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+        elif key == "xml":
+            field_values[field_name] = FieldSource(
+                value=build_xml(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+        elif key == "externalDocs":
+            field_values[field_name] = FieldSource(
+                value=build_external_documentation(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+
+    # Build and return the Schema instance (single constructor call)
+    return Schema(
+        root_node=root,
+        **field_values,
+        extensions=extract_extension_fields(root, context),
     )
 
-    def __init__(self, data: Mapping[str, Any] | None = None):
-        """
-        Initialize a Schema object.
-
-        Automatically marshals nested objects (discriminator, xml, externalDocs, and nested schemas).
-
-        Args:
-            data: Optional mapping to initialize the object with
-        """
-        super().__init__()
-        if data:
-            for key, value in data.items():
-                # Marshal specific nested objects
-                if (
-                    key == "discriminator"
-                    and isinstance(value, Mapping)
-                    and not isinstance(value, Discriminator)
-                ):
-                    self[key] = Discriminator(value)
-                elif key == "xml" and isinstance(value, Mapping) and not isinstance(value, XML):
-                    self[key] = XML(value)
-                elif (
-                    key == "externalDocs"
-                    and isinstance(value, Mapping)
-                    and not isinstance(value, ExternalDocumentation)
-                ):
-                    self[key] = ExternalDocumentation(value)
-                # Unmarshal schema composition lists (allOf, oneOf, anyOf)
-                elif (
-                    key in ("allOf", "oneOf", "anyOf")
-                    and isinstance(value, Sequence)
-                    and not isinstance(value, str)
-                ):
-                    self[key] = [self._unmarshal_schema_or_reference(item) for item in value]
-                # Unmarshal single schema fields (not, items)
-                elif key in ("not", "items") and isinstance(value, Mapping):
-                    self[key] = self._unmarshal_schema_or_reference(value)
-                # Unmarshal properties dict
-                elif key == "properties" and isinstance(value, Mapping):
-                    self[key] = {
-                        k: self._unmarshal_schema_or_reference(v) for k, v in value.items()
-                    }
-                # Unmarshal additionalProperties (can be bool or schema)
-                elif key == "additionalProperties":
-                    if isinstance(value, bool):
-                        self[key] = value
-                    elif isinstance(value, Mapping):
-                        self[key] = self._unmarshal_schema_or_reference(value)
-                    else:
-                        self[key] = self._copy_value(value)
-                else:
-                    # Store as-is (with defensive copy)
-                    self[key] = self._copy_value(value)
-
-    # JSON Schema Core - Metadata
-    @property
-    def title(self) -> str | None:
-        """A title for the schema."""
-        return self.get("title")
-
-    @title.setter
-    def title(self, value: str | None) -> None:
-        if value is None:
-            self.pop("title", None)
-        else:
-            self["title"] = value
-
-    # JSON Schema Core - Numeric validation
-    @property
-    def multiple_of(self) -> float | int | None:
-        """Value must be multiple of this number."""
-        return self.get("multipleOf")
-
-    @multiple_of.setter
-    def multiple_of(self, value: float | int | None) -> None:
-        if value is None:
-            self.pop("multipleOf", None)
-        else:
-            self["multipleOf"] = value
-
-    @property
-    def maximum(self) -> float | int | None:
-        """Maximum value (inclusive)."""
-        return self.get("maximum")
-
-    @maximum.setter
-    def maximum(self, value: float | int | None) -> None:
-        if value is None:
-            self.pop("maximum", None)
-        else:
-            self["maximum"] = value
-
-    @property
-    def exclusive_maximum(self) -> float | int | None:
-        """Maximum value (exclusive)."""
-        return self.get("exclusiveMaximum")
-
-    @exclusive_maximum.setter
-    def exclusive_maximum(self, value: float | int | None) -> None:
-        if value is None:
-            self.pop("exclusiveMaximum", None)
-        else:
-            self["exclusiveMaximum"] = value
-
-    @property
-    def minimum(self) -> float | int | None:
-        """Minimum value (inclusive)."""
-        return self.get("minimum")
-
-    @minimum.setter
-    def minimum(self, value: float | int | None) -> None:
-        if value is None:
-            self.pop("minimum", None)
-        else:
-            self["minimum"] = value
-
-    @property
-    def exclusive_minimum(self) -> float | int | None:
-        """Minimum value (exclusive)."""
-        return self.get("exclusiveMinimum")
-
-    @exclusive_minimum.setter
-    def exclusive_minimum(self, value: float | int | None) -> None:
-        if value is None:
-            self.pop("exclusiveMinimum", None)
-        else:
-            self["exclusiveMinimum"] = value
-
-    # String validation properties
-    @property
-    def max_length(self) -> int | None:
-        """Maximum string length."""
-        return self.get("maxLength")
-
-    @max_length.setter
-    def max_length(self, value: int | None) -> None:
-        if value is None:
-            self.pop("maxLength", None)
-        else:
-            self["maxLength"] = value
-
-    @property
-    def min_length(self) -> int | None:
-        """Minimum string length."""
-        return self.get("minLength")
-
-    @min_length.setter
-    def min_length(self, value: int | None) -> None:
-        if value is None:
-            self.pop("minLength", None)
-        else:
-            self["minLength"] = value
-
-    @property
-    def pattern(self) -> str | None:
-        """Regular expression pattern for string validation."""
-        return self.get("pattern")
-
-    @pattern.setter
-    def pattern(self, value: str | None) -> None:
-        if value is None:
-            self.pop("pattern", None)
-        else:
-            self["pattern"] = value
-
-    # Array validation properties
-    @property
-    def max_items(self) -> int | None:
-        """Maximum number of array items."""
-        return self.get("maxItems")
-
-    @max_items.setter
-    def max_items(self, value: int | None) -> None:
-        if value is None:
-            self.pop("maxItems", None)
-        else:
-            self["maxItems"] = value
-
-    @property
-    def min_items(self) -> int | None:
-        """Minimum number of array items."""
-        return self.get("minItems")
-
-    @min_items.setter
-    def min_items(self, value: int | None) -> None:
-        if value is None:
-            self.pop("minItems", None)
-        else:
-            self["minItems"] = value
-
-    @property
-    def unique_items(self) -> bool | None:
-        """Whether array items must be unique."""
-        return self.get("uniqueItems")
-
-    @unique_items.setter
-    def unique_items(self, value: bool | None) -> None:
-        if value is None:
-            self.pop("uniqueItems", None)
-        else:
-            self["uniqueItems"] = value
-
-    # JSON Schema Core - Object validation
-    @property
-    def max_properties(self) -> int | None:
-        """Maximum number of object properties."""
-        return self.get("maxProperties")
-
-    @max_properties.setter
-    def max_properties(self, value: int | None) -> None:
-        if value is None:
-            self.pop("maxProperties", None)
-        else:
-            self["maxProperties"] = value
-
-    @property
-    def min_properties(self) -> int | None:
-        """Minimum number of object properties."""
-        return self.get("minProperties")
-
-    @min_properties.setter
-    def min_properties(self, value: int | None) -> None:
-        if value is None:
-            self.pop("minProperties", None)
-        else:
-            self["minProperties"] = value
-
-    @property
-    def required(self) -> list[str] | None:
-        """List of required property names (for object types)."""
-        return self.get("required")
-
-    @required.setter
-    def required(self, value: list[str] | None) -> None:
-        if value is None:
-            self.pop("required", None)
-        else:
-            self["required"] = value
-
-    @property
-    def enum(self) -> list[Any] | None:
-        """Allowed values."""
-        return self.get("enum")
-
-    @enum.setter
-    def enum(self, value: list[Any] | None) -> None:
-        if value is None:
-            self.pop("enum", None)
-        else:
-            self["enum"] = value
-
-    # JSON Schema Type
-    @property
-    def type(self) -> str | None:
-        """Type of the schema (string, number, integer, boolean, array, object, null)."""
-        return self.get("type")
-
-    @type.setter
-    def type(self, value: str | None) -> None:
-        if value is None:
-            self.pop("type", None)
-        else:
-            self["type"] = value
-
-    @property
-    def all_of(self) -> list[Schema | Reference] | None:
-        """Schemas that must all be valid (list of Schema or Reference objects)."""
-        return self.get("allOf")
-
-    @all_of.setter
-    def all_of(self, value: list[Schema | Reference] | None) -> None:
-        if value is None:
-            self.pop("allOf", None)
-        else:
-            self["allOf"] = value
-
-    @property
-    def one_of(self) -> list[Schema | Reference] | None:
-        """Schemas where exactly one must be valid (list of Schema or Reference objects)."""
-        return self.get("oneOf")
-
-    @one_of.setter
-    def one_of(self, value: list[Schema | Reference] | None) -> None:
-        if value is None:
-            self.pop("oneOf", None)
-        else:
-            self["oneOf"] = value
-
-    @property
-    def any_of(self) -> list[Schema | Reference] | None:
-        """Schemas where at least one must be valid (list of Schema or Reference objects)."""
-        return self.get("anyOf")
-
-    @any_of.setter
-    def any_of(self, value: list[Schema | Reference] | None) -> None:
-        if value is None:
-            self.pop("anyOf", None)
-        else:
-            self["anyOf"] = value
-
-    @property
-    def not_(self) -> Schema | Reference | None:
-        """Schema that must NOT be valid."""
-        return self.get("not")
-
-    @not_.setter
-    def not_(self, value: Schema | Reference | None) -> None:
-        if value is None:
-            self.pop("not", None)
-        else:
-            self["not"] = value
-
-    @property
-    def items_(self) -> Schema | Reference | None:
-        """
-        Schema for array items (Schema or Reference object).
-
-        Note: Property named 'items_' (with underscore) to avoid conflict with
-        MutableMapping.items() method. Dict access still uses the standard field name:
-        schema["items"].
-        """
-        return self.get("items")
-
-    @items_.setter
-    def items_(self, value: Schema | Reference | None) -> None:
-        if value is None:
-            self.pop("items", None)
-        else:
-            self["items"] = value
-
-    @property
-    def properties(self) -> dict[str, Schema | Reference] | None:
-        """Object properties (map of property name to Schema or Reference)."""
-        return self.get("properties")
-
-    @properties.setter
-    def properties(self, value: Mapping[str, Schema | Reference] | None) -> None:
-        if value is None:
-            self.pop("properties", None)
-        else:
-            self["properties"] = dict(value) if isinstance(value, Mapping) else value
-
-    @property
-    def additional_properties(self) -> bool | Schema | Reference | None:
-        """Schema for additional properties (bool or Schema or Reference object)."""
-        return self.get("additionalProperties")
-
-    @additional_properties.setter
-    def additional_properties(self, value: bool | Schema | Reference | None) -> None:
-        if value is None:
-            self.pop("additionalProperties", None)
-        else:
-            self["additionalProperties"] = value
 
-    # JSON Schema Metadata
-    @property
-    def description(self) -> str | None:
-        """A description of the schema."""
-        return self.get("description")
-
-    @description.setter
-    def description(self, value: str | None) -> None:
-        if value is None:
-            self.pop("description", None)
-        else:
-            self["description"] = value
-
-    @property
-    def format(self) -> str | None:
-        """Format hint for the type (e.g., date-time, email, uuid)."""
-        return self.get("format")
-
-    @format.setter
-    def format(self, value: str | None) -> None:
-        if value is None:
-            self.pop("format", None)
-        else:
-            self["format"] = value
-
-    @property
-    def default(self) -> Any:
-        """Default value."""
-        return self.get("default")
-
-    @default.setter
-    def default(self, value: Any) -> None:
-        if value is None:
-            self.pop("default", None)
-        else:
-            self["default"] = value
-
-    # OpenAPI Extensions
-    @property
-    def nullable(self) -> bool | None:
-        """Whether the value can be null (OpenAPI extension)."""
-        return self.get("nullable")
-
-    @nullable.setter
-    def nullable(self, value: bool | None) -> None:
-        if value is None:
-            self.pop("nullable", None)
-        else:
-            self["nullable"] = value
-
-    @property
-    def discriminator(self) -> Discriminator | None:
-        """Discriminator for polymorphism (OpenAPI extension)."""
-        return self.get("discriminator")
-
-    @discriminator.setter
-    def discriminator(self, value: Discriminator | None) -> None:
-        if value is None:
-            self.pop("discriminator", None)
-        else:
-            self["discriminator"] = value
-
-    @property
-    def read_only(self) -> bool | None:
-        """Whether the property is read-only (OpenAPI extension)."""
-        return self.get("readOnly")
-
-    @read_only.setter
-    def read_only(self, value: bool | None) -> None:
-        if value is None:
-            self.pop("readOnly", None)
-        else:
-            self["readOnly"] = value
-
-    @property
-    def write_only(self) -> bool | None:
-        """Whether the property is write-only (OpenAPI extension)."""
-        return self.get("writeOnly")
-
-    @write_only.setter
-    def write_only(self, value: bool | None) -> None:
-        if value is None:
-            self.pop("writeOnly", None)
-        else:
-            self["writeOnly"] = value
-
-    @property
-    def xml(self) -> XML | None:
-        """XML representation metadata (OpenAPI extension)."""
-        return self.get("xml")
-
-    @xml.setter
-    def xml(self, value: XML | None) -> None:
-        if value is None:
-            self.pop("xml", None)
-        else:
-            self["xml"] = value
-
-    @property
-    def external_docs(self) -> ExternalDocumentation | None:
-        """External documentation (OpenAPI extension)."""
-        return self.get("externalDocs")
-
-    @external_docs.setter
-    def external_docs(self, value: ExternalDocumentation | None) -> None:
-        if value is None:
-            self.pop("externalDocs", None)
-        else:
-            self["externalDocs"] = value
-
-    @property
-    def example(self) -> Any:
-        """Example value (OpenAPI extension)."""
-        return self.get("example")
-
-    @example.setter
-    def example(self, value: Any) -> None:
-        if value is None:
-            self.pop("example", None)
-        else:
-            self["example"] = value
-
-    @property
-    def deprecated(self) -> bool | None:
-        """Whether the schema is deprecated (OpenAPI extension)."""
-        return self.get("deprecated")
-
-    @deprecated.setter
-    def deprecated(self, value: bool | None) -> None:
-        if value is None:
-            self.pop("deprecated", None)
-        else:
-            self["deprecated"] = value
-
-    # Helper methods
-    @classmethod
-    def _unmarshal_schema_or_reference(cls, value: Any) -> Schema | Reference | Any:
-        """
-        Unmarshal a value into Schema or Reference if it's a Mapping.
-
-        Converts raw data (dict/Mapping) into Schema or Reference objects during construction.
-        Uses the actual class (or subclass) for creating Schema instances.
-
-        Args:
-            value: Value to unmarshal
-
-        Returns:
-            Schema or Reference instance, or value as-is
-        """
-        if not isinstance(value, Mapping):
-            return value
-
-        # Already unmarshaled
-        if isinstance(value, (Schema, Reference)):
-            return value
-
-        # Check if it's a reference (has $ref field)
-        if "$ref" in value:
-            return Reference(value)
-        else:
-            # Otherwise treat as Schema (or subclass)
-            return cls(value)
+def _build_schema_or_reference(node: yaml.Node, context: Context) -> NestedSchema:
+    """
+    Build either a Schema or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Schema object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Schema, Reference, or ValueSource if the node is invalid
+    """
+    # Check if it's a reference (has $ref key)
+    if isinstance(node, yaml.MappingNode):
+        for key_node, _ in node.value:
+            key = context.yaml_constructor.construct_yaml_str(key_node)
+            if key == "$ref":
+                return build_reference(node, context)
+
+    # Otherwise, try to build as Schema (which may be recursive)
+    return build(node, context)