1
+import { describe, it, expect } from 'vitest';
2
+import { dereferenceJsonSchema } from '../../src/utils/jsonSchema';
3
+import { JsonSchemaRefResolutionError } from '../../src/errors/ValidationErrors';
4
+
5
+const containsRef = (value: unknown): boolean => {
6
+ if (value === null || typeof value !== 'object') return false;
7
+ if (Array.isArray(value)) return value.some(containsRef);
8
+ if ('$ref' in (value as Record<string, unknown>)) return true;
9
+ return Object.values(value as Record<string, unknown>).some(containsRef);
10
+};
11
+
12
+describe('dereferenceJsonSchema', () => {
13
+ it('inlines a single internal $ref under $defs', () => {
14
+ const out = dereferenceJsonSchema({
15
+ type: 'object',
16
+ properties: { user: { $ref: '#/$defs/User' } },
17
+ required: ['user'],
18
+ $defs: { User: { type: 'string' } },
19
+ });
20
+
21
+ expect(out).toEqual({
22
+ type: 'object',
23
+ properties: { user: { type: 'string' } },
24
+ required: ['user'],
25
+ });
26
+ expect(containsRef(out)).toBe(false);
27
+ });
28
+
29
+ it('resolves a chain of refs A -> B -> C', () => {
30
+ const out = dereferenceJsonSchema({
31
+ type: 'object',
32
+ properties: { v: { $ref: '#/$defs/A' } },
33
+ $defs: {
34
+ A: { $ref: '#/$defs/B' },
35
+ B: { $ref: '#/$defs/C' },
36
+ C: { type: 'integer' },
37
+ },
38
+ });
39
+
40
+ expect(containsRef(out)).toBe(false);
41
+ expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'integer' });
42
+ });
43
+
44
+ it('walks containers reflectively (items, oneOf, anyOf, allOf, not, additionalProperties, patternProperties, prefixItems)', () => {
45
+ const out = dereferenceJsonSchema({
46
+ type: 'object',
47
+ properties: {
48
+ a: { type: 'array', items: { $ref: '#/$defs/Leaf' } },
49
+ b: { oneOf: [{ $ref: '#/$defs/Leaf' }, { type: 'null' }] },
50
+ c: { anyOf: [{ $ref: '#/$defs/Leaf' }] },
51
+ d: { allOf: [{ $ref: '#/$defs/Leaf' }] },
52
+ e: { not: { $ref: '#/$defs/Leaf' } },
53
+ f: { type: 'object', additionalProperties: { $ref: '#/$defs/Leaf' } },
54
+ g: {
55
+ type: 'object',
56
+ patternProperties: { '^x_': { $ref: '#/$defs/Leaf' } },
57
+ },
58
+ h: { type: 'array', prefixItems: [{ $ref: '#/$defs/Leaf' }] },
59
+ },
60
+ $defs: { Leaf: { type: 'string' } },
61
+ });
62
+
63
+ expect(containsRef(out)).toBe(false);
64
+ });
65
+
66
+ it('resolves Draft 7 legacy `definitions`', () => {
67
+ const out = dereferenceJsonSchema({
68
+ type: 'object',
69
+ properties: { name: { $ref: '#/definitions/Name' } },
70
+ definitions: { Name: { type: 'string', minLength: 1 } },
71
+ });
72
+
73
+ expect(containsRef(out)).toBe(false);
74
+ expect((out as { properties: { name: unknown } }).properties.name).toEqual({
75
+ type: 'string',
76
+ minLength: 1,
77
+ });
78
+ });
79
+
80
+ it('mixes $defs and definitions transitively', () => {
81
+ const out = dereferenceJsonSchema({
82
+ type: 'object',
83
+ properties: { v: { $ref: '#/definitions/A' } },
84
+ definitions: { A: { $ref: '#/$defs/B' } },
85
+ $defs: { B: { type: 'boolean' } },
86
+ });
87
+
88
+ expect(containsRef(out)).toBe(false);
89
+ expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'boolean' });
90
+ });
91
+
92
+ it('shallow-merges sibling keywords next to $ref (Draft 2020-12 semantics; siblings win on collision)', () => {
93
+ const out = dereferenceJsonSchema({
94
+ type: 'object',
95
+ properties: {
96
+ v: {
97
+ $ref: '#/$defs/Foo',
98
+ description: 'caller override',
99
+ default: null,
100
+ },
101
+ },
102
+ $defs: {
103
+ Foo: { type: 'string', description: 'target description' },
104
+ },
105
+ });
106
+
107
+ const v = (out as { properties: { v: Record<string, unknown> } }).properties.v;
108
+ expect(v.type).toBe('string');
109
+ expect(v.description).toBe('caller override');
110
+ expect(v.default).toBeNull();
111
+ expect(containsRef(out)).toBe(false);
112
+ });
113
+
114
+ it('breaks recursive $ref cycles with a permissive object sentinel', () => {
115
+ const out = dereferenceJsonSchema({
116
+ $ref: '#/$defs/Tree',
117
+ $defs: {
118
+ Tree: {
119
+ type: 'object',
120
+ properties: {
121
+ children: { type: 'array', items: { $ref: '#/$defs/Tree' } },
122
+ },
123
+ },
124
+ },
125
+ });
126
+
127
+ expect((out as { type: string }).type).toBe('object');
128
+ const children = (
129
+ out as {
130
+ properties: { children: { items: { type: string; additionalProperties: boolean } } };
131
+ }
132
+ ).properties.children;
133
+ expect(children.items).toEqual({ type: 'object', additionalProperties: true });
134
+ expect(containsRef(out)).toBe(false);
135
+ });
136
+
137
+ it('strips $defs and definitions from the returned root schema', () => {
138
+ const out = dereferenceJsonSchema({
139
+ type: 'object',
140
+ properties: { x: { $ref: '#/$defs/Foo' } },
141
+ $defs: { Foo: { type: 'integer' } },
142
+ definitions: { Bar: { type: 'string' } },
143
+ }) as Record<string, unknown>;
144
+
145
+ expect(out.$defs).toBeUndefined();
146
+ expect(out.definitions).toBeUndefined();
147
+ });
148
+
149
+ it('throws JsonSchemaRefResolutionError when target is missing', () => {
150
+ expect(() =>
151
+ dereferenceJsonSchema({
152
+ type: 'object',
153
+ properties: { v: { $ref: '#/$defs/Missing' } },
154
+ $defs: {},
155
+ })
156
+ ).toThrow(JsonSchemaRefResolutionError);
157
+ });
158
+
159
+ it('throws JsonSchemaRefResolutionError when chain depth exceeds the cap', () => {
160
+ const $defs: Record<string, unknown> = {};
161
+ for (let i = 0; i < 200; i++) {
162
+ $defs[`A${i}`] = { $ref: i + 1 < 200 ? `#/$defs/A${i + 1}` : '#/$defs/A0' };
163
+ }
164
+ expect(() =>
165
+ dereferenceJsonSchema({
166
+ type: 'object',
167
+ properties: { v: { $ref: '#/$defs/A0' } },
168
+ $defs,
169
+ })
170
+ ).toThrow(JsonSchemaRefResolutionError);
171
+ });
172
+
173
+ it('leaves external $ref pointers untouched', () => {
174
+ const out = dereferenceJsonSchema({
175
+ type: 'object',
176
+ properties: { v: { $ref: 'https://example.com/Foo' } },
177
+ });
178
+
179
+ expect((out as { properties: { v: { $ref: string } } }).properties.v.$ref).toBe(
180
+ 'https://example.com/Foo'
181
+ );
182
+ });
183
+
184
+ it('does not mutate the input schema', () => {
185
+ const input = {
186
+ type: 'object',
187
+ properties: { v: { $ref: '#/$defs/Foo' } },
188
+ $defs: { Foo: { type: 'string' } },
189
+ };
190
+ const snapshot = structuredClone(input);
191
+ dereferenceJsonSchema(input);
192
+ expect(input).toEqual(snapshot);
193
+ });
194
+
195
+ it('decodes JSON Pointer escape sequences (~1 -> /, ~0 -> ~) in the correct order', () => {
196
+ const out = dereferenceJsonSchema({
197
+ type: 'object',
198
+ properties: {
199
+ a: { $ref: '#/$defs/with~1slash' },
200
+ b: { $ref: '#/$defs/with~0tilde' },
201
+ c: { $ref: '#/$defs/tilde-then-slash~01' },
202
+ },
203
+ $defs: {
204
+ 'with/slash': { type: 'string' },
205
+ 'with~tilde': { type: 'integer' },
206
+ 'tilde-then-slash~1': { type: 'boolean' },
207
+ },
208
+ } as unknown as Record<string, unknown>);
209
+
210
+ const props = (out as { properties: Record<string, { type: string }> }).properties;
211
+ expect(props.a.type).toBe('string');
212
+ expect(props.b.type).toBe('integer');
213
+ expect(props.c.type).toBe('boolean');
214
+ });
215
+
216
+ it('resolves array-index pointers (#/$defs/foo/oneOf/0)', () => {
217
+ const out = dereferenceJsonSchema({
218
+ type: 'object',
219
+ properties: { v: { $ref: '#/$defs/foo/oneOf/0' } },
220
+ $defs: {
221
+ foo: { oneOf: [{ type: 'string' }, { type: 'number' }] },
222
+ },
223
+ } as unknown as Record<string, unknown>);
224
+
225
+ expect((out as { properties: { v: { type: string } } }).properties.v.type).toBe('string');
226
+ });
227
+});