feat: bring json-schema-ref-parser in-house

Author: mrlubos

.changeset/slick-queens-buy.md

@@ -0,0 +1,5 @@
+---
+"@hey-api/json-schema-ref-parser": minor
+---
+
+**feat**: clean up dependencies

dev/inputs.ts

@@ -9,6 +9,7 @@ export const inputs = {
   opencode: path.resolve(getSpecsPath(), '3.1.x', 'opencode.yaml'),
   petstore:
     'https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml',
+  redfish: 'http://redfish.dmtf.org/schemas/v1/Message.v1_2_1.yaml',
   scalar: 'scalar:@scalar/access-service',
   transformers: path.resolve(getSpecsPath(), '3.1.x', 'transformers.json'),
   validators: path.resolve(getSpecsPath(), '3.1.x', 'validators.yaml'),

packages/json-schema-ref-parser/README.md

@@ -0,0 +1,117 @@
+# JSON Schema $Ref Parser
+
+#### Parse, Resolve, and Dereference JSON Schema $ref pointers
+
+## Installation
+
+Install using [npm](https://docs.npmjs.com/about-npm/):
+
+```bash
+npm install @hey-api/json-schema-ref-parser
+yarn add @hey-api/json-schema-ref-parser
+bun add @hey-api/json-schema-ref-parser
+```
+
+## The Problem:
+
+You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead
+of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML
+format. Maybe some of the files contain cross-references to each other.
+
+```json
+{
+  "definitions": {
+    "person": {
+      // references an external file
+      "$ref": "schemas/people/Bruce-Wayne.json"
+    },
+    "place": {
+      // references a sub-schema in an external file
+      "$ref": "schemas/places.yaml#/definitions/Gotham-City"
+    },
+    "thing": {
+      // references a URL
+      "$ref": "http://wayne-enterprises.com/things/batmobile"
+    },
+    "color": {
+      // references a value in an external file via an internal reference
+      "$ref": "#/definitions/thing/properties/colors/black-as-the-night"
+    }
+  }
+}
+```
+
+## The Solution:
+
+JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
+and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most
+complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward
+JavaScript objects.
+
+- Use **JSON** or **YAML** schemas — or even a mix of both!
+- Supports `$ref` pointers to external files and URLs, as well as custom sources such as databases
+- Can bundle multiple files into a single schema that only has _internal_ `$ref` pointers
+- Can dereference your schema, producing a plain-old JavaScript object that's easy to work with
+- Supports circular references, nested references,
+  back-references, and cross-references between files
+- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object
+  instance
+- Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux
+
+## Example
+
+```javascript
+import { $RefParser } from '@hey-api/json-schema-ref-parser';
+
+try {
+  const parser = new $RefParser();
+  await parser.dereference({ pathOrUrlOrSchema: mySchema });
+  console.log(parser.schema.definitions.person.properties.firstName);
+} catch (err) {
+  console.error(err);
+}
+```
+
+### New in this fork (@hey-api)
+
+- **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.
+
+```javascript
+import { $RefParser } from '@hey-api/json-schema-ref-parser';
+
+const parser = new $RefParser();
+const merged = await parser.bundleMany({
+  pathOrUrlOrSchemas: [
+    './specs/a.yaml',
+    'https://example.com/b.yaml',
+    { openapi: '3.1.0', info: { title: 'Inline' }, paths: {} },
+  ],
+});
+
+// merged.components.* will contain prefixed names like a_<name>, b_<name>, etc.
+```
+
+- **Dereference hooks**: Fine-tune dereferencing with `excludedPathMatcher(path) => boolean` to skip subpaths and `onDereference(path, value, parent, parentPropName)` to observe replacements.
+
+```javascript
+const parser = new $RefParser();
+parser.options.dereference.excludedPathMatcher = (p) => p.includes('/example/');
+parser.options.dereference.onDereference = (p, v) => {
+  // inspect p / v as needed
+};
+await parser.dereference({ pathOrUrlOrSchema: './openapi.yaml' });
+```
+
+- **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.
+
+```javascript
+await new $RefParser().bundle({
+  pathOrUrlOrSchema: {
+    $id: 'https://api.example.com/openapi.json',
+    openapi: '3.1.0',
+    paths: {
+      '/ping': { get: { responses: { 200: { description: 'ok' } } } },
+    },
+  },
+});
+```

packages/json-schema-ref-parser/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@hey-api/json-schema-ref-parser",
+  "version": "1.2.4",
+  "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
+  "keywords": [
+    "$ref",
+    "dereference",
+    "json",
+    "json-pointer",
+    "json-schema",
+    "jsonschema",
+    "resolve",
+    "schema"
+  ],
+  "homepage": "https://heyapi.dev/",
+  "bugs": {
+    "url": "https://github.com/hey-api/openapi-ts/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hey API",
+    "email": "lubos@heyapi.dev",
+    "url": "https://heyapi.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hey-api/openapi-ts.git"
+  },
+  "funding": "https://github.com/sponsors/hey-api",
+  "files": [
+    "src",
+    "dist",
+    "cjs"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown && pnpm check-exports",
+    "check-exports": "attw --pack . --profile esm-only --ignore-rules cjs-resolves-to-esm",
+    "dev": "tsdown --watch",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@jsdevtools/ono": "7.1.3",
+    "@types/json-schema": "7.0.15",
+    "js-yaml": "4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}

packages/json-schema-ref-parser/src/__tests__/bundle.test.ts

@@ -0,0 +1,59 @@
+import path from 'node:path';
+
+import { $RefParser } from '..';
+import { getSpecsPath } from './utils';
+
+describe('bundle', () => {
+  it('handles circular reference with description', async () => {
+    const refParser = new $RefParser();
+    const pathOrUrlOrSchema = path.join(
+      getSpecsPath(),
+      'json-schema-ref-parser',
+      'circular-ref-with-description.json',
+    );
+    const schema = await refParser.bundle({ pathOrUrlOrSchema });
+    expect(schema).toEqual({
+      schemas: {
+        Bar: {
+          $ref: '#/schemas/Foo',
+          description: 'ok',
+        },
+        Foo: {
+          $ref: '#/schemas/Bar',
+        },
+      },
+    });
+  });
+
+  it('bundles multiple references to the same file correctly', async () => {
+    const refParser = new $RefParser();
+    const pathOrUrlOrSchema = path.join(
+      getSpecsPath(),
+      'json-schema-ref-parser',
+      'multiple-refs.json',
+    );
+    const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+    // Both parameters should now be $ref to the same internal definition
+    const firstParam = schema.paths['/test1/{pathId}'].get.parameters[0];
+    const secondParam = schema.paths['/test2/{pathId}'].get.parameters[0];
+
+    // The $ref should match the output structure in file_context_0
+    expect(firstParam.$ref).toBe('#/components/parameters/path-parameter_pathId');
+    expect(secondParam.$ref).toBe('#/components/parameters/path-parameter_pathId');
+
+    // The referenced parameter should exist and match the expected structure
+    expect(schema.components).toBeDefined();
+    expect(schema.components.parameters).toBeDefined();
+    expect(schema.components.parameters['path-parameter_pathId']).toEqual({
+      in: 'path',
+      name: 'pathId',
+      required: true,
+      schema: {
+        description: 'Unique identifier for the path',
+        format: 'uuid',
+        type: 'string',
+      },
+    });
+  });
+});

packages/json-schema-ref-parser/src/__tests__/index.test.ts

@@ -0,0 +1,43 @@
+import path from 'node:path';
+
+import { getResolvedInput } from '../index';
+
+describe('getResolvedInput', () => {
+  it('handles url', async () => {
+    const pathOrUrlOrSchema = 'https://foo.com';
+    const resolvedInput = await getResolvedInput({ pathOrUrlOrSchema });
+    expect(resolvedInput.type).toBe('url');
+    expect(resolvedInput.schema).toBeUndefined();
+    expect(resolvedInput.path).toBe('https://foo.com/');
+  });
+
+  it('handles file', async () => {
+    const pathOrUrlOrSchema = './path/to/openapi.json';
+    const resolvedInput = await getResolvedInput({ pathOrUrlOrSchema });
+    expect(resolvedInput.type).toBe('file');
+    expect(resolvedInput.schema).toBeUndefined();
+    expect(path.normalize(resolvedInput.path).toLowerCase()).toBe(
+      path.normalize(path.resolve('./path/to/openapi.json')).toLowerCase(),
+    );
+  });
+
+  it('handles raw spec', async () => {
+    const pathOrUrlOrSchema = {
+      info: {
+        version: '1.0.0',
+      },
+      openapi: '3.1.0',
+      paths: {},
+    };
+    const resolvedInput = await getResolvedInput({ pathOrUrlOrSchema });
+    expect(resolvedInput.type).toBe('json');
+    expect(resolvedInput.schema).toEqual({
+      info: {
+        version: '1.0.0',
+      },
+      openapi: '3.1.0',
+      paths: {},
+    });
+    expect(resolvedInput.path).toBe('');
+  });
+});

packages/json-schema-ref-parser/src/__tests__/pointer.test.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+
+import { $RefParser } from '..';
+import { getSpecsPath } from './utils';
+
+describe('pointer', () => {
+  it('inlines internal JSON Pointer refs under #/paths/ for OpenAPI bundling', async () => {
+    const refParser = new $RefParser();
+    const pathOrUrlOrSchema = path.join(
+      getSpecsPath(),
+      'json-schema-ref-parser',
+      'openapi-paths-ref.json',
+    );
+    const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+    // The GET endpoint should have its schema defined inline
+    const getSchema = schema.paths['/foo'].get.responses['200'].content['application/json'].schema;
+    expect(getSchema.$ref).toBeUndefined();
+    expect(getSchema.type).toBe('object');
+    expect(getSchema.properties.bar.type).toBe('string');
+
+    // The POST endpoint should have its schema inlined (copied) instead of a $ref
+    const postSchema =
+      schema.paths['/foo'].post.responses['200'].content['application/json'].schema;
+    expect(postSchema.$ref).toBe(
+      '#/paths/~1foo/get/responses/200/content/application~1json/schema',
+    );
+    expect(postSchema.type).toBeUndefined();
+    expect(postSchema.properties?.bar?.type).toBeUndefined();
+
+    // Both schemas should be identical objects
+    expect(postSchema).not.toBe(getSchema);
+  });
+});

packages/json-schema-ref-parser/src/__tests__/utils.ts

@@ -0,0 +1,3 @@
+import path from 'node:path';
+
+export const getSpecsPath = (): string => path.join(__dirname, '..', '..', '..', '..', 'specs');