0
# Specification Structure
1

2
The specification structure represents the root OpenAPI document and its core metadata components. This includes the main Specification container, API information, server configurations, and documentation references that define the overall API context.
3

4
## Capabilities
5

6
### Root Specification
7

8
The top-level container that holds the complete parsed OpenAPI specification with all its components.
9

10
```python { .api }
11
@dataclass
12
class Specification:
13
    version: str
14
    info: Info
15
    servers: list[Server] = field(default_factory=list)
16
    tags: list[Tag] = field(default_factory=list)
17
    security_schemas: dict[str, Security] = field(default_factory=dict)
18
    security: list[dict[str, Any]] = field(default_factory=list)
19
    schemas: dict[str, Schema] = field(default_factory=dict)
20
    external_docs: Optional[ExternalDoc] = None
21
    paths: list[Path] = field(default_factory=list)
22
    extensions: Optional[dict] = field(default_factory=dict)
23
```
24

25
**Properties:**
26
- `version`: OpenAPI specification version (e.g., "3.0.0")
27
- `info`: API metadata and information
28
- `servers`: List of server configurations where the API is hosted
29
- `paths`: API endpoints and their operations
30
- `security`: Global security requirements
31
- `tags`: Metadata for grouping operations
32
- `external_docs`: Reference to external documentation
33
- `security_schemas`: Reusable security scheme definitions
34
- `schemas`: Reusable schema components
35
- `extensions`: Custom extensions (x-* properties)
36

37
### API Information
38

39
Metadata about the API including title, version, description, and contact information.
40

41
```python { .api }
42
@dataclass
43
class Info:
44
    title: str
45
    version: str
46
    description: Optional[str] = None
47
    terms_of_service: Optional[str] = None
48
    contact: Optional[Contact] = None
49
    license: Optional[License] = None
50
    extensions: Optional[dict] = field(default_factory=dict)
51
```
52

53
**Properties:**
54
- `title`: API title/name (required)
55
- `version`: API version string (required)
56
- `description`: Detailed API description with CommonMark syntax support
57
- `terms_of_service`: URL to terms of service
58
- `contact`: Contact information for the API
59
- `license`: License information for the API
60
- `extensions`: Custom info extensions
61

62
### Contact Information
63

64
Contact details for the API maintainers or support team.
65

66
```python { .api }
67
@dataclass
68
class Contact:
69
    name: Optional[str] = None
70
    url: Optional[str] = None
71
    email: Optional[str] = None
72
```
73

74
**Properties:**
75
- `name`: Contact name/organization
76
- `url`: Contact website or support URL
77
- `email`: Contact email address
78

79
### License Information
80

81
Licensing information for the API.
82

83
```python { .api }
84
@dataclass
85
class License:
86
    name: str
87
    url: Optional[str] = None
88
    extensions: Optional[dict] = field(default_factory=dict)
89
```
90

91
**Properties:**
92
- `name`: License name (required)
93
- `url`: URL to the license text
94
- `extensions`: Custom license extensions
95

96
### Server Configuration
97

98
Server information specifying where the API is accessible.
99

100
```python { .api }
101
@dataclass
102
class Server:
103
    url: str
104
    description: Optional[str] = None
105
    variables: Optional[dict] = field(default_factory=dict)
106
    extensions: Optional[dict] = field(default_factory=dict)
107
```
108

109
**Properties:**
110
- `url`: Server URL template (required). May contain variables in {brackets}
111
- `description`: Human-readable server description
112
- `variables`: Variable definitions for URL template substitution
113
- `extensions`: Custom server extensions
114

115
### External Documentation
116

117
Reference to external documentation resources.
118

119
```python { .api }
120
@dataclass
121
class ExternalDoc:
122
    url: str
123
    description: Optional[str] = None
124
    extensions: Optional[dict] = field(default_factory=dict)
125
```
126

127
**Properties:**
128
- `url`: URL to external documentation (required)
129
- `description`: Description of the external documentation
130
- `extensions`: Custom external docs extensions
131

132
### Tags
133

134
Metadata for grouping and organizing API operations.
135

136
```python { .api }
137
@dataclass
138
class Tag:
139
    name: str
140
    description: Optional[str] = None
141
    external_docs: Optional[ExternalDoc] = None
142
```
143

144
**Properties:**
145
- `name`: Tag name (required)
146
- `description`: Tag description
147
- `external_docs`: Additional external documentation for this tag
148

149
### Usage Examples
150

151
Access API metadata:
152
```python
153
from openapi_parser import parse
154

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

157
# Basic API information
158
print(f"API: {spec.info.title} v{spec.info.version}")
159
print(f"Description: {spec.info.description}")
160

161
# Contact information
162
if spec.info.contact:
163
    contact = spec.info.contact
164
    print(f"Contact: {contact.name} ({contact.email})")
165

166
# License information  
167
if spec.info.license:
168
    print(f"License: {spec.info.license.name}")
169
```
170

171
Access server configurations:
172
```python
173
# List all servers
174
for server in spec.servers:
175
    print(f"Server: {server.url}")
176
    if server.description:
177
        print(f"  Description: {server.description}")
178
    
179
    # Server variables
180
    for var_name, var_def in (server.variables or {}).items():
181
        print(f"  Variable {var_name}: {var_def}")
182
```
183

184
Work with tags:
185
```python
186
# List all tags
187
for tag in spec.tags:
188
    print(f"Tag: {tag.name}")
189
    if tag.description:
190
        print(f"  Description: {tag.description}")
191
```