fork of hey-api/openapi-ts because I need some additional things
1# JSON Schema $Ref Parser
2
3#### Parse, Resolve, and Dereference JSON Schema $ref pointers
4
5## Installation
6
7Install using [npm](https://docs.npmjs.com/about-npm/):
8
9```bash
10npm add @hey-api/json-schema-ref-parser
11pnpm add @hey-api/json-schema-ref-parser
12yarn add @hey-api/json-schema-ref-parser
13bun add @hey-api/json-schema-ref-parser
14```
15
16## The Problem:
17
18You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead
19of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML
20format. Maybe some of the files contain cross-references to each other.
21
22```json
23{
24 "definitions": {
25 "person": {
26 // references an external file
27 "$ref": "schemas/people/Bruce-Wayne.json"
28 },
29 "place": {
30 // references a sub-schema in an external file
31 "$ref": "schemas/places.yaml#/definitions/Gotham-City"
32 },
33 "thing": {
34 // references a URL
35 "$ref": "http://wayne-enterprises.com/things/batmobile"
36 },
37 "color": {
38 // references a value in an external file via an internal reference
39 "$ref": "#/definitions/thing/properties/colors/black-as-the-night"
40 }
41 }
42}
43```
44
45## The Solution:
46
47JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
48and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most
49complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward
50JavaScript objects.
51
52- Use **JSON** or **YAML** schemas — or even a mix of both!
53- Supports `$ref` pointers to external files and URLs, as well as custom sources such as databases
54- Can bundle multiple files into a single schema that only has _internal_ `$ref` pointers
55- Can dereference your schema, producing a plain-old JavaScript object that's easy to work with
56- Supports circular references, nested references,
57 back-references, and cross-references between files
58- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object
59 instance
60- Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux
61
62### New in this fork (@hey-api)
63
64- **Multiple inputs with `bundleMany`**: Merge and bundle several OpenAPI/JSON Schema inputs (files, URLs, or raw objects) into a single schema. Components are prefixed to avoid name collisions, paths are namespaced on conflict, and `$ref`s are rewritten accordingly.
65
66```javascript
67import { $RefParser } from '@hey-api/json-schema-ref-parser';
68
69const parser = new $RefParser();
70const merged = await parser.bundleMany({
71 pathOrUrlOrSchemas: [
72 './specs/a.yaml',
73 'https://example.com/b.yaml',
74 { openapi: '3.1.0', info: { title: 'Inline' }, paths: {} },
75 ],
76});
77
78// merged.components.* will contain prefixed names like a_<name>, b_<name>, etc.
79```
80
81- **Dereference hooks**: Fine-tune dereferencing with `excludedPathMatcher(path) => boolean` to skip subpaths and `onDereference(path, value, parent, parentPropName)` to observe replacements.
82
83```javascript
84const parser = new $RefParser();
85parser.options.dereference.excludedPathMatcher = (p) => p.includes('/example/');
86parser.options.dereference.onDereference = (p, v) => {
87 // inspect p / v as needed
88};
89await parser.dereference({ pathOrUrlOrSchema: './openapi.yaml' });
90```
91
92- **Smart input resolution**: You can pass a file path, URL, or raw schema object. If a raw schema includes `$id`, it is used as the base URL for resolving relative `$ref`s.
93
94```javascript
95await new $RefParser().bundle({
96 pathOrUrlOrSchema: {
97 $id: 'https://api.example.com/openapi.json',
98 openapi: '3.1.0',
99 paths: {
100 '/ping': { get: { responses: { 200: { description: 'ok' } } } },
101 },
102 },
103});
104```