jentic-openapi-datamodels 1.0.0a18__py3-none-any.whl → 1.0.0a20__py3-none-any.whl

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

@@ -2,16 +2,10 @@ from dataclasses import dataclass, field
 
 from ruamel import yaml
 
-from jentic.apitools.openapi.datamodels.low.context import Context
-from jentic.apitools.openapi.datamodels.low.fields import fixed_field
-from jentic.apitools.openapi.datamodels.low.model_builder import build_model
-from jentic.apitools.openapi.datamodels.low.sources import (
-    FieldSource,
-    KeySource,
-    ValueSource,
-    YAMLInvalidValue,
-    YAMLValue,
-)
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
 
 
 __all__ = ["ServerVariable", "build"]

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

@@ -1,23 +1,12 @@
-from dataclasses import dataclass, field, replace
+from dataclasses import dataclass, field
 
 from ruamel import yaml
 
-from jentic.apitools.openapi.datamodels.low.context import Context
-from jentic.apitools.openapi.datamodels.low.fields import fixed_field
-from jentic.apitools.openapi.datamodels.low.model_builder import build_model
-from jentic.apitools.openapi.datamodels.low.sources import (
-    FieldSource,
-    KeySource,
-    ValueSource,
-    YAMLInvalidValue,
-    YAMLValue,
-)
-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 ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .external_documentation import ExternalDocumentation
 
 
 __all__ = ["Tag", "build"]
@@ -42,7 +31,7 @@ class Tag:
     root_node: yaml.Node
     name: FieldSource[str] | None = fixed_field()
     description: FieldSource[str] | None = fixed_field()
-    external_docs: FieldSource[ExternalDocumentation] | None = fixed_field(
+    external_docs: FieldSource["ExternalDocumentation"] | None = fixed_field(
         metadata={"yaml_name": "externalDocs"}
     )
     extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
@@ -71,31 +60,4 @@ def build(root: yaml.Node, context: Context | None = None) -> Tag | ValueSource[
         tag = build(root)
         assert tag.name.value == 'pet'
     """
-    # 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)
-
-    # Use build_model to handle most fields
-    tag = build_model(root, Tag, context=context)
-
-    # Manually handle special fields that build_model can't process (nested objects)
-    for key_node, value_node in root.value:
-        key = context.yaml_constructor.construct_yaml_str(key_node)
-
-        if key == "externalDocs":
-            # Handle nested ExternalDocumentation object - child builder handles invalid nodes
-            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
-            external_docs = FieldSource(
-                value=build_external_documentation(value_node, context=context),
-                key_node=key_node,
-                value_node=value_node,
-            )
-            tag = replace(tag, external_docs=external_docs)
-            break
-
-    return tag
+    return build_model(root, Tag, context=context)

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

@@ -2,16 +2,10 @@ from dataclasses import dataclass, field
 
 from ruamel import yaml
 
-from jentic.apitools.openapi.datamodels.low.context import Context
-from jentic.apitools.openapi.datamodels.low.fields import fixed_field
-from jentic.apitools.openapi.datamodels.low.model_builder import build_model
-from jentic.apitools.openapi.datamodels.low.sources import (
-    FieldSource,
-    KeySource,
-    ValueSource,
-    YAMLInvalidValue,
-    YAMLValue,
-)
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
 
 
 __all__ = ["XML", "build"]

jentic/apitools/openapi/datamodels/low/v31/__init__.py

@@ -0,0 +1,77 @@
+"""OpenAPI 3.1.x Low-Level Data Models.
+
+This module provides low-level/plumbing data models for OpenAPI 3.1 specification objects.
+These models preserve complete source fidelity for inspection and validation.
+"""
+
+# Main entry point for parsing OpenAPI documents
+# All dataclasses for type hints and isinstance checks
+from .callback import Callback
+from .components import Components
+from .contact import Contact
+from .discriminator import Discriminator
+from .encoding import Encoding
+from .example import Example
+from .external_documentation import ExternalDocumentation
+from .header import Header
+from .info import Info
+from .license import License
+from .link import Link
+from .media_type import MediaType
+from .oauth_flow import OAuthFlow
+from .oauth_flows import OAuthFlows
+from .openapi import OpenAPI31, build
+from .operation import Operation
+from .parameter import Parameter
+from .path_item import PathItem
+from .paths import Paths
+from .reference import Reference
+from .request_body import RequestBody
+from .response import Response
+from .responses import Responses
+from .schema import BooleanJSONSchema, Schema
+from .security_requirement import SecurityRequirement
+from .security_scheme import SecurityScheme
+from .server import Server
+from .server_variable import ServerVariable
+from .tag import Tag
+from .xml import XML
+
+
+__all__ = [
+    # Main entry point
+    "build",
+    # Root object
+    "OpenAPI31",
+    # All dataclasses (alphabetically sorted)
+    "Callback",
+    "Components",
+    "Contact",
+    "Discriminator",
+    "Encoding",
+    "Example",
+    "ExternalDocumentation",
+    "Header",
+    "Info",
+    "License",
+    "Link",
+    "MediaType",
+    "OAuthFlow",
+    "OAuthFlows",
+    "Operation",
+    "Parameter",
+    "PathItem",
+    "Paths",
+    "Reference",
+    "RequestBody",
+    "Response",
+    "Responses",
+    "Schema",
+    "BooleanJSONSchema",
+    "SecurityRequirement",
+    "SecurityScheme",
+    "Server",
+    "ServerVariable",
+    "Tag",
+    "XML",
+]

jentic/apitools/openapi/datamodels/low/v31/builders/__init__.py

@@ -0,0 +1,347 @@
+"""Builders for OpenAPI 3.1.x specification objects."""
+
+from dataclasses import fields
+from typing import TYPE_CHECKING, Any, TypeVar, cast, get_args
+
+from ruamel import yaml
+
+from ...context import Context
+from ...extractors import extract_extension_fields
+from ...fields import fixed_fields
+from ...sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+
+
+if TYPE_CHECKING:
+    from ..callback import Callback  # noqa: F401
+    from ..example import Example  # noqa: F401
+    from ..external_documentation import ExternalDocumentation  # noqa: F401
+    from ..header import Header  # noqa: F401
+    from ..link import Link  # noqa: F401
+    from ..media_type import MediaType  # noqa: F401
+    from ..parameter import Parameter  # noqa: F401
+    from ..path_item import PathItem  # noqa: F401
+    from ..reference import Reference  # noqa: F401
+    from ..schema import BooleanJSONSchema, Schema  # noqa: F401
+    from ..security_requirement import SecurityRequirement  # noqa: F401
+    from ..server import Server  # noqa: F401
+
+
+__all__ = ["build_model", "build_field_source"]
+
+
+T = TypeVar("T")
+
+
+def build_model(
+    root: yaml.Node, dataclass_type: type[T], *, context: Context | None = None
+) -> T | ValueSource[YAMLInvalidValue]:
+    """
+    Generic builder for OpenAPI 3.1 low model.
+
+    Builds any dataclass that follows the pattern:
+    - Has a required `root_node: yaml.Node` field
+    - Has an optional `extensions: dict[...]` field
+    - Has spec fields marked with `fixed_field()`
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        dataclass_type: The dataclass type to build
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An instance of dataclass_type 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:
+        xml = build_model(root_node, XML, context=context)
+    """
+    # 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)
+
+    # Get fixed specification fields for this dataclass type
+    _fixed_fields = fixed_fields(dataclass_type)
+
+    # Build YAML name to Python field name mapping
+    yaml_to_field = {
+        field.metadata.get("yaml_name", fname): fname for fname, field in _fixed_fields.items()
+    }
+
+    # Extract field values in a single pass (non-recursive, single layer only)
+    field_values: dict[str, FieldSource[Any]] = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Map YAML key to Python field name
+        field_name = yaml_to_field.get(key)
+        if field_name:
+            field = _fixed_fields[field_name]
+            field_type_args = set(get_args(field.type))
+
+            if field_type_args & {
+                FieldSource[str],
+                FieldSource[bool],
+                FieldSource[int],
+                FieldSource[YAMLValue],
+            }:
+                field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], ValueSource[str]]]}:
+                # Handle dict with KeySource/ValueSource wrapping
+                if isinstance(value_node, yaml.MappingNode):
+                    mapping_dict: dict[KeySource[str], ValueSource[str]] = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        map_value = context.yaml_constructor.construct_object(
+                            map_value_node, deep=True
+                        )
+                        mapping_dict[KeySource(value=map_key, key_node=map_key_node)] = ValueSource(
+                            value=map_value, value_node=map_value_node
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=mapping_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[list[ValueSource[str]]]}:
+                # Handle list with ValueSource wrapping for each item
+                if isinstance(value_node, yaml.SequenceNode):
+                    value_list: list[ValueSource[str]] = []
+                    for item_node in value_node.value:
+                        item_value = context.yaml_constructor.construct_object(item_node, deep=True)
+                        value_list.append(ValueSource(value=item_value, value_node=item_node))
+                    field_values[field_name] = FieldSource(
+                        value=value_list, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a sequence - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[list["Server"]]}:
+                # Handle list[Server] with lazy import
+                from ..server import build as build_server
+
+                if isinstance(value_node, yaml.SequenceNode):
+                    servers_list = []
+                    for item_node in value_node.value:
+                        server_obj = build_server(item_node, context)
+                        servers_list.append(server_obj)
+                    field_values[field_name] = FieldSource(
+                        value=servers_list, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a sequence - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[list["SecurityRequirement"]]}:
+                # Handle list[SecurityRequirement] with lazy import
+                from ..security_requirement import build as build_security_requirement
+
+                if isinstance(value_node, yaml.SequenceNode):
+                    security_list = []
+                    for item_node in value_node.value:
+                        security_req = build_security_requirement(item_node, context)
+                        security_list.append(security_req)
+                    field_values[field_name] = FieldSource(
+                        value=security_list, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a sequence - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[list["Parameter | Reference"]]}:
+                # Handle list[Parameter | Reference] with lazy import
+                from ..parameter import build_parameter_or_reference
+
+                if isinstance(value_node, yaml.SequenceNode):
+                    parameters_list = []
+                    for item_node in value_node.value:
+                        parameter_or_reference = build_parameter_or_reference(item_node, context)
+                        parameters_list.append(parameter_or_reference)
+                    field_values[field_name] = FieldSource(
+                        value=parameters_list, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a sequence - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "Example | Reference"]]}:
+                # Handle dict[KeySource[str], Example | Reference] with lazy import
+                from ..example import build_example_or_reference
+
+                if isinstance(value_node, yaml.MappingNode):
+                    examples_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        example_or_reference = build_example_or_reference(map_value_node, context)
+                        examples_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            example_or_reference
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=examples_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "MediaType"]]}:
+                # Handle dict[KeySource[str], MediaType] with lazy import
+                from ..media_type import build as build_media_type
+
+                if isinstance(value_node, yaml.MappingNode):
+                    content_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        media_type_obj = build_media_type(map_value_node, context)
+                        content_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            media_type_obj
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=content_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "Header | Reference"]]}:
+                # Handle dict[KeySource[str], Header | Reference] with lazy import
+                from ..header import build_header_or_reference
+
+                if isinstance(value_node, yaml.MappingNode):
+                    headers_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        header_or_reference = build_header_or_reference(map_value_node, context)
+                        headers_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            header_or_reference
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=headers_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource["ExternalDocumentation"]}:
+                # Handle ExternalDocumentation with lazy import
+                from ..external_documentation import build as build_external_docs
+
+                field_values[field_name] = FieldSource(
+                    value=build_external_docs(value_node, context),
+                    key_node=key_node,
+                    value_node=value_node,
+                )
+            elif field_type_args & {FieldSource["Schema | BooleanJSONSchema"]}:
+                # Handle Schema | Reference union with lazy import
+                from ..schema import build as build_schema
+
+                field_values[field_name] = FieldSource(
+                    value=build_schema(value_node, context),
+                    key_node=key_node,
+                    value_node=value_node,
+                )
+            elif field_type_args & {FieldSource[dict[KeySource[str], "PathItem"]]}:
+                # Handle dict[KeySource[str], PathItem] with lazy import
+                from ..path_item import build as build_path_item
+
+                if isinstance(value_node, yaml.MappingNode):
+                    path_items_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        path_item = build_path_item(map_value_node, context)
+                        path_items_dict[KeySource(value=map_key, key_node=map_key_node)] = path_item
+                    field_values[field_name] = FieldSource(
+                        value=path_items_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "Callback | Reference"]]}:
+                # Handle dict[KeySource[str], Callback | Reference] with lazy import
+                from ..callback import build_callback_or_reference
+
+                if isinstance(value_node, yaml.MappingNode):
+                    callbacks_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        callback_or_reference = build_callback_or_reference(map_value_node, context)
+                        callbacks_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            callback_or_reference
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=callbacks_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "Header | Reference"]]}:
+                # Handle dict[KeySource[str], Header | Reference] with lazy import
+                from ..header import build_header_or_reference
+
+                if isinstance(value_node, yaml.MappingNode):
+                    headers_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        header_or_reference = build_header_or_reference(map_value_node, context)
+                        headers_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            header_or_reference
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=headers_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+            elif field_type_args & {FieldSource[dict[KeySource[str], "Link | Reference"]]}:
+                # Handle dict[KeySource[str], Link | Reference] with lazy import
+                from ..link import build_link_or_reference
+
+                if isinstance(value_node, yaml.MappingNode):
+                    links_dict = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        link_or_reference = build_link_or_reference(map_value_node, context)
+                        links_dict[KeySource(value=map_key, key_node=map_key_node)] = (
+                            link_or_reference
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=links_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    field_values[field_name] = build_field_source(key_node, value_node, context)
+
+    # Build and return the dataclass instance
+    # Conditionally include extensions field if dataclass supports it
+    # Cast to Any to work around generic type constraints
+    has_extensions = any(f.name == "extensions" for f in fields(cast(Any, dataclass_type)))
+    return cast(
+        T,
+        dataclass_type(
+            root_node=root,  # type: ignore[call-arg]
+            **field_values,
+            **({"extensions": extract_extension_fields(root, context)} if has_extensions else {}),
+        ),
+    )
+
+
+def build_field_source(
+    key_node: yaml.Node,
+    value_node: yaml.Node,
+    context: Context,
+) -> FieldSource[Any]:
+    """
+    Build a FieldSource from a YAML node.
+
+    Constructs the Python value from the YAML node and wraps it in a FieldSource
+    that preserves the original node locations for error reporting.
+
+    Args:
+        key_node: The YAML node for the field key
+        value_node: The YAML node for the field value
+        context: Parsing context
+
+    Returns:
+        A FieldSource containing the constructed value and node references
+    """
+    value = context.yaml_constructor.construct_object(value_node, deep=True)
+    return FieldSource(value=value, key_node=key_node, value_node=value_node)

jentic/apitools/openapi/datamodels/low/v31/callback.py

@@ -0,0 +1,131 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .path_item import PathItem
+from .path_item import build as build_path_item
+from .reference import Reference
+from .reference import build as build_reference
+
+
+__all__ = ["Callback", "build", "build_callback_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Callback:
+    """
+    Callback Object representation for OpenAPI 3.1.
+
+    A map of possible out-of-band callbacks related to the parent operation. Each value in the map
+    is a Path Item Object that describes a set of requests that may be initiated by the API provider
+    and the expected responses.
+
+    The key is a runtime expression that identifies a URL to use for the callback operation.
+
+    Attributes:
+        root_node: The top-level node representing the entire Callback object in the original source file
+        path_items: Map of expression keys to Path Item Objects. Each key is a runtime expression
+                    that will be evaluated to determine the callback URL.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    path_items: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Callback | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Callback 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.
+
+    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 Callback 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:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        '{$request.body#/callbackUrl}':
+          post:
+            requestBody:
+              required: true
+              content:
+                application/json:
+                  schema:
+                    type: object
+            responses:
+              '200':
+                description: callback successfully processed
+        ''')
+        callback = build(root)
+        assert len(callback.path_items) > 0
+    """
+    context = context or Context()
+
+    # Check if root is a MappingNode, if not return ValueSource with invalid data
+    if not isinstance(root, yaml.MappingNode):
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Extract extensions first
+    extensions = extract_extension_fields(root, context)
+    extension_properties = {k.value for k in extensions.keys()}
+
+    # Process each field to determine if it's an expression (not an extension)
+    path_items: dict[KeySource[str], PathItem | ValueSource[YAMLInvalidValue]] = {}
+
+    for key_node, value_node in root.value:
+        expression = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if expression not in extension_properties:
+            # Expression field (any key that's not an extension) - build as Path Item
+            path_item_obj = build_path_item(value_node, context)
+            path_items[KeySource(value=expression, key_node=key_node)] = path_item_obj
+
+    # Create and return the Callback object with collected data
+    return Callback(
+        root_node=root,
+        path_items=path_items,  # type: ignore[arg-type]
+        extensions=extensions,
+    )
+
+
+def build_callback_or_reference(
+    node: yaml.Node, context: Context
+) -> Callback | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Callback or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Callback object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Callback, 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 Callback
+    return build(node, context)