0
# Core Processing
1

2
Core functionality for loading, initializing, and processing API definitions with comprehensive format support and flexible input handling.
3

4
## Capabilities
5

6
### OASNormalize Class
7

8
Main class that provides a unified interface for working with OpenAPI, Swagger, and Postman API definitions.
9

10
```typescript { .api }
11
/**
12
 * Main class for normalizing API definitions across multiple formats
13
 */
14
class OASNormalize {
15
  constructor(file: any, opts?: Options);
16
  
17
  // Instance properties
18
  cache: {
19
    bundle?: OpenAPI.Document | false;
20
    convert?: OpenAPI.Document | false;
21
    deref?: OpenAPI.Document | false;
22
    load?: Record<string, unknown> | false;
23
  };
24
  file: any;
25
  opts: Options;
26
  type: ReturnType<typeof getType>;
27
}
28

29
interface Options {
30
  /** Enable colorized validation errors (default: false) */
31
  colorizeErrors?: boolean;
32
  /** Allow local file path access for security (default: false) */
33
  enablePaths?: boolean;
34
  /** OpenAPI parser configuration options */
35
  parser?: ParserOptions;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import OASNormalize from "oas-normalize";
43

44
// Initialize with different input types
45
const oasFromURL = new OASNormalize('https://api.example.com/openapi.json');
46
const oasFromFile = new OASNormalize('./api-spec.yaml', { enablePaths: true });
47
const oasFromObject = new OASNormalize({ openapi: '3.0.0', info: { title: 'API' } });
48
const oasFromString = new OASNormalize('{"openapi": "3.0.0", "info": {"title": "API"}}');
49

50
// With options
51
const oas = new OASNormalize(apiSpec, {
52
  colorizeErrors: true,
53
  enablePaths: true,
54
  parser: {
55
    validate: {
56
      rules: {
57
        openapi: {
58
          'path-parameters-not-in-path': 'warning'
59
        }
60
      }
61
    }
62
  }
63
});
64
```
65

66
### Load Method
67

68
Load and retrieve the API definition that OAS Normalize was initialized with, resolving URLs and file paths as needed.
69

70
```typescript { .api }
71
/**
72
 * Load and return the API definition
73
 * Resolves URLs, file paths, and various input formats to a JSON object
74
 * @returns Promise resolving to the loaded API definition
75
 */
76
async load(): Promise<Record<string, unknown>>;
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
// Load from various sources
83
const oas = new OASNormalize('https://petstore.swagger.io/v2/swagger.json');
84
const definition = await oas.load();
85
console.log(definition.info.title); // "Swagger Petstore"
86

87
// Load from local file (requires enablePaths)
88
const oasLocal = new OASNormalize('./petstore.yaml', { enablePaths: true });
89
const localDef = await oasLocal.load();
90

91
// Load from JSON object (returns as-is)
92
const oasObj = new OASNormalize({ openapi: '3.0.0', info: { title: 'My API' } });
93
const objDef = await oasObj.load();
94

95
// Load from YAML string
96
const yamlString = `
97
openapi: 3.0.0
98
info:
99
  title: My API
100
  version: 1.0.0
101
`;
102
const oasYaml = new OASNormalize(yamlString);
103
const yamlDef = await oasYaml.load();
104
```
105

106
### Version Method
107

108
Retrieve specification type and version information about the supplied API definition.
109

110
```typescript { .api }
111
/**
112
 * Get version information about the API definition
113
 * @returns Promise resolving to specification type and version details
114
 */
115
async version(): Promise<{
116
  specification: 'openapi' | 'postman' | 'swagger';
117
  version: string | 'unknown';
118
}>;
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
// Check OpenAPI version
125
const oas = new OASNormalize(openapi31Spec);
126
const { specification, version } = await oas.version();
127
console.log(specification); // "openapi"
128
console.log(version); // "3.1.0"
129

130
// Check Swagger version
131
const swagger = new OASNormalize(swagger20Spec);
132
const swaggerInfo = await swagger.version();
133
console.log(swaggerInfo.specification); // "swagger"
134
console.log(swaggerInfo.version); // "2.0"
135

136
// Check Postman collection
137
const postman = new OASNormalize(postmanCollection);
138
const postmanInfo = await postman.version();
139
console.log(postmanInfo.specification); // "postman"
140
console.log(postmanInfo.version); // "2.1.0" or "unknown"
141
```
142

143
## Supported Input Types
144

145
### URLs (HTTP/HTTPS)
146

147
```typescript
148
const oas = new OASNormalize('https://api.example.com/openapi.json');
149
const oasWithAuth = new OASNormalize('https://user:pass@api.example.com/spec.yaml');
150
```
151

152
- Automatically handles GitHub blob URLs (converts to raw URLs)
153
- Supports basic authentication in URL
154
- Handles both JSON and YAML content types
155

156
### File Paths
157

158
```typescript
159
const oas = new OASNormalize('./api-spec.yaml', { enablePaths: true });
160
const oasAbsolute = new OASNormalize('/absolute/path/to/spec.json', { enablePaths: true });
161
```
162

163
- Requires `enablePaths: true` option for security
164
- Supports both relative and absolute paths
165
- Handles JSON and YAML files
166

167
### JSON Objects
168

169
```typescript
170
const spec = { openapi: '3.0.0', info: { title: 'My API' } };
171
const oas = new OASNormalize(spec);
172
```
173

174
- Direct JavaScript objects
175
- No additional processing required
176

177
### String Content
178

179
```typescript
180
// JSON strings
181
const jsonString = '{"openapi": "3.0.0", "info": {"title": "API"}}';
182
const oasJson = new OASNormalize(jsonString);
183

184
// YAML strings
185
const yamlString = 'openapi: 3.0.0\ninfo:\n  title: API';
186
const oasYaml = new OASNormalize(yamlString);
187
```
188

189
- Automatically detects JSON vs YAML format
190
- Parses content appropriately
191

192
### Buffer Objects
193

194
```typescript
195
import fs from 'fs';
196
const buffer = fs.readFileSync('./api-spec.yaml');
197
const oas = new OASNormalize(buffer);
198
```
199

200
- Converts buffer to string and processes as YAML/JSON
201
- Useful for programmatic file handling
202

203
## Security Considerations
204

205
### Local File Access
206

207
Local file path access is disabled by default for security reasons:
208

209
```typescript
210
// This will throw an error
211
const oas = new OASNormalize('./local-file.yaml');
212
await oas.load(); // Error: Use `opts.enablePaths` to enable accessing local files.
213

214
// Enable with explicit option
215
const oasSafe = new OASNormalize('./local-file.yaml', { enablePaths: true });
216
await oasSafe.load(); // Works
217
```
218

219
### Reference Resolution Security
220

221
When `enablePaths` is disabled, external file references in $ref pointers are blocked:
222

223
```typescript
224
const specWithRef = {
225
  openapi: '3.0.0',
226
  paths: {
227
    '/': {
228
      get: {
229
        parameters: [{
230
          schema: { $ref: '/etc/passwd' }  // This will be blocked
231
        }]
232
      }
233
    }
234
  }
235
};
236

237
const oas = new OASNormalize(specWithRef, { enablePaths: false });
238
await oas.validate(); // Will throw error about unable to resolve $ref
239
```