@digitraffic/common 2026.10.30-1 → 2026.10.30-2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
import { describe, expect, test } from "vitest";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { convertJsonSchemaNullableToOneOfDeep, toApiGatewayJsonSchema, } from "../../utils/api-model.js";
|
|
4
|
+
describe("convertJsonSchemaNullableToOneOfDeep", () => {
|
|
5
|
+
test("does not change a schema without nullable", () => {
|
|
6
|
+
const input = {
|
|
7
|
+
type: "object",
|
|
8
|
+
properties: {
|
|
9
|
+
name: { type: "string", description: "Vessel name" },
|
|
10
|
+
ids: { type: "array", items: { type: "number" } },
|
|
11
|
+
union: { anyOf: [{ type: "string" }, { type: "number" }] },
|
|
12
|
+
},
|
|
13
|
+
required: ["name"],
|
|
14
|
+
additionalProperties: false,
|
|
15
|
+
};
|
|
16
|
+
expect(convertJsonSchemaNullableToOneOfDeep(input)).toEqual(input);
|
|
17
|
+
});
|
|
18
|
+
test("converts nullable fields to oneOf", () => {
|
|
19
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
20
|
+
type: "object",
|
|
21
|
+
properties: {
|
|
22
|
+
reason: {
|
|
23
|
+
type: "string",
|
|
24
|
+
nullable: true,
|
|
25
|
+
description: "Optional reason",
|
|
26
|
+
},
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
expect(schema).toEqual({
|
|
30
|
+
type: "object",
|
|
31
|
+
properties: {
|
|
32
|
+
reason: {
|
|
33
|
+
oneOf: [
|
|
34
|
+
{ type: "string", description: "Optional reason" },
|
|
35
|
+
{ type: "null" },
|
|
36
|
+
],
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
});
|
|
40
|
+
});
|
|
41
|
+
test("converts nested nullable fields", () => {
|
|
42
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
43
|
+
type: "array",
|
|
44
|
+
items: {
|
|
45
|
+
type: "object",
|
|
46
|
+
properties: {
|
|
47
|
+
reason: { type: "string", nullable: true },
|
|
48
|
+
},
|
|
49
|
+
},
|
|
50
|
+
});
|
|
51
|
+
expect(schema).toEqual({
|
|
52
|
+
type: "array",
|
|
53
|
+
items: {
|
|
54
|
+
type: "object",
|
|
55
|
+
properties: {
|
|
56
|
+
reason: {
|
|
57
|
+
oneOf: [{ type: "string" }, { type: "null" }],
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
});
|
|
62
|
+
});
|
|
63
|
+
test("adds null to an existing union", () => {
|
|
64
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
65
|
+
anyOf: [{ type: "string" }, { type: "number" }],
|
|
66
|
+
nullable: true,
|
|
67
|
+
});
|
|
68
|
+
expect(schema).toEqual({
|
|
69
|
+
anyOf: [{ type: "string" }, { type: "number" }, { type: "null" }],
|
|
70
|
+
});
|
|
71
|
+
});
|
|
72
|
+
test("keeps null allowed when nullable schema uses allOf", () => {
|
|
73
|
+
// Zod can emit nullable intersections as { nullable: true, allOf: [...] }.
|
|
74
|
+
// anyOf is used instead of oneOf because an allOf alternative could also
|
|
75
|
+
// accept null, and oneOf would then reject it.
|
|
76
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
77
|
+
allOf: [{ type: "object" }, { type: "object" }],
|
|
78
|
+
nullable: true,
|
|
79
|
+
});
|
|
80
|
+
expect(schema).toEqual({
|
|
81
|
+
anyOf: [
|
|
82
|
+
{ allOf: [{ type: "object" }, { type: "object" }] },
|
|
83
|
+
{ type: "null" },
|
|
84
|
+
],
|
|
85
|
+
});
|
|
86
|
+
});
|
|
87
|
+
test("keeps null allowed when nullable schema is only a reference", () => {
|
|
88
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
89
|
+
ref: "#/definitions/Vessel",
|
|
90
|
+
nullable: true,
|
|
91
|
+
});
|
|
92
|
+
expect(schema).toEqual({
|
|
93
|
+
anyOf: [{ ref: "#/definitions/Vessel" }, { type: "null" }],
|
|
94
|
+
});
|
|
95
|
+
});
|
|
96
|
+
test("keeps null allowed when nullable schema is empty", () => {
|
|
97
|
+
// An empty schema accepts everything, including null. oneOf would reject
|
|
98
|
+
// null because both alternatives match, so anyOf must be used.
|
|
99
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
100
|
+
nullable: true,
|
|
101
|
+
});
|
|
102
|
+
expect(schema).toEqual({
|
|
103
|
+
anyOf: [{}, { type: "null" }],
|
|
104
|
+
});
|
|
105
|
+
});
|
|
106
|
+
test("keeps a property named nullable", () => {
|
|
107
|
+
// "nullable" here is a field name, not the OpenAPI keyword
|
|
108
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
109
|
+
type: "object",
|
|
110
|
+
properties: {
|
|
111
|
+
nullable: { type: "boolean" },
|
|
112
|
+
},
|
|
113
|
+
required: ["nullable"],
|
|
114
|
+
});
|
|
115
|
+
expect(schema).toEqual({
|
|
116
|
+
type: "object",
|
|
117
|
+
properties: {
|
|
118
|
+
nullable: { type: "boolean" },
|
|
119
|
+
},
|
|
120
|
+
required: ["nullable"],
|
|
121
|
+
});
|
|
122
|
+
});
|
|
123
|
+
test("keeps literal values such as defaults untouched", () => {
|
|
124
|
+
// The default value is data, not schema. It must not be rewritten.
|
|
125
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
126
|
+
type: "object",
|
|
127
|
+
properties: {
|
|
128
|
+
settings: {
|
|
129
|
+
type: "object",
|
|
130
|
+
default: { nullable: true },
|
|
131
|
+
},
|
|
132
|
+
},
|
|
133
|
+
});
|
|
134
|
+
expect(schema).toEqual({
|
|
135
|
+
type: "object",
|
|
136
|
+
properties: {
|
|
137
|
+
settings: {
|
|
138
|
+
type: "object",
|
|
139
|
+
default: { nullable: true },
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
});
|
|
143
|
+
});
|
|
144
|
+
test("converts nullable inside dependencies schemas", () => {
|
|
145
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
146
|
+
type: "object",
|
|
147
|
+
dependencies: {
|
|
148
|
+
// schema dependency: applied when "credit" is present
|
|
149
|
+
credit: {
|
|
150
|
+
properties: {
|
|
151
|
+
billingAddress: { type: "string", nullable: true },
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
// property dependency: a plain name list, must stay unchanged
|
|
155
|
+
name: ["firstName"],
|
|
156
|
+
},
|
|
157
|
+
});
|
|
158
|
+
expect(schema).toEqual({
|
|
159
|
+
type: "object",
|
|
160
|
+
dependencies: {
|
|
161
|
+
credit: {
|
|
162
|
+
properties: {
|
|
163
|
+
billingAddress: {
|
|
164
|
+
oneOf: [{ type: "string" }, { type: "null" }],
|
|
165
|
+
},
|
|
166
|
+
},
|
|
167
|
+
},
|
|
168
|
+
name: ["firstName"],
|
|
169
|
+
},
|
|
170
|
+
});
|
|
171
|
+
});
|
|
172
|
+
test("keeps definitions resolvable when a nullable root is wrapped", () => {
|
|
173
|
+
// definitions must stay at the root, otherwise "#/definitions/Code"
|
|
174
|
+
// would point to nothing after wrapping
|
|
175
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
176
|
+
type: "object",
|
|
177
|
+
definitions: {
|
|
178
|
+
Code: { type: "string", nullable: true },
|
|
179
|
+
},
|
|
180
|
+
properties: {
|
|
181
|
+
code: { ref: "#/definitions/Code" },
|
|
182
|
+
},
|
|
183
|
+
nullable: true,
|
|
184
|
+
});
|
|
185
|
+
expect(schema).toEqual({
|
|
186
|
+
definitions: {
|
|
187
|
+
Code: { oneOf: [{ type: "string" }, { type: "null" }] },
|
|
188
|
+
},
|
|
189
|
+
oneOf: [
|
|
190
|
+
{
|
|
191
|
+
type: "object",
|
|
192
|
+
properties: {
|
|
193
|
+
code: { ref: "#/definitions/Code" },
|
|
194
|
+
},
|
|
195
|
+
},
|
|
196
|
+
{ type: "null" },
|
|
197
|
+
],
|
|
198
|
+
});
|
|
199
|
+
});
|
|
200
|
+
test("wraps a nullable anyOf that has sibling constraints", () => {
|
|
201
|
+
// enum applies to the whole schema, so null added inside anyOf alone
|
|
202
|
+
// would still be rejected by it
|
|
203
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
204
|
+
anyOf: [{ type: "string" }, { type: "number" }],
|
|
205
|
+
enum: ["a", 1],
|
|
206
|
+
nullable: true,
|
|
207
|
+
});
|
|
208
|
+
expect(schema).toEqual({
|
|
209
|
+
anyOf: [
|
|
210
|
+
{
|
|
211
|
+
anyOf: [{ type: "string" }, { type: "number" }],
|
|
212
|
+
enum: ["a", 1],
|
|
213
|
+
},
|
|
214
|
+
{ type: "null" },
|
|
215
|
+
],
|
|
216
|
+
});
|
|
217
|
+
});
|
|
218
|
+
test("removes nullable false from root and nested schemas", () => {
|
|
219
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
220
|
+
type: "object",
|
|
221
|
+
nullable: false,
|
|
222
|
+
properties: {
|
|
223
|
+
name: { type: "string", nullable: false },
|
|
224
|
+
},
|
|
225
|
+
});
|
|
226
|
+
expect(schema).toEqual({
|
|
227
|
+
type: "object",
|
|
228
|
+
properties: {
|
|
229
|
+
name: { type: "string" },
|
|
230
|
+
},
|
|
231
|
+
});
|
|
232
|
+
});
|
|
233
|
+
test("throws when wrapping would break a local reference", () => {
|
|
234
|
+
// "#/properties/..." would point to nothing after wrapping, so the
|
|
235
|
+
// conversion must fail at synth time instead of producing a broken model
|
|
236
|
+
expect(() => convertJsonSchemaNullableToOneOfDeep({
|
|
237
|
+
type: "object",
|
|
238
|
+
nullable: true,
|
|
239
|
+
properties: {
|
|
240
|
+
homeAddress: { type: "object" },
|
|
241
|
+
billingAddress: { ref: "#/properties/homeAddress" },
|
|
242
|
+
},
|
|
243
|
+
})).toThrow(/#\/properties\/homeAddress/);
|
|
244
|
+
});
|
|
245
|
+
test("allows definitions references when wrapping", () => {
|
|
246
|
+
expect(() => convertJsonSchemaNullableToOneOfDeep({
|
|
247
|
+
type: "object",
|
|
248
|
+
nullable: true,
|
|
249
|
+
definitions: { Code: { type: "string" } },
|
|
250
|
+
properties: {
|
|
251
|
+
code: { ref: "#/definitions/Code" },
|
|
252
|
+
},
|
|
253
|
+
})).not.toThrow();
|
|
254
|
+
});
|
|
255
|
+
test("does not treat references inside literal values as broken", () => {
|
|
256
|
+
// The default value is data. A "ref" inside it is not a schema reference
|
|
257
|
+
// and must not fail the conversion.
|
|
258
|
+
const schema = convertJsonSchemaNullableToOneOfDeep({
|
|
259
|
+
type: "object",
|
|
260
|
+
nullable: true,
|
|
261
|
+
properties: {
|
|
262
|
+
settings: {
|
|
263
|
+
type: "object",
|
|
264
|
+
default: { ref: "#/properties/code" },
|
|
265
|
+
},
|
|
266
|
+
},
|
|
267
|
+
});
|
|
268
|
+
expect(schema).toEqual({
|
|
269
|
+
oneOf: [
|
|
270
|
+
{
|
|
271
|
+
type: "object",
|
|
272
|
+
properties: {
|
|
273
|
+
settings: {
|
|
274
|
+
type: "object",
|
|
275
|
+
default: { ref: "#/properties/code" },
|
|
276
|
+
},
|
|
277
|
+
},
|
|
278
|
+
},
|
|
279
|
+
{ type: "null" },
|
|
280
|
+
],
|
|
281
|
+
});
|
|
282
|
+
});
|
|
283
|
+
test("creates an API Gateway schema from Zod", () => {
|
|
284
|
+
const schema = toApiGatewayJsonSchema(z.object({
|
|
285
|
+
reason: z.string().nullable(),
|
|
286
|
+
timestamp: z.iso.datetime(),
|
|
287
|
+
}));
|
|
288
|
+
expect(schema).toMatchObject({
|
|
289
|
+
type: "object",
|
|
290
|
+
properties: {
|
|
291
|
+
reason: {
|
|
292
|
+
oneOf: [{ type: "string" }, { type: "null" }],
|
|
293
|
+
},
|
|
294
|
+
timestamp: { type: "string", format: "date-time" },
|
|
295
|
+
},
|
|
296
|
+
});
|
|
297
|
+
expect(schema).not.toHaveProperty("properties.timestamp.pattern");
|
|
298
|
+
});
|
|
299
|
+
test("keeps a property named pattern but removes the pattern keyword", () => {
|
|
300
|
+
const schema = toApiGatewayJsonSchema(z.object({
|
|
301
|
+
// a field that happens to be named "pattern"
|
|
302
|
+
pattern: z.string().regex(/^[a-z]+$/),
|
|
303
|
+
}));
|
|
304
|
+
expect(schema).toMatchObject({
|
|
305
|
+
type: "object",
|
|
306
|
+
properties: {
|
|
307
|
+
pattern: { type: "string" },
|
|
308
|
+
},
|
|
309
|
+
required: ["pattern"],
|
|
310
|
+
});
|
|
311
|
+
// the regex keyword itself must not reach API Gateway
|
|
312
|
+
expect(schema).not.toHaveProperty("properties.pattern.pattern");
|
|
313
|
+
});
|
|
314
|
+
});
|
|
315
|
+
//# sourceMappingURL=api-model.test.js.map
|
|
@@ -1,6 +1,71 @@
|
|
|
1
1
|
import type { JsonSchema, Model, RequestValidator, RestApi } from "aws-cdk-lib/aws-apigateway";
|
|
2
|
+
import type { ZodType } from "zod";
|
|
2
3
|
import type { ModelWithReference } from "../aws/types/model-with-reference.js";
|
|
3
4
|
type ModelReferenceUrl = `https://apigateway.amazonaws.com/restapis/${string}/models/${string}`;
|
|
5
|
+
type JsonSchemaWithNullable = JsonSchema & {
|
|
6
|
+
nullable?: boolean;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* Converts nullable fields in an OpenAPI 3.0 JSON Schema to a form accepted by
|
|
10
|
+
* API Gateway model schemas.
|
|
11
|
+
*
|
|
12
|
+
* API Gateway rejects the OpenAPI 3.0 `nullable` keyword. Importing a model
|
|
13
|
+
* with it fails with errors such as "ArrayNode cannot be cast to TextNode".
|
|
14
|
+
* This input is not accepted:
|
|
15
|
+
*
|
|
16
|
+
* ```json
|
|
17
|
+
* { "type": "string", "nullable": true }
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* This function removes `nullable` and expresses null as an alternative,
|
|
21
|
+
* which API Gateway accepts:
|
|
22
|
+
*
|
|
23
|
+
* ```json
|
|
24
|
+
* { "oneOf": [{ "type": "string" }, { "type": "null" }] }
|
|
25
|
+
* ```
|
|
26
|
+
*
|
|
27
|
+
* If the nullable schema is already an `anyOf` union, the null alternative is
|
|
28
|
+
* added to it. If it has no `type` at all (for example `allOf` or a plain
|
|
29
|
+
* reference), the whole schema is wrapped in an `anyOf` so that null stays
|
|
30
|
+
* allowed. The conversion is applied recursively to nested schemas. Field
|
|
31
|
+
* names and literal values such as defaults are left untouched.
|
|
32
|
+
*
|
|
33
|
+
* Limitation: when a nullable schema is wrapped, only references to
|
|
34
|
+
* `#/definitions/...` stay valid. If the schema contains local references to
|
|
35
|
+
* other locations, such as `#/properties/...`, an error is thrown instead of
|
|
36
|
+
* producing a model with broken references. Zod output never contains such
|
|
37
|
+
* references, so this only matters for hand-written schemas.
|
|
38
|
+
*/
|
|
39
|
+
export declare function convertJsonSchemaNullableToOneOfDeep(schema: JsonSchemaWithNullable): JsonSchemaWithNullable;
|
|
40
|
+
/**
|
|
41
|
+
* Creates a JSON Schema that can be used as an API Gateway model from a Zod schema.
|
|
42
|
+
*
|
|
43
|
+
* API Gateway does not accept Zod's default nullable output or regex patterns in
|
|
44
|
+
* model schemas. This helper keeps nullable values as `oneOf` alternatives and
|
|
45
|
+
* removes the `pattern` keyword that API Gateway cannot import. Field names and
|
|
46
|
+
* literal values are not touched, so a field may safely be named for example
|
|
47
|
+
* "pattern" or "nullable".
|
|
48
|
+
*
|
|
49
|
+
* For example, this Zod schema:
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* z.object({ reason: z.string().nullable() });
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* becomes this API Gateway schema:
|
|
56
|
+
*
|
|
57
|
+
* ```json
|
|
58
|
+
* {
|
|
59
|
+
* "type": "object",
|
|
60
|
+
* "properties": {
|
|
61
|
+
* "reason": {
|
|
62
|
+
* "oneOf": [{ "type": "string" }, { "type": "null" }]
|
|
63
|
+
* }
|
|
64
|
+
* }
|
|
65
|
+
* }
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
export declare function toApiGatewayJsonSchema(schema: ZodType): JsonSchema;
|
|
4
69
|
/**
|
|
5
70
|
* Get a reference to an OpenAPI model object in a REST API.
|
|
6
71
|
* Can be used to supply a reference to properties of a GeoJSON feature.
|
package/dist/utils/api-model.js
CHANGED
|
@@ -1,4 +1,233 @@
|
|
|
1
1
|
import { JsonSchemaType, JsonSchemaVersion } from "aws-cdk-lib/aws-apigateway";
|
|
2
|
+
import { toJSONSchema } from "zod";
|
|
3
|
+
function isObject(value) {
|
|
4
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
5
|
+
}
|
|
6
|
+
// Keywords whose value is a map from a name to a schema. The names are data
|
|
7
|
+
// (for example field names) and must not be changed, only the schema values.
|
|
8
|
+
// A dependencies value can also be a string array, which is left unchanged.
|
|
9
|
+
const SCHEMA_MAP_KEYWORDS = [
|
|
10
|
+
"properties",
|
|
11
|
+
"patternProperties",
|
|
12
|
+
"definitions",
|
|
13
|
+
"dependencies",
|
|
14
|
+
];
|
|
15
|
+
// Keywords whose value is a list of schemas.
|
|
16
|
+
const SCHEMA_LIST_KEYWORDS = ["oneOf", "anyOf", "allOf"];
|
|
17
|
+
// Keywords whose value is a single schema.
|
|
18
|
+
const SCHEMA_KEYWORDS = [
|
|
19
|
+
"items",
|
|
20
|
+
"additionalProperties",
|
|
21
|
+
"additionalItems",
|
|
22
|
+
"contains",
|
|
23
|
+
"propertyNames",
|
|
24
|
+
"not",
|
|
25
|
+
];
|
|
26
|
+
/**
|
|
27
|
+
* Walks a JSON Schema and applies the transform to every schema object,
|
|
28
|
+
* starting from the innermost ones. Only values of known schema keywords are
|
|
29
|
+
* treated as schemas. Everything else, such as field names in `properties`
|
|
30
|
+
* and literal values like `default`, is left untouched.
|
|
31
|
+
*/
|
|
32
|
+
function transformSchemaDeep(schema, transform) {
|
|
33
|
+
if (!isObject(schema)) {
|
|
34
|
+
return schema;
|
|
35
|
+
}
|
|
36
|
+
const result = {};
|
|
37
|
+
for (const [key, value] of Object.entries(schema)) {
|
|
38
|
+
if (SCHEMA_MAP_KEYWORDS.includes(key) && isObject(value)) {
|
|
39
|
+
result[key] = Object.fromEntries(Object.entries(value).map(([name, subSchema]) => [
|
|
40
|
+
name,
|
|
41
|
+
transformSchemaDeep(subSchema, transform),
|
|
42
|
+
]));
|
|
43
|
+
}
|
|
44
|
+
else if (SCHEMA_LIST_KEYWORDS.includes(key) && Array.isArray(value)) {
|
|
45
|
+
result[key] = value.map((item) => transformSchemaDeep(item, transform));
|
|
46
|
+
}
|
|
47
|
+
else if (key === "items" && Array.isArray(value)) {
|
|
48
|
+
result[key] = value.map((item) => transformSchemaDeep(item, transform));
|
|
49
|
+
}
|
|
50
|
+
else if (SCHEMA_KEYWORDS.includes(key) && isObject(value)) {
|
|
51
|
+
result[key] = transformSchemaDeep(value, transform);
|
|
52
|
+
}
|
|
53
|
+
else {
|
|
54
|
+
result[key] = value;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return transform(result);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Collects all local reference values ("#/...") from a schema. Walks only
|
|
61
|
+
* known schema keywords, so references inside literal values such as defaults
|
|
62
|
+
* or enums are not collected. Both the CDK property name "ref" and the raw
|
|
63
|
+
* JSON Schema keyword "$ref" are checked.
|
|
64
|
+
*/
|
|
65
|
+
function findLocalReferences(schema) {
|
|
66
|
+
if (!isObject(schema)) {
|
|
67
|
+
return [];
|
|
68
|
+
}
|
|
69
|
+
const references = [];
|
|
70
|
+
for (const [key, value] of Object.entries(schema)) {
|
|
71
|
+
if ((key === "ref" || key === "$ref") &&
|
|
72
|
+
typeof value === "string" &&
|
|
73
|
+
value.startsWith("#/")) {
|
|
74
|
+
references.push(value);
|
|
75
|
+
}
|
|
76
|
+
else if (SCHEMA_MAP_KEYWORDS.includes(key) && isObject(value)) {
|
|
77
|
+
for (const subSchema of Object.values(value)) {
|
|
78
|
+
references.push(...findLocalReferences(subSchema));
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
else if ((SCHEMA_LIST_KEYWORDS.includes(key) || key === "items") &&
|
|
82
|
+
Array.isArray(value)) {
|
|
83
|
+
for (const item of value) {
|
|
84
|
+
references.push(...findLocalReferences(item));
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
else if (SCHEMA_KEYWORDS.includes(key) && isObject(value)) {
|
|
88
|
+
references.push(...findLocalReferences(value));
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return references;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Wraps a schema and a null alternative into a union. Definitions are kept at
|
|
95
|
+
* the root, otherwise local references like "#/definitions/X" would point to
|
|
96
|
+
* nothing after wrapping.
|
|
97
|
+
*
|
|
98
|
+
* Throws if the schema contains local references to other locations, such as
|
|
99
|
+
* "#/properties/...". Wrapping would silently break them, so failing at synth
|
|
100
|
+
* time is safer than deploying a broken model.
|
|
101
|
+
*/
|
|
102
|
+
function wrapSchemaWithNull(schema, unionKeyword) {
|
|
103
|
+
const { definitions, ...rest } = schema;
|
|
104
|
+
const brokenReferences = findLocalReferences(rest).filter((reference) => !reference.startsWith("#/definitions/"));
|
|
105
|
+
if (brokenReferences.length > 0) {
|
|
106
|
+
throw new Error(`Cannot convert nullable schema: wrapping would break local references: ${brokenReferences.join(", ")}. Only #/definitions/ references are supported.`);
|
|
107
|
+
}
|
|
108
|
+
const wrapped = {
|
|
109
|
+
[unionKeyword]: [rest, { type: "null" }],
|
|
110
|
+
};
|
|
111
|
+
if (definitions !== undefined) {
|
|
112
|
+
// biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
|
|
113
|
+
wrapped["definitions"] = definitions;
|
|
114
|
+
}
|
|
115
|
+
return wrapped;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Converts one schema object with `nullable: true` to a form that accepts null.
|
|
119
|
+
*/
|
|
120
|
+
function convertNullableSchema(schema) {
|
|
121
|
+
if (!("nullable" in schema)) {
|
|
122
|
+
return schema;
|
|
123
|
+
}
|
|
124
|
+
// The nullable keyword is always removed because API Gateway rejects it.
|
|
125
|
+
// A null alternative is added only when the value was true.
|
|
126
|
+
const { nullable, ...rest } = schema;
|
|
127
|
+
if (nullable !== true) {
|
|
128
|
+
return rest;
|
|
129
|
+
}
|
|
130
|
+
// A simple typed schema cannot overlap with null, so oneOf is safe.
|
|
131
|
+
// biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
|
|
132
|
+
if (typeof rest["type"] === "string") {
|
|
133
|
+
return wrapSchemaWithNull(rest, "oneOf");
|
|
134
|
+
}
|
|
135
|
+
// A standalone anyOf can take null as one more alternative. This is only
|
|
136
|
+
// safe when anyOf is the sole keyword: sibling keywords such as enum apply
|
|
137
|
+
// to the whole schema and would still reject null.
|
|
138
|
+
// biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
|
|
139
|
+
const anyOf = rest["anyOf"];
|
|
140
|
+
if (Array.isArray(anyOf) && Object.keys(rest).length === 1) {
|
|
141
|
+
const hasNull = anyOf.some(
|
|
142
|
+
// biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
|
|
143
|
+
(item) => isObject(item) && item["type"] === "null");
|
|
144
|
+
return hasNull ? rest : { anyOf: [...anyOf, { type: "null" }] };
|
|
145
|
+
}
|
|
146
|
+
// Everything else: oneOf, allOf, references or an empty schema. Wrap in
|
|
147
|
+
// anyOf instead of oneOf, because the schema itself may also accept null
|
|
148
|
+
// and oneOf would then reject it (oneOf requires exactly one match).
|
|
149
|
+
return wrapSchemaWithNull(rest, "anyOf");
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Removes the `pattern` keyword from one schema object. Field names that
|
|
153
|
+
* happen to be called "pattern" live inside `properties` and are not touched.
|
|
154
|
+
*/
|
|
155
|
+
function removePatternKeyword(schema) {
|
|
156
|
+
if (!("pattern" in schema)) {
|
|
157
|
+
return schema;
|
|
158
|
+
}
|
|
159
|
+
const { pattern: _pattern, ...rest } = schema;
|
|
160
|
+
return rest;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Converts nullable fields in an OpenAPI 3.0 JSON Schema to a form accepted by
|
|
164
|
+
* API Gateway model schemas.
|
|
165
|
+
*
|
|
166
|
+
* API Gateway rejects the OpenAPI 3.0 `nullable` keyword. Importing a model
|
|
167
|
+
* with it fails with errors such as "ArrayNode cannot be cast to TextNode".
|
|
168
|
+
* This input is not accepted:
|
|
169
|
+
*
|
|
170
|
+
* ```json
|
|
171
|
+
* { "type": "string", "nullable": true }
|
|
172
|
+
* ```
|
|
173
|
+
*
|
|
174
|
+
* This function removes `nullable` and expresses null as an alternative,
|
|
175
|
+
* which API Gateway accepts:
|
|
176
|
+
*
|
|
177
|
+
* ```json
|
|
178
|
+
* { "oneOf": [{ "type": "string" }, { "type": "null" }] }
|
|
179
|
+
* ```
|
|
180
|
+
*
|
|
181
|
+
* If the nullable schema is already an `anyOf` union, the null alternative is
|
|
182
|
+
* added to it. If it has no `type` at all (for example `allOf` or a plain
|
|
183
|
+
* reference), the whole schema is wrapped in an `anyOf` so that null stays
|
|
184
|
+
* allowed. The conversion is applied recursively to nested schemas. Field
|
|
185
|
+
* names and literal values such as defaults are left untouched.
|
|
186
|
+
*
|
|
187
|
+
* Limitation: when a nullable schema is wrapped, only references to
|
|
188
|
+
* `#/definitions/...` stay valid. If the schema contains local references to
|
|
189
|
+
* other locations, such as `#/properties/...`, an error is thrown instead of
|
|
190
|
+
* producing a model with broken references. Zod output never contains such
|
|
191
|
+
* references, so this only matters for hand-written schemas.
|
|
192
|
+
*/
|
|
193
|
+
export function convertJsonSchemaNullableToOneOfDeep(schema) {
|
|
194
|
+
return transformSchemaDeep(schema, convertNullableSchema);
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Creates a JSON Schema that can be used as an API Gateway model from a Zod schema.
|
|
198
|
+
*
|
|
199
|
+
* API Gateway does not accept Zod's default nullable output or regex patterns in
|
|
200
|
+
* model schemas. This helper keeps nullable values as `oneOf` alternatives and
|
|
201
|
+
* removes the `pattern` keyword that API Gateway cannot import. Field names and
|
|
202
|
+
* literal values are not touched, so a field may safely be named for example
|
|
203
|
+
* "pattern" or "nullable".
|
|
204
|
+
*
|
|
205
|
+
* For example, this Zod schema:
|
|
206
|
+
*
|
|
207
|
+
* ```ts
|
|
208
|
+
* z.object({ reason: z.string().nullable() });
|
|
209
|
+
* ```
|
|
210
|
+
*
|
|
211
|
+
* becomes this API Gateway schema:
|
|
212
|
+
*
|
|
213
|
+
* ```json
|
|
214
|
+
* {
|
|
215
|
+
* "type": "object",
|
|
216
|
+
* "properties": {
|
|
217
|
+
* "reason": {
|
|
218
|
+
* "oneOf": [{ "type": "string" }, { "type": "null" }]
|
|
219
|
+
* }
|
|
220
|
+
* }
|
|
221
|
+
* }
|
|
222
|
+
* ```
|
|
223
|
+
*/
|
|
224
|
+
export function toApiGatewayJsonSchema(schema) {
|
|
225
|
+
const jsonSchema = toJSONSchema(schema, {
|
|
226
|
+
target: "openapi-3.0",
|
|
227
|
+
unrepresentable: "any",
|
|
228
|
+
});
|
|
229
|
+
return transformSchemaDeep(jsonSchema, (schemaObject) => convertNullableSchema(removePatternKeyword(schemaObject)));
|
|
230
|
+
}
|
|
2
231
|
/**
|
|
3
232
|
* Get a reference to an OpenAPI model object in a REST API.
|
|
4
233
|
* Can be used to supply a reference to properties of a GeoJSON feature.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@digitraffic/common",
|
|
3
|
-
"version": "2026.10.30-
|
|
3
|
+
"version": "2026.10.30-2",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "",
|
|
6
6
|
"repository": {
|
|
@@ -149,7 +149,7 @@
|
|
|
149
149
|
"undici": "8.12.2",
|
|
150
150
|
"velocityjs": "2.1.7",
|
|
151
151
|
"vitest": "4.1.12",
|
|
152
|
-
"zod": "4.
|
|
152
|
+
"zod": "4.6.7"
|
|
153
153
|
},
|
|
154
154
|
"peerDependencies": {
|
|
155
155
|
"@aws-sdk/client-api-gateway": "3.1098.0",
|
|
@@ -169,7 +169,7 @@
|
|
|
169
169
|
"pg-native": "3.8.0",
|
|
170
170
|
"pg-promise": "12.7.0",
|
|
171
171
|
"undici": "8.12.2",
|
|
172
|
-
"zod": "4.
|
|
172
|
+
"zod": "4.6.7"
|
|
173
173
|
},
|
|
174
174
|
"engines": {
|
|
175
175
|
"node": ">=24 <25"
|