Schema System

The schema system provides comprehensive data model definitions for representing and validating data structures in OpenAPI specifications. It includes primitive types, complex objects, arrays, and composition schemas with validation constraints and format specifications.

Capabilities

Base Schema

The foundational schema class that all other schema types inherit from, providing common properties for validation and metadata.

@dataclass
class Schema:
    type: DataType
    title: Optional[str] = None
    enum: Optional[list[Any]] = field(default_factory=list)
    example: Optional[Any] = None
    description: Optional[str] = None
    default: Optional[Any] = None
    nullable: Optional[bool] = field(default=False)
    read_only: Optional[bool] = field(default=False)
    write_only: Optional[bool] = field(default=False)
    deprecated: Optional[bool] = field(default=False)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

• type: Schema data type from DataType enum
• title: Schema title for documentation
• enum: List of allowed values for enumerated types
• example: Example value demonstrating valid data
• description: Human-readable description
• default: Default value when not provided
• nullable: Whether null values are allowed
• read_only: Whether the value is read-only (response only)
• write_only: Whether the value is write-only (request only)
• deprecated: Whether this schema is deprecated
• extensions: Custom schema extensions (x-* properties)

Primitive Types

Integer Schema

Integer type with numeric validation constraints and format specifications.

@dataclass
class Integer(Schema):
    multiple_of: Optional[int] = None
    maximum: Optional[int] = None
    exclusive_maximum: Optional[int] = None
    minimum: Optional[int] = None
    exclusive_minimum: Optional[int] = None
    format: Optional[Union[IntegerFormat, LooseIntegerFormat]] = None

Properties:

• multiple_of: Value must be multiple of this number
• maximum: Maximum allowed value (inclusive)
• exclusive_maximum: Maximum allowed value (exclusive)
• minimum: Minimum allowed value (inclusive)
• exclusive_minimum: Minimum allowed value (exclusive)
• format: Integer format (int32, int64) or custom format

Number Schema

Floating-point number type with numeric validation constraints.

@dataclass
class Number(Schema):
    multiple_of: Optional[float] = None
    maximum: Optional[float] = None
    exclusive_maximum: Optional[float] = None
    minimum: Optional[float] = None
    exclusive_minimum: Optional[float] = None
    format: Optional[Union[NumberFormat, LooseNumberFormat]] = None

Properties:

• multiple_of: Value must be multiple of this number
• maximum: Maximum allowed value (inclusive)
• exclusive_maximum: Maximum allowed value (exclusive)
• minimum: Minimum allowed value (inclusive)
• exclusive_minimum: Minimum allowed value (exclusive)
• format: Number format (float, double) or custom format

String Schema

String type with length constraints, patterns, and format validation.

@dataclass
class String(Schema):
    max_length: Optional[int] = None
    min_length: Optional[int] = None
    pattern: Optional[str] = None
    format: Optional[Union[StringFormat, LooseStringFormat]] = None

Properties:

• max_length: Maximum string length
• min_length: Minimum string length
• pattern: Regular expression pattern for validation
• format: String format (date, email, uri, uuid, etc.) or custom format

Boolean Schema

Boolean type for true/false values.

@dataclass
class Boolean(Schema):
    pass

Null Schema

Null type representing absence of value.

@dataclass
class Null(Schema):
    pass

Complex Types

Array Schema

Array type with item validation and size constraints.

@dataclass
class Array(Schema):
    max_items: Optional[int] = None
    min_items: Optional[int] = None
    unique_items: Optional[bool] = None
    items: Schema = None

Properties:

• max_items: Maximum number of array items
• min_items: Minimum number of array items
• unique_items: Whether array items must be unique
• items: Schema for array items

Object Schema

Object type with property definitions and validation rules.

@dataclass
class Object(Schema):
    max_properties: Optional[int] = None
    min_properties: Optional[int] = None
    required: list[str] = field(default_factory=list)
    properties: list[Property] = field(default_factory=list)

Properties:

• max_properties: Maximum number of object properties
• min_properties: Minimum number of object properties
• required: List of required property names
• properties: List of object property definitions

Property Definition

Individual property within an object schema.

@dataclass
class Property:
    name: str
    schema: Schema

Properties:

• name: Property name
• schema: Schema definition for the property value

Schema Composition

OneOf Schema

Schema composition where data must match exactly one of the provided schemas.

@dataclass
class OneOf(Schema):
    schemas: list[Schema] = field(default_factory=list)
    discriminator: Optional[Discriminator] = None

Properties:

• schemas: List of schema options (exactly one must match)
• discriminator: Discriminator for polymorphic schema resolution

AnyOf Schema

Schema composition where data must match one or more of the provided schemas.

@dataclass
class AnyOf(Schema):
    schemas: list[Schema] = field(default_factory=list)

Properties:

• schemas: List of schema options (one or more must match)

Discriminator

Discriminator configuration for polymorphic schema inheritance.

@dataclass
class Discriminator:
    property_name: str
    mapping: Optional[dict] = field(default_factory=dict)

Properties:

• property_name: Property name used for discrimination
• mapping: Mapping of discriminator values to schema names

Usage Examples

Working with primitive schemas:

from openapi_parser import parse

spec = parse('api-spec.yml')

# Find schemas by type
for name, schema in spec.schemas.items():
    if isinstance(schema, String):
        print(f"String schema: {name}")
        if schema.format:
            print(f"  Format: {schema.format}")
        if schema.pattern:
            print(f"  Pattern: {schema.pattern}")
    
    elif isinstance(schema, Integer):
        print(f"Integer schema: {name}")
        if schema.minimum is not None:
            print(f"  Minimum: {schema.minimum}")
        if schema.maximum is not None:
            print(f"  Maximum: {schema.maximum}")

Working with object schemas:

# Examine object properties
for name, schema in spec.schemas.items():
    if isinstance(schema, Object):
        print(f"Object schema: {name}")
        print(f"  Required properties: {schema.required}")
        
        for prop in schema.properties:
            print(f"  Property: {prop.name} ({prop.schema.type.value})")

Working with array schemas:

# Check array item types
for name, schema in spec.schemas.items():
    if isinstance(schema, Array):
        print(f"Array schema: {name}")
        print(f"  Item type: {schema.items.type.value}")
        if schema.min_items:
            print(f"  Min items: {schema.min_items}")
        if schema.max_items:
            print(f"  Max items: {schema.max_items}")