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

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

@@ -0,0 +1,109 @@
+import re
+from dataclasses import dataclass, field
+from typing import cast
+
+from ruamel import yaml
+
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .reference import Reference
+from .response import Response, build_response_or_reference
+
+
+__all__ = ["Responses", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Responses:
+    """
+    Responses Object representation for OpenAPI 3.0.
+
+    A container for the expected responses of an operation. The container maps a HTTP response code
+    to the expected response.
+
+    Attributes:
+        root_node: The top-level node representing the entire Responses object in the original source file
+        default: The documentation of responses other than the ones declared for specific HTTP response codes.
+                Use this field to cover undeclared responses.
+        responses: Maps HTTP status codes to their Response objects. The key is the HTTP status code
+                  (e.g., "200", "404", "4XX") and the value is a Response object or Reference.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    default: FieldSource[Response | Reference] | None = fixed_field()
+    responses: dict[KeySource[str], Response | Reference] = field(default_factory=dict)
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Responses | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Responses 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 Responses 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('''
+        '200':
+          description: successful operation
+        '404':
+          description: not found
+        default:
+          description: unexpected error
+        ''')
+        responses = build(root)
+        assert '200' in {k.value for k in responses.responses.keys()}
+    """
+    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)
+
+    # Process each field to determine if it's default or a status code response
+    responses = {}
+    default: FieldSource[Response | Reference] | None = None
+
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "default":
+            # Handle default response - can be Response or Reference
+            response_or_reference = build_response_or_reference(value_node, context)
+            default = cast(
+                FieldSource[Response | Reference],
+                FieldSource(value=response_or_reference, key_node=key_node, value_node=value_node),
+            )
+        elif _HTTP_STATUS_CODE_PATTERN.match(key):
+            # Valid HTTP status code (100-599) or pattern (1XX-5XX)
+            response_or_reference = build_response_or_reference(value_node, context)
+            responses[KeySource(value=key, key_node=key_node)] = response_or_reference
+
+    # Create and return the Responses object with collected data
+    return Responses(
+        root_node=root,
+        default=default,
+        responses=responses,
+        extensions=extract_extension_fields(root, context),
+    )
+
+
+# Pattern for valid HTTP status codes: 100-599 or wildcard patterns (1XX-5XX)
+_HTTP_STATUS_CODE_PATTERN = re.compile(r"^([1-5]XX|[1-5][0-9]{2})$")

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

@@ -3,31 +3,22 @@ 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.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"]
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..fields import fixed_field, fixed_fields
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_field_source
+from .discriminator import Discriminator
+from .discriminator import build as build_discriminator
+from .external_documentation import ExternalDocumentation
+from .external_documentation import build as build_external_documentation
+from .reference import Reference
+from .reference import build as build_reference
+from .xml import XML
+from .xml import build as build_xml
+
+
+__all__ = ["Schema", "NestedSchema", "build", "build_schema_or_reference"]
 
 
 # Type alias for nested schema references
@@ -52,31 +43,31 @@ class Schema:
 
         # 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
+        multiple_of: 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
+        exclusive_maximum: 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
+        exclusive_minimum: If true, the value must be strictly greater than minimum
+        max_length: Maximum length of a string instance
+        min_length: 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
+        max_items: Maximum number of items in an array instance
+        min_items: Minimum number of items in an array instance
+        unique_items: If true, array items must be unique
+        max_properties: Maximum number of properties in an object instance
+        min_properties: 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
+        all_of: Must be valid against all of the subschemas
+        one_of: Must be valid against exactly one of the subschemas
+        any_of: 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
+        additional_properties: 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.
@@ -86,10 +77,10 @@ class Schema:
         # 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
+        read_only: Relevant only for Schema "properties" definitions - sent in response but not in request
+        write_only: Relevant only for Schema "properties" definitions - sent in request but not in response
         xml: Additional metadata for XML representations
-        externalDocs: Additional external documentation
+        external_docs: Additional external documentation
         example: Example of the media type
         deprecated: Specifies that the schema is deprecated
 
@@ -100,31 +91,37 @@ class Schema:
 
     # JSON Schema Core validation keywords
     title: FieldSource[str] | None = fixed_field()
-    multipleOf: FieldSource[int | float] | None = fixed_field()
+    multiple_of: FieldSource[int | float] | None = fixed_field(metadata={"yaml_name": "multipleOf"})
     maximum: FieldSource[int | float] | None = fixed_field()
-    exclusiveMaximum: FieldSource[bool] | None = fixed_field()
+    exclusive_maximum: FieldSource[bool] | None = fixed_field(
+        metadata={"yaml_name": "exclusiveMaximum"}
+    )
     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()
+    exclusive_minimum: FieldSource[bool] | None = fixed_field(
+        metadata={"yaml_name": "exclusiveMinimum"}
+    )
+    max_length: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "maxLength"})
+    min_length: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "minLength"})
     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()
+    max_items: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "maxItems"})
+    min_items: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "minItems"})
+    unique_items: FieldSource[bool] | None = fixed_field(metadata={"yaml_name": "uniqueItems"})
+    max_properties: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "maxProperties"})
+    min_properties: FieldSource[int] | None = fixed_field(metadata={"yaml_name": "minProperties"})
     required: FieldSource[list[ValueSource[str]]] | None = fixed_field()
     enum: FieldSource[list[ValueSource[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()
+    all_of: FieldSource[list[NestedSchema]] | None = fixed_field(metadata={"yaml_name": "allOf"})
+    one_of: FieldSource[list[NestedSchema]] | None = fixed_field(metadata={"yaml_name": "oneOf"})
+    any_of: FieldSource[list[NestedSchema]] | None = fixed_field(metadata={"yaml_name": "anyOf"})
     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()
+    properties: FieldSource[dict[KeySource[str], NestedSchema]] | None = fixed_field()
+    additional_properties: FieldSource["bool | NestedSchema"] | None = fixed_field(
+        metadata={"yaml_name": "additionalProperties"}
+    )
 
     # JSON Schema Metadata
     description: FieldSource[str] | None = fixed_field()
@@ -134,10 +131,12 @@ class Schema:
     # 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()
+    read_only: FieldSource[bool] | None = fixed_field(metadata={"yaml_name": "readOnly"})
+    write_only: FieldSource[bool] | None = fixed_field(metadata={"yaml_name": "writeOnly"})
     xml: FieldSource[XML] | None = fixed_field()
-    externalDocs: FieldSource[ExternalDocumentation] | None = fixed_field()
+    external_docs: FieldSource[ExternalDocumentation] | None = fixed_field(
+        metadata={"yaml_name": "externalDocs"}
+    )
     example: FieldSource[YAMLValue] | None = fixed_field()
     deprecated: FieldSource[bool] | None = fixed_field()
 
@@ -153,8 +152,8 @@ def build(
     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
+    Note: Schema is self-referential (can contain other Schema objects in all_of, one_of, any_of, not_,
+    items, properties, additional_properties). The builder handles nested Schema objects by preserving
     them as raw YAML values, letting validation layers interpret them.
 
     Args:
@@ -172,11 +171,9 @@ def build(
         root = yaml.compose("type: string\\nminLength: 1\\nmaxLength: 100")
         schema = build(root)
         assert schema.type.value == 'string'
-        assert schema.minLength.value == 1
+        assert schema.min_length.value == 1
     """
-    # Initialize context once at the beginning
-    if context is None:
-        context = Context()
+    context = context or Context()
 
     if not isinstance(root, yaml.MappingNode):
         # Preserve invalid root data instead of returning None
@@ -216,10 +213,7 @@ def build(
             FieldSource[int | float],
             FieldSource[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
-            )
+            field_values[field_name] = build_field_source(key_node, value_node, context)
 
         # Handle list with ValueSource wrapping for each item (e.g., required, enum fields)
         elif field_type_args & {
@@ -236,32 +230,26 @@ def build(
                 )
             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
-                )
+                field_values[field_name] = build_field_source(key_node, value_node, context)
 
         # 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)
+                    schema_or_reference = build_schema_or_reference(item_node, context)
+                    schemas.append(schema_or_reference)
                 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
-                )
+                field_values[field_name] = build_field_source(key_node, value_node, context)
         # Recursive schema single fields (not, items)
         elif key in ("not", "items"):
-            schema_or_ref = _build_schema_or_reference(value_node, context)
+            schema_or_reference = build_schema_or_reference(value_node, context)
             field_values[field_name] = FieldSource(
-                value=schema_or_ref, key_node=key_node, value_node=value_node
+                value=schema_or_reference, key_node=key_node, value_node=value_node
             )
         # additionalProperties (boolean | schema | reference)
         elif key == "additionalProperties":
@@ -270,36 +258,32 @@ def build(
                 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
-                )
+                field_values[field_name] = build_field_source(key_node, value_node, context)
             else:
                 # It's a schema or reference
-                schema_or_ref = _build_schema_or_reference(value_node, context)
+                schema_or_reference = build_schema_or_reference(value_node, context)
                 field_values[field_name] = FieldSource(
-                    value=schema_or_ref, key_node=key_node, value_node=value_node
+                    value=schema_or_reference, key_node=key_node, value_node=value_node
                 )
-        # properties (dict[KeySource[str], ValueSource[NestedSchema]])
+        # properties (dict[KeySource[str], NestedSchema])
         elif key == "properties":
             if isinstance(value_node, yaml.MappingNode):
-                properties_dict: dict[KeySource[str], ValueSource[NestedSchema]] = {}
+                properties_dict: dict[KeySource[str], 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)
+                    prop_schema_or_reference: NestedSchema = 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)
+                        prop_schema_or_reference
                     )
                 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
-                )
+                field_values[field_name] = build_field_source(key_node, value_node, context)
         # Nested objects (discriminator, xml, externalDocs)
         elif key == "discriminator":
             field_values[field_name] = FieldSource(
@@ -328,7 +312,7 @@ def build(
     )
 
 
-def _build_schema_or_reference(node: yaml.Node, context: Context) -> NestedSchema:
+def build_schema_or_reference(node: yaml.Node, context: Context) -> NestedSchema:
     """
     Build either a Schema or Reference from a YAML node.
 

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

@@ -3,9 +3,9 @@ from dataclasses import dataclass
 from ruamel import yaml
 from ruamel.yaml import MappingNode, SequenceNode
 
-from jentic.apitools.openapi.datamodels.low.context import Context
-from jentic.apitools.openapi.datamodels.low.fields import patterned_field
-from jentic.apitools.openapi.datamodels.low.sources import KeySource, ValueSource
+from ..context import Context
+from ..fields import patterned_field
+from ..sources import KeySource, ValueSource, YAMLInvalidValue
 
 
 __all__ = ["SecurityRequirement", "build"]
@@ -38,7 +38,9 @@ class SecurityRequirement:
     )
 
 
-def build(root: yaml.Node, context: Context | None = None) -> SecurityRequirement | None:
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> SecurityRequirement | ValueSource[YAMLInvalidValue]:
     """
     Build a SecurityRequirement object from a YAML node.
 
@@ -50,7 +52,9 @@ def build(root: yaml.Node, context: Context | None = None) -> SecurityRequiremen
         context: Optional parsing context. If None, a default context will be created.
 
     Returns:
-        A SecurityRequirement object if the node is valid, None otherwise
+        A SecurityRequirement 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
@@ -59,11 +63,12 @@ def build(root: yaml.Node, context: Context | None = None) -> SecurityRequiremen
         security_req = build(root)
         assert security_req.requirements is not None
     """
-    if not isinstance(root, MappingNode):
-        return None
+    context = context or Context()
 
-    if context is None:
-        context = Context()
+    if not isinstance(root, 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)
 
     requirements_dict: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = {}
 

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

@@ -2,21 +2,17 @@ from dataclasses import dataclass, field, replace
 
 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.oauth_flows import OAuthFlows
-from jentic.apitools.openapi.datamodels.low.v30.oauth_flows import build as build_oauth_flows
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .oauth_flows import OAuthFlows
+from .oauth_flows import build as build_oauth_flows
+from .reference import Reference
+from .reference import build as build_reference
 
 
-__all__ = ["SecurityScheme", "build"]
+__all__ = ["SecurityScheme", "build", "build_security_scheme_or_reference"]
 
 
 @dataclass(frozen=True, slots=True)
@@ -79,18 +75,15 @@ def build(
         security_scheme = build(root)
         assert security_scheme.type.value == 'apiKey'
     """
-    # Initialize context once at the beginning
-    if context is None:
-        context = Context()
+    context = context or 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
+    # Use build_model for initial construction
     security_scheme = build_model(root, SecurityScheme, context=context)
 
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(security_scheme, SecurityScheme):
+        return security_scheme
+
     # 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)
@@ -107,3 +100,30 @@ def build(
             break
 
     return security_scheme
+
+
+def build_security_scheme_or_reference(
+    node: yaml.Node, context: Context
+) -> SecurityScheme | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a SecurityScheme or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a SecurityScheme object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A SecurityScheme, 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 SecurityScheme
+    return build(node, context)

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

@@ -0,0 +1,111 @@
+from dataclasses import dataclass, field, replace
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_field_source, build_model
+from .server_variable import ServerVariable
+from .server_variable import build as build_server_variable
+
+
+__all__ = ["Server", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Server:
+    """
+    Server Object representation for OpenAPI 3.0.
+
+    An object representing a Server.
+
+    Attributes:
+        root_node: The top-level node representing the entire Server object in the original source file
+        url: REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
+        description: An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+        variables: A map between a variable name and its value. The value is used for substitution in the server's URL template.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    url: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    variables: FieldSource[dict[KeySource[str], ServerVariable]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Server | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Server 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 Server 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('''
+        url: https://{environment}.example.com/api/v1
+        description: Production API server
+        variables:
+          environment:
+            default: production
+            enum:
+              - production
+              - staging
+              - development
+            description: The deployment environment
+        ''')
+        server = build(root)
+        assert server.url.value == 'https://{environment}.example.com/api/v1'
+        assert server.description.value == 'Production API server'
+        assert 'environment' in {k.value for k in server.variables.value.keys()}
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    server = build_model(root, Server, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(server, Server):
+        return server
+
+    # Manually handle nested variables field
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "variables":
+            # Handle variables field - map of ServerVariable objects
+            if isinstance(value_node, yaml.MappingNode):
+                variables_dict: dict[
+                    KeySource[str], ServerVariable | ValueSource[YAMLInvalidValue]
+                ] = {}
+                for var_key_node, var_value_node in value_node.value:
+                    var_key = context.yaml_constructor.construct_yaml_str(var_key_node)
+                    # Build ServerVariable for each variable - child builder handles invalid nodes
+                    variables_dict[KeySource(value=var_key, key_node=var_key_node)] = (
+                        build_server_variable(var_value_node, context=context)
+                    )
+                variables = FieldSource(
+                    value=variables_dict, key_node=key_node, value_node=value_node
+                )
+                server = replace(server, variables=variables)
+            else:
+                # Not a mapping - preserve as-is for validation
+                variables = build_field_source(key_node, value_node, context)
+                server = replace(server, variables=variables)
+            break
+
+    return server