0
# Schema System
1

2
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.
3

4
## Capabilities
5

6
### Base Schema
7

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

10
```python { .api }
11
@dataclass
12
class Schema:
13
    type: DataType
14
    title: Optional[str] = None
15
    enum: Optional[list[Any]] = field(default_factory=list)
16
    example: Optional[Any] = None
17
    description: Optional[str] = None
18
    default: Optional[Any] = None
19
    nullable: Optional[bool] = field(default=False)
20
    read_only: Optional[bool] = field(default=False)
21
    write_only: Optional[bool] = field(default=False)
22
    deprecated: Optional[bool] = field(default=False)
23
    extensions: Optional[dict] = field(default_factory=dict)
24
```
25

26
**Properties:**
27
- `type`: Schema data type from DataType enum
28
- `title`: Schema title for documentation
29
- `enum`: List of allowed values for enumerated types
30
- `example`: Example value demonstrating valid data
31
- `description`: Human-readable description
32
- `default`: Default value when not provided
33
- `nullable`: Whether null values are allowed
34
- `read_only`: Whether the value is read-only (response only)
35
- `write_only`: Whether the value is write-only (request only)
36
- `deprecated`: Whether this schema is deprecated
37
- `extensions`: Custom schema extensions (x-* properties)
38

39
### Primitive Types
40

41
#### Integer Schema
42

43
Integer type with numeric validation constraints and format specifications.
44

45
```python { .api }
46
@dataclass
47
class Integer(Schema):
48
    multiple_of: Optional[int] = None
49
    maximum: Optional[int] = None
50
    exclusive_maximum: Optional[int] = None
51
    minimum: Optional[int] = None
52
    exclusive_minimum: Optional[int] = None
53
    format: Optional[Union[IntegerFormat, LooseIntegerFormat]] = None
54
```
55

56
**Properties:**
57
- `multiple_of`: Value must be multiple of this number
58
- `maximum`: Maximum allowed value (inclusive)
59
- `exclusive_maximum`: Maximum allowed value (exclusive)
60
- `minimum`: Minimum allowed value (inclusive)
61
- `exclusive_minimum`: Minimum allowed value (exclusive)
62
- `format`: Integer format (int32, int64) or custom format
63

64
#### Number Schema
65

66
Floating-point number type with numeric validation constraints.
67

68
```python { .api }
69
@dataclass
70
class Number(Schema):
71
    multiple_of: Optional[float] = None
72
    maximum: Optional[float] = None
73
    exclusive_maximum: Optional[float] = None
74
    minimum: Optional[float] = None
75
    exclusive_minimum: Optional[float] = None
76
    format: Optional[Union[NumberFormat, LooseNumberFormat]] = None
77
```
78

79
**Properties:**
80
- `multiple_of`: Value must be multiple of this number
81
- `maximum`: Maximum allowed value (inclusive)
82
- `exclusive_maximum`: Maximum allowed value (exclusive)
83
- `minimum`: Minimum allowed value (inclusive)
84
- `exclusive_minimum`: Minimum allowed value (exclusive)
85
- `format`: Number format (float, double) or custom format
86

87
#### String Schema
88

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

91
```python { .api }
92
@dataclass
93
class String(Schema):
94
    max_length: Optional[int] = None
95
    min_length: Optional[int] = None
96
    pattern: Optional[str] = None
97
    format: Optional[Union[StringFormat, LooseStringFormat]] = None
98
```
99

100
**Properties:**
101
- `max_length`: Maximum string length
102
- `min_length`: Minimum string length  
103
- `pattern`: Regular expression pattern for validation
104
- `format`: String format (date, email, uri, uuid, etc.) or custom format
105

106
#### Boolean Schema
107

108
Boolean type for true/false values.
109

110
```python { .api }
111
@dataclass
112
class Boolean(Schema):
113
    pass
114
```
115

116
#### Null Schema
117

118
Null type representing absence of value.
119

120
```python { .api }
121
@dataclass
122
class Null(Schema):
123
    pass
124
```
125

126
### Complex Types
127

128
#### Array Schema
129

130
Array type with item validation and size constraints.
131

132
```python { .api }
133
@dataclass
134
class Array(Schema):
135
    max_items: Optional[int] = None
136
    min_items: Optional[int] = None
137
    unique_items: Optional[bool] = None
138
    items: Schema = None
139
```
140

141
**Properties:**
142
- `max_items`: Maximum number of array items
143
- `min_items`: Minimum number of array items
144
- `unique_items`: Whether array items must be unique
145
- `items`: Schema for array items
146

147
#### Object Schema
148

149
Object type with property definitions and validation rules.
150

151
```python { .api }
152
@dataclass
153
class Object(Schema):
154
    max_properties: Optional[int] = None
155
    min_properties: Optional[int] = None
156
    required: list[str] = field(default_factory=list)
157
    properties: list[Property] = field(default_factory=list)
158
```
159

160
**Properties:**
161
- `max_properties`: Maximum number of object properties
162
- `min_properties`: Minimum number of object properties
163
- `required`: List of required property names
164
- `properties`: List of object property definitions
165

166
#### Property Definition
167

168
Individual property within an object schema.
169

170
```python { .api }
171
@dataclass
172
class Property:
173
    name: str
174
    schema: Schema
175
```
176

177
**Properties:**
178
- `name`: Property name
179
- `schema`: Schema definition for the property value
180

181
### Schema Composition
182

183
#### OneOf Schema
184

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

187
```python { .api }
188
@dataclass
189
class OneOf(Schema):
190
    schemas: list[Schema] = field(default_factory=list)
191
    discriminator: Optional[Discriminator] = None
192
```
193

194
**Properties:**
195
- `schemas`: List of schema options (exactly one must match)
196
- `discriminator`: Discriminator for polymorphic schema resolution
197

198
#### AnyOf Schema
199

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

202
```python { .api }
203
@dataclass
204
class AnyOf(Schema):
205
    schemas: list[Schema] = field(default_factory=list)
206
```
207

208
**Properties:**
209
- `schemas`: List of schema options (one or more must match)
210

211
#### Discriminator
212

213
Discriminator configuration for polymorphic schema inheritance.
214

215
```python { .api }
216
@dataclass
217
class Discriminator:
218
    property_name: str
219
    mapping: Optional[dict] = field(default_factory=dict)
220
```
221

222
**Properties:**
223
- `property_name`: Property name used for discrimination
224
- `mapping`: Mapping of discriminator values to schema names
225

226
### Usage Examples
227

228
Working with primitive schemas:
229
```python
230
from openapi_parser import parse
231

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

234
# Find schemas by type
235
for name, schema in spec.schemas.items():
236
    if isinstance(schema, String):
237
        print(f"String schema: {name}")
238
        if schema.format:
239
            print(f"  Format: {schema.format}")
240
        if schema.pattern:
241
            print(f"  Pattern: {schema.pattern}")
242
    
243
    elif isinstance(schema, Integer):
244
        print(f"Integer schema: {name}")
245
        if schema.minimum is not None:
246
            print(f"  Minimum: {schema.minimum}")
247
        if schema.maximum is not None:
248
            print(f"  Maximum: {schema.maximum}")
249
```
250

251
Working with object schemas:
252
```python
253
# Examine object properties
254
for name, schema in spec.schemas.items():
255
    if isinstance(schema, Object):
256
        print(f"Object schema: {name}")
257
        print(f"  Required properties: {schema.required}")
258
        
259
        for prop in schema.properties:
260
            print(f"  Property: {prop.name} ({prop.schema.type.value})")
261
```
262

263
Working with array schemas:
264
```python
265
# Check array item types
266
for name, schema in spec.schemas.items():
267
    if isinstance(schema, Array):
268
        print(f"Array schema: {name}")
269
        print(f"  Item type: {schema.items.type.value}")
270
        if schema.min_items:
271
            print(f"  Min items: {schema.min_items}")
272
        if schema.max_items:
273
            print(f"  Max items: {schema.max_items}")
274
```