0
# OAS Normalize
1

2
OAS Normalize is a comprehensive TypeScript library that provides tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions. It offers a unified interface for handling diverse API specification formats with robust error handling, automatic format conversion, and built-in validation capabilities.
3

4
## Package Information
5

6
- **Package Name**: oas-normalize
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install oas-normalize`
10

11
## Core Imports
12

13
```typescript
14
import OASNormalize from "oas-normalize";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const OASNormalize = require("oas-normalize");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import OASNormalize from "oas-normalize";
27

28
// Initialize with API definition (URL, file path, JSON object, etc.)
29
const oas = new OASNormalize(
30
  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml'
31
);
32

33
// Validate the API definition
34
try {
35
  await oas.validate();
36
  console.log('API definition is valid!');
37
} catch (error) {
38
  console.error('Validation failed:', error.message);
39
}
40

41
// Convert to OpenAPI format
42
const openapi = await oas.convert();
43

44
// Bundle external references
45
const bundled = await oas.bundle();
46

47
// Dereference all $ref pointers
48
const dereferenced = await oas.dereference();
49
```
50

51
## Architecture
52

53
OAS Normalize is built around several key components:
54

55
- **Multi-format Support**: Handles OpenAPI 3.x, Swagger 2.0, and Postman collections seamlessly
56
- **Input Flexibility**: Accepts various input types including URLs, file paths, JSON objects, YAML strings, and Buffers
57
- **Automatic Conversion**: Converts Swagger 2.0 and Postman collections to OpenAPI 3.x format
58
- **Reference Resolution**: Bundles external $ref pointers and provides full dereferencing capabilities
59
- **Validation Engine**: Comprehensive validation with detailed error reporting and customizable rulesets
60
- **Caching System**: Built-in caching for improved performance on repeated operations
61

62
## Capabilities
63

64
### Core Processing
65

66
Main class for loading, processing, and manipulating API definitions with comprehensive format support and validation.
67

68
```typescript { .api }
69
class OASNormalize {
70
  constructor(file: any, opts?: Options);
71
  
72
  // Load the original API definition
73
  async load(): Promise<Record<string, unknown>>;
74
  
75
  // Get specification type and version information
76
  async version(): Promise<{
77
    specification: 'openapi' | 'postman' | 'swagger';
78
    version: string | 'unknown';
79
  }>;
80
}
81

82
interface Options {
83
  colorizeErrors?: boolean;
84
  enablePaths?: boolean;
85
  parser?: ParserOptions;
86
}
87
```
88

89
[Core Processing](./core-processing.md)
90

91
### Format Conversion
92

93
Automatic conversion capabilities for transforming Swagger and Postman collections to OpenAPI format.
94

95
```typescript { .api }
96
class OASNormalize {
97
  // Convert API definition to OpenAPI format
98
  async convert(): Promise<OpenAPI.Document>;
99
}
100
```
101

102
[Format Conversion](./format-conversion.md)
103

104
### Reference Resolution
105

106
Advanced reference resolution for bundling external $ref pointers and dereferencing all references inline.
107

108
```typescript { .api }
109
class OASNormalize {
110
  // Bundle external $ref pointers
111
  async bundle(): Promise<OpenAPI.Document>;
112
  
113
  // Dereference all $ref pointers inline
114
  async dereference(): Promise<OpenAPI.Document>;
115
  
116
  // Deprecated alias for dereference
117
  async deref(): Promise<OpenAPI.Document>;
118
}
119
```
120

121
[Reference Resolution](./reference-resolution.md)
122

123
### Validation
124

125
Comprehensive validation system with detailed error reporting, contextual messages, and customizable validation rules.
126

127
```typescript { .api }
128
class OASNormalize {
129
  // Validate API definition with detailed error reporting
130
  async validate(opts?: {
131
    parser?: ParserOptions;
132
  }): Promise<ValidationResult>;
133
}
134

135
interface ValidationResult {
136
  valid: boolean;
137
  warnings: WarningDetails[];
138
  errors: ErrorDetails[];
139
}
140
```
141

142
[Validation](./validation.md)
143

144
### Error Handling
145

146
Custom error classes and utility functions for managing validation errors and compilation.
147

148
```typescript { .api }
149
class ValidationError extends Error {
150
  constructor(message: string);
151
  name: 'ValidationError';
152
}
153

154
// Utility functions
155
function compileErrors(result: ValidationResult): string;
156
```
157

158
[Error Handling](./error-handling.md)
159

160
### Utility Functions
161

162
Helper functions for type detection, schema validation, and input processing.
163

164
```typescript { .api }
165
// Type detection and validation
166
function getType(obj: any): 'buffer' | 'json' | 'path' | 'string-json' | 'string-yaml' | 'url' | false;
167
function isOpenAPI(schema: Record<string, unknown>): boolean;
168
function isSwagger(schema: Record<string, unknown>): boolean;
169
function isPostman(schema: Record<string, unknown>): boolean;
170
function isAPIDefinition(schema: Record<string, unknown>): boolean;
171
function getAPIDefinitionType(schema: Record<string, unknown>): 'openapi' | 'postman' | 'swagger' | 'unknown';
172

173
// Data processing utilities
174
function stringToJSON(string: Record<string, unknown> | string): Record<string, unknown>;
175
function prepareURL(url: string): { options: RequestInit; url: string };
176
function isBuffer(obj: any): boolean;
177
```
178

179
[Utility Functions](./utility-functions.md)