0
# Type System and Enums
1

2
The type system provides enumeration classes that define allowed values for various OpenAPI specification fields. These enums ensure type safety and provide validation constraints for data types, formats, HTTP methods, parameter locations, content types, and security configurations.
3

4
## Capabilities
5

6
### Schema Data Types
7

8
Defines the fundamental data types available for OpenAPI schemas.
9

10
```python { .api }
11
class DataType(Enum):
12
    NULL = "null"
13
    INTEGER = "integer"
14
    NUMBER = "number"
15
    STRING = "string"
16
    BOOLEAN = "boolean"
17
    ARRAY = "array"
18
    OBJECT = "object"
19
    ONE_OF = "oneOf"
20
    ANY_OF = "anyOf"
21
```
22

23
**Values:**
24
- `NULL`: Null/none type
25
- `INTEGER`: Whole numbers
26
- `NUMBER`: Floating-point numbers
27
- `STRING`: Text values
28
- `BOOLEAN`: True/false values
29
- `ARRAY`: Ordered collections
30
- `OBJECT`: Key-value structures
31
- `ONE_OF`: Exactly one schema must match
32
- `ANY_OF`: One or more schemas must match
33

34
### Format Types
35

36
#### Integer Formats
37

38
Standard format specifications for integer values.
39

40
```python { .api }
41
class IntegerFormat(Enum):
42
    INT32 = "int32"
43
    INT64 = "int64"
44
```
45

46
**Values:**
47
- `INT32`: Signed 32-bit integer (-2³¹ to 2³¹-1)
48
- `INT64`: Signed 64-bit integer (-2⁶³ to 2⁶³-1)
49

50
#### Number Formats
51

52
Standard format specifications for floating-point numbers.
53

54
```python { .api }
55
class NumberFormat(Enum):
56
    FLOAT = "float"
57
    DOUBLE = "double"
58
```
59

60
**Values:**
61
- `FLOAT`: Single-precision floating-point
62
- `DOUBLE`: Double-precision floating-point
63

64
#### String Formats
65

66
Format specifications for string validation and interpretation.
67

68
```python { .api }
69
class StringFormat(Enum):
70
    BYTE = "byte"
71
    BINARY = "binary"
72
    DATE = "date"
73
    DATETIME = "date-time"
74
    PASSWORD = "password"
75
    UUID = "uuid"
76
    UUID4 = "uuid4"
77
    EMAIL = "email"
78
    URI = "uri"
79
    HOSTNAME = "hostname"
80
    IPV4 = "ipv4"
81
    IPV6 = "ipv6"
82
    URL = "url"
83
```
84

85
**Values:**
86
- `BYTE`: Base64-encoded binary data
87
- `BINARY`: Binary data
88
- `DATE`: Full-date (RFC 3339, e.g., "2023-12-25")
89
- `DATETIME`: Date-time (RFC 3339, e.g., "2023-12-25T10:30:00Z")
90
- `PASSWORD`: Password input (UI hint)
91
- `UUID`: Universally unique identifier
92
- `UUID4`: UUID version 4 specifically
93
- `EMAIL`: Email address
94
- `URI`: Universal resource identifier
95
- `HOSTNAME`: Internet hostname
96
- `IPV4`: IPv4 address
97
- `IPV6`: IPv6 address
98
- `URL`: Universal resource locator
99

100
### HTTP Operations
101

102
Defines the supported HTTP methods for API operations.
103

104
```python { .api }
105
class OperationMethod(Enum):
106
    GET = "get"
107
    PUT = "put"
108
    POST = "post"
109
    DELETE = "delete"
110
    OPTIONS = "options"
111
    HEAD = "head"
112
    PATCH = "patch"
113
    TRACE = "trace"
114
```
115

116
**Values:**
117
- `GET`: Retrieve resource
118
- `PUT`: Update/replace resource
119
- `POST`: Create resource or submit data
120
- `DELETE`: Remove resource
121
- `OPTIONS`: Get allowed methods
122
- `HEAD`: Get headers only
123
- `PATCH`: Partial update
124
- `TRACE`: Diagnostic trace
125

126
### Parameter Locations
127

128
#### Base Location
129

130
Base locations for security parameters.
131

132
```python { .api }
133
class BaseLocation(Enum):
134
    HEADER = "header"
135
    QUERY = "query"
136
    COOKIE = "cookie"
137
```
138

139
#### Parameter Location
140

141
All supported parameter locations including path parameters.
142

143
```python { .api }
144
class ParameterLocation(Enum):
145
    HEADER = "header"
146
    QUERY = "query"
147
    COOKIE = "cookie"
148
    PATH = "path"
149
```
150

151
**Values:**
152
- `HEADER`: HTTP header parameter
153
- `QUERY`: URL query string parameter
154
- `COOKIE`: HTTP cookie parameter
155
- `PATH`: URL path parameter
156

157
### Parameter Styles
158

159
#### Path Parameter Styles
160

161
Serialization styles for path parameters.
162

163
```python { .api }
164
class PathParameterStyle(Enum):
165
    SIMPLE = "simple"
166
    LABEL = "label"
167
    MATRIX = "matrix"
168
```
169

170
**Values:**
171
- `SIMPLE`: Simple comma-separated values
172
- `LABEL`: Dot-prefixed values
173
- `MATRIX`: Semicolon-prefixed key-value pairs
174

175
#### Query Parameter Styles
176

177
Serialization styles for query parameters.
178

179
```python { .api }
180
class QueryParameterStyle(Enum):
181
    FORM = "form"
182
    SPACE_DELIMITED = "spaceDelimited"
183
    PIPE_DELIMITED = "pipeDelimited"
184
    DEEP_OBJECT = "deepObject"
185
```
186

187
**Values:**
188
- `FORM`: Form-style serialization
189
- `SPACE_DELIMITED`: Space-separated values
190
- `PIPE_DELIMITED`: Pipe-separated values
191
- `DEEP_OBJECT`: Deep object serialization
192

193
#### Header Parameter Styles
194

195
Serialization styles for header parameters.
196

197
```python { .api }
198
class HeaderParameterStyle(Enum):
199
    SIMPLE = "simple"
200
```
201

202
#### Cookie Parameter Styles
203

204
Serialization styles for cookie parameters.
205

206
```python { .api }
207
class CookieParameterStyle(Enum):
208
    FORM = "form"
209
```
210

211
### Content Types
212

213
Standard MIME content types for request and response bodies.
214

215
```python { .api }
216
class ContentType(Enum):
217
    JSON = "application/json"
218
    JSON_TEXT = "text/json"
219
    JSON_ANY = "application/*+json"
220
    JSON_PROBLEM = "application/problem+json"
221
    XML = "application/xml"
222
    FORM = "application/x-www-form-urlencoded"
223
    MULTIPART_FORM = "multipart/form-data"
224
    PLAIN_TEXT = "text/plain"
225
    HTML = "text/html"
226
    PDF = "application/pdf"
227
    PNG = "image/png"
228
    JPEG = "image/jpeg"
229
    GIF = "image/gif"
230
    SVG = "image/svg+xml"
231
    AVIF = "image/avif"
232
    BMP = "image/bmp"
233
    WEBP = "image/webp"
234
    Image = "image/*"
235
    BINARY = "application/octet-stream"
236
```
237

238
### Security Types
239

240
Security scheme types for API authentication.
241

242
```python { .api }
243
class SecurityType(Enum):
244
    API_KEY = "apiKey"
245
    HTTP = "http"
246
    OAUTH2 = "oauth2"
247
    OPEN_ID_CONNECT = "openIdConnect"
248
```
249

250
**Values:**
251
- `API_KEY`: API key authentication
252
- `HTTP`: HTTP authentication schemes
253
- `OAUTH2`: OAuth 2.0 authentication
254
- `OPEN_ID_CONNECT`: OpenID Connect authentication
255

256
#### Authentication Schemes
257

258
HTTP authentication schemes for security configurations.
259

260
```python { .api }
261
class AuthenticationScheme(Enum):
262
    BASIC = "basic"
263
    BEARER = "bearer"
264
    DIGEST = "digest"
265
    HOBA = "hoba"
266
    MUTUAL = "mutual"
267
    NEGOTIATE = "negotiate"
268
    OAUTH = "oauth"
269
    SCRAM_SHA1 = "scram-sha-1"
270
    SCRAM_SHA256 = "scram-sha-256"
271
    VAPID = "vapid"
272
```
273

274
#### OAuth Flow Types
275

276
OAuth 2.0 flow types for authentication configuration.
277

278
```python { .api }
279
class OAuthFlowType(Enum):
280
    IMPLICIT = "implicit"
281
    PASSWORD = "password"
282
    CLIENT_CREDENTIALS = "clientCredentials"
283
    AUTHORIZATION_CODE = "authorizationCode"
284
```
285

286
**Values:**
287
- `IMPLICIT`: Implicit grant flow
288
- `PASSWORD`: Resource owner password credentials flow
289
- `CLIENT_CREDENTIALS`: Client credentials grant flow
290
- `AUTHORIZATION_CODE`: Authorization code grant flow
291

292
### Loose Types
293

294
For compatibility with non-standard specifications, the library provides loose type definitions that allow custom values beyond the standard enums:
295

296
```python { .api }
297
@dataclass
298
class LooseEnum:
299
    """Container for non-standard enum values"""
300
    value: str
301

302
# Type aliases for loose validation (all are aliases to LooseEnum)
303
LooseContentType = LooseEnum
304
LooseIntegerFormat = LooseEnum
305
LooseNumberFormat = LooseEnum  
306
LooseStringFormat = LooseEnum
307
```
308

309
### Usage Examples
310

311
Working with enums:
312
```python
313
from openapi_parser import parse
314
from openapi_parser.enumeration import DataType, OperationMethod, ContentType
315

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

318
# Check data types in schemas
319
for name, schema in (spec.schemas or {}).items():
320
    print(f"Schema {name}: {schema.type.value}")
321
    
322
    # Type-specific handling
323
    if schema.type == DataType.STRING:
324
        print(f"  String schema with format: {getattr(schema, 'format', 'none')}")
325
    elif schema.type == DataType.ARRAY:
326
        print(f"  Array with item type: {schema.items.type.value}")
327

328
# List HTTP methods used
329
methods_used = set()
330
for path in spec.paths:
331
    for operation in path.operations:
332
        methods_used.add(operation.method)
333

334
print("HTTP methods used:")
335
for method in sorted(methods_used, key=lambda m: m.value):
336
    print(f"  {method.value.upper()}")
337

338
# Find content types
339
content_types_used = set()
340
for path in spec.paths:
341
    for operation in path.operations:
342
        if operation.request_body:
343
            for content in operation.request_body.content:
344
                if isinstance(content.type, ContentType):
345
                    content_types_used.add(content.type.value)
346

347
print("Content types used:")
348
for ct in sorted(content_types_used):
349
    print(f"  {ct}")
350
```
351

352
Enum validation and loose types:
353
```python
354
# With strict enum validation (default)
355
spec_strict = parse('api-spec.yml', strict_enum=True)
356

357
# With loose enum validation (allows custom values)
358
spec_loose = parse('api-spec.yml', strict_enum=False)
359

360
# Check for loose types
361
for path in spec_loose.paths:
362
    for operation in path.operations:
363
        if operation.request_body:
364
            for content in operation.request_body.content:
365
                if isinstance(content.type, str):
366
                    print(f"Custom content type: {content.type}")
367
```