graphenix-format 1.3.0 → 1.4.0

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.
Files changed (6) hide show
  1. package/README.md +322 -320
  2. package/dist/types.d.ts +17 -0
  3. package/dist/types.d.ts.map +1 -1
  4. package/docs/interop-worox-graph.md +4 -1
  5. package/package.json +1 -1
  6. package/schema/graphenix-format-1.0.0.schema.json +529 -491
package/schema/graphenix-format-1.0.0.schema.json CHANGED
@@ -1,491 +1,529 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "$id": "https://graphenix.dev/schema/graphenix-format-1.0.0.json",
4
- "title": "Graphenix Format 1.0.0",
5
- "description": "JSON Schema for the Graphenix graph description format (version 1.0.0). Execution semantics are out of scope.",
6
- "type": "object",
7
- "required": ["formatVersion", "id", "graph"],
8
- "additionalProperties": false,
9
- "properties": {
10
- "formatVersion": {
11
- "type": "string",
12
- "description": "Semantic version of the graphenix-format used by this document (e.g. 1.0.0)."
13
- },
14
- "id": {
15
- "type": "string",
16
- "description": "Globally unique identifier for this graph within the system."
17
- },
18
- "name": {
19
- "type": "string",
20
- "description": "Human-readable name for the graph."
21
- },
22
- "description": {
23
- "type": "string",
24
- "description": "Free-form description of the graph."
25
- },
26
- "tags": {
27
- "type": "array",
28
- "items": {
29
- "type": "string"
30
- },
31
- "description": "Tags for classification, search, and filtering."
32
- },
33
- "graph": {
34
- "$ref": "#/$defs/Graph"
35
- },
36
- "types": {
37
- "type": "array",
38
- "items": {
39
- "$ref": "#/$defs/TypeDefinition"
40
- },
41
- "description": "Custom logical types referenced by nodes and ports."
42
- },
43
- "subgraphs": {
44
- "type": "array",
45
- "items": {
46
- "$ref": "#/$defs/SubgraphDefinition"
47
- },
48
- "description": "Inlined reusable graphs."
49
- },
50
- "extensions": {
51
- "type": "object",
52
- "description": "Namespaced extension object. Engines that do not recognize an extension namespace must ignore it.",
53
- "additionalProperties": true
54
- },
55
- "metadata": {
56
- "type": "object",
57
- "description": "Optional document metadata. `graphEntry` and `graphResponse` align with worox-graph graph JSON contracts (I/O layers 01 and 08); other keys are allowed for tooling.",
58
- "additionalProperties": true,
59
- "properties": {
60
- "graphEntry": {
61
- "$ref": "#/$defs/GraphEntryContract"
62
- },
63
- "graphResponse": {
64
- "$ref": "#/$defs/GraphResponseContract"
65
- }
66
- }
67
- }
68
- },
69
- "$defs": {
70
- "Graph": {
71
- "type": "object",
72
- "required": ["nodes", "edges", "inputs", "outputs"],
73
- "additionalProperties": false,
74
- "properties": {
75
- "nodes": {
76
- "type": "array",
77
- "items": {
78
- "$ref": "#/$defs/Node"
79
- }
80
- },
81
- "edges": {
82
- "type": "array",
83
- "items": {
84
- "$ref": "#/$defs/Edge"
85
- }
86
- },
87
- "inputs": {
88
- "type": "array",
89
- "items": {
90
- "$ref": "#/$defs/GraphInput"
91
- }
92
- },
93
- "outputs": {
94
- "type": "array",
95
- "items": {
96
- "$ref": "#/$defs/GraphOutput"
97
- }
98
- },
99
- "metadata": {
100
- "type": "object",
101
- "description": "Arbitrary metadata not affecting execution semantics.",
102
- "additionalProperties": true
103
- }
104
- }
105
- },
106
- "Node": {
107
- "type": "object",
108
- "required": ["id", "kind"],
109
- "additionalProperties": false,
110
- "properties": {
111
- "id": {
112
- "type": "string",
113
- "description": "Unique identifier within the containing graph."
114
- },
115
- "name": {
116
- "type": "string",
117
- "description": "Human-readable name for UIs and logs."
118
- },
119
- "kind": {
120
- "type": "string",
121
- "description": "Logical type of node determining how the executor interprets it (e.g. builtin:map, task:http-request, subgraph:graph:user-validation)."
122
- },
123
- "inputs": {
124
- "type": "array",
125
- "items": {
126
- "$ref": "#/$defs/PortDefinition"
127
- },
128
- "default": []
129
- },
130
- "outputs": {
131
- "type": "array",
132
- "items": {
133
- "$ref": "#/$defs/PortDefinition"
134
- },
135
- "default": []
136
- },
137
- "parameters": {
138
- "type": "object",
139
- "description": "Static configuration for the node. Interpretation is executor-specific based on kind.",
140
- "additionalProperties": true,
141
- "default": {}
142
- },
143
- "metadata": {
144
- "type": "object",
145
- "description": "Arbitrary metadata not affecting execution semantics (e.g. UI position).",
146
- "additionalProperties": true
147
- },
148
- "extensions": {
149
- "type": "object",
150
- "description": "Namespaced extension data.",
151
- "additionalProperties": true
152
- }
153
- }
154
- },
155
- "PortDefinition": {
156
- "type": "object",
157
- "required": ["id", "direction", "type"],
158
- "additionalProperties": false,
159
- "properties": {
160
- "id": {
161
- "type": "string",
162
- "description": "Unique identifier within the node."
163
- },
164
- "name": {
165
- "type": "string",
166
- "description": "Human-readable label."
167
- },
168
- "direction": {
169
- "type": "string",
170
- "enum": ["input", "output"],
171
- "description": "Direction of data flow."
172
- },
173
- "type": {
174
- "type": "string",
175
- "description": "Type identifier (built-in type or custom type id)."
176
- },
177
- "required": {
178
- "type": "boolean",
179
- "description": "Indicates if a value must be present for the node to execute.",
180
- "default": false
181
- },
182
- "default": {
183
- "description": "Default value when no incoming edge provides one. Must be compatible with the declared type.",
184
- "type": ["string", "number", "boolean", "array", "object", "null"]
185
- }
186
- }
187
- },
188
- "EdgeEndpoint": {
189
- "type": "object",
190
- "required": ["nodeId", "portId"],
191
- "additionalProperties": false,
192
- "properties": {
193
- "nodeId": {
194
- "type": "string",
195
- "description": "ID of the node."
196
- },
197
- "portId": {
198
- "type": "string",
199
- "description": "ID of the port on the referenced node."
200
- }
201
- }
202
- },
203
- "Edge": {
204
- "type": "object",
205
- "required": ["id", "from", "to"],
206
- "additionalProperties": false,
207
- "properties": {
208
- "id": {
209
- "type": "string",
210
- "description": "Unique identifier within the graph."
211
- },
212
- "from": {
213
- "$ref": "#/$defs/EdgeEndpoint",
214
- "description": "Source of the edge; must reference an existing node/output port."
215
- },
216
- "to": {
217
- "$ref": "#/$defs/EdgeEndpoint",
218
- "description": "Target of the edge; must reference an existing node/input port."
219
- },
220
- "metadata": {
221
- "type": "object",
222
- "description": "Metadata not affecting execution (e.g. edge label in UI).",
223
- "additionalProperties": true
224
- },
225
- "extensions": {
226
- "type": "object",
227
- "description": "Namespaced extension data.",
228
- "additionalProperties": true
229
- }
230
- }
231
- },
232
- "GraphInput": {
233
- "type": "object",
234
- "required": ["id", "type", "target"],
235
- "additionalProperties": false,
236
- "properties": {
237
- "id": {
238
- "type": "string",
239
- "description": "Unique identifier within the graph."
240
- },
241
- "name": {
242
- "type": "string",
243
- "description": "Human-readable name."
244
- },
245
- "type": {
246
- "type": "string",
247
- "description": "Logical type identifier for the external input."
248
- },
249
- "target": {
250
- "$ref": "#/$defs/EdgeEndpoint",
251
- "description": "Node and input port that consume this graph input."
252
- },
253
- "metadata": {
254
- "type": "object",
255
- "description": "Metadata not affecting execution.",
256
- "additionalProperties": true
257
- },
258
- "extensions": {
259
- "type": "object",
260
- "description": "Namespaced extension data.",
261
- "additionalProperties": true
262
- }
263
- }
264
- },
265
- "GraphOutput": {
266
- "type": "object",
267
- "required": ["id", "type", "source"],
268
- "additionalProperties": false,
269
- "properties": {
270
- "id": {
271
- "type": "string",
272
- "description": "Unique identifier within the graph."
273
- },
274
- "name": {
275
- "type": "string",
276
- "description": "Human-readable name."
277
- },
278
- "type": {
279
- "type": "string",
280
- "description": "Logical type identifier for the external output."
281
- },
282
- "source": {
283
- "$ref": "#/$defs/EdgeEndpoint",
284
- "description": "Node and output port that provide this graph output."
285
- },
286
- "metadata": {
287
- "type": "object",
288
- "description": "Metadata not affecting execution.",
289
- "additionalProperties": true
290
- },
291
- "extensions": {
292
- "type": "object",
293
- "description": "Namespaced extension data.",
294
- "additionalProperties": true
295
- }
296
- }
297
- },
298
- "TypeField": {
299
- "type": "object",
300
- "required": ["name", "type"],
301
- "additionalProperties": false,
302
- "properties": {
303
- "name": {
304
- "type": "string",
305
- "description": "Field name."
306
- },
307
- "type": {
308
- "type": "string",
309
- "description": "Type identifier for the field (built-in or custom)."
310
- },
311
- "required": {
312
- "type": "boolean",
313
- "description": "Whether this field must be present.",
314
- "default": false
315
- }
316
- }
317
- },
318
- "TypeObject": {
319
- "type": "object",
320
- "required": ["id", "kind", "fields"],
321
- "additionalProperties": false,
322
- "properties": {
323
- "id": {
324
- "type": "string",
325
- "description": "Unique type identifier (e.g. type:User)."
326
- },
327
- "kind": {
328
- "const": "object"
329
- },
330
- "description": {
331
- "type": "string"
332
- },
333
- "fields": {
334
- "type": "array",
335
- "items": {
336
- "$ref": "#/$defs/TypeField"
337
- }
338
- },
339
- "metadata": {
340
- "type": "object",
341
- "additionalProperties": true
342
- },
343
- "extensions": {
344
- "type": "object",
345
- "additionalProperties": true
346
- }
347
- }
348
- },
349
- "TypeUnion": {
350
- "type": "object",
351
- "required": ["id", "kind", "options"],
352
- "additionalProperties": false,
353
- "properties": {
354
- "id": {
355
- "type": "string",
356
- "description": "Unique type identifier."
357
- },
358
- "kind": {
359
- "const": "union"
360
- },
361
- "description": {
362
- "type": "string"
363
- },
364
- "options": {
365
- "type": "array",
366
- "items": {
367
- "type": "string"
368
- },
369
- "description": "Array of type IDs or built-in types."
370
- },
371
- "metadata": {
372
- "type": "object",
373
- "additionalProperties": true
374
- },
375
- "extensions": {
376
- "type": "object",
377
- "additionalProperties": true
378
- }
379
- }
380
- },
381
- "TypeAlias": {
382
- "type": "object",
383
- "required": ["id", "kind", "target"],
384
- "additionalProperties": false,
385
- "properties": {
386
- "id": {
387
- "type": "string",
388
- "description": "Unique type identifier."
389
- },
390
- "kind": {
391
- "const": "alias"
392
- },
393
- "description": {
394
- "type": "string"
395
- },
396
- "target": {
397
- "type": "string",
398
- "description": "Type ID (or built-in) this type refers to."
399
- },
400
- "metadata": {
401
- "type": "object",
402
- "additionalProperties": true
403
- },
404
- "extensions": {
405
- "type": "object",
406
- "additionalProperties": true
407
- }
408
- }
409
- },
410
- "TypeDefinition": {
411
- "oneOf": [
412
- {
413
- "$ref": "#/$defs/TypeObject"
414
- },
415
- {
416
- "$ref": "#/$defs/TypeUnion"
417
- },
418
- {
419
- "$ref": "#/$defs/TypeAlias"
420
- }
421
- ]
422
- },
423
- "SubgraphDefinition": {
424
- "type": "object",
425
- "required": ["id", "graph"],
426
- "additionalProperties": false,
427
- "properties": {
428
- "id": {
429
- "type": "string",
430
- "description": "Unique identifier for the subgraph within the document."
431
- },
432
- "name": {
433
- "type": "string",
434
- "description": "Human-readable name for the subgraph."
435
- },
436
- "graph": {
437
- "$ref": "#/$defs/Graph"
438
- },
439
- "metadata": {
440
- "type": "object",
441
- "additionalProperties": true
442
- },
443
- "extensions": {
444
- "type": "object",
445
- "additionalProperties": true
446
- }
447
- }
448
- },
449
- "GraphEntryContract": {
450
- "type": "object",
451
- "description": "Worox-graph entry contract: execution inputs and paths (layer 01). Additional properties may be added by worox-graph.",
452
- "additionalProperties": true,
453
- "properties": {
454
- "summary": {
455
- "type": "string",
456
- "description": "Human-readable summary of entry expectations."
457
- },
458
- "requiredExecutionPaths": {
459
- "type": "array",
460
- "description": "Descriptors for execution paths that must be satisfied (engine-specific item shape).",
461
- "items": {}
462
- },
463
- "executionSchema": {
464
- "type": "object",
465
- "description": "JSON Schema for the merged execution object (tooling validates at runtime when enabled)."
466
- },
467
- "notableExecutionPaths": {
468
- "type": "array",
469
- "description": "Notable optional or diagnostic execution paths.",
470
- "items": {}
471
- }
472
- }
473
- },
474
- "GraphResponseContract": {
475
- "type": "object",
476
- "description": "Worox-graph response contract: final output shape (layer 08). Additional properties may be added by worox-graph.",
477
- "additionalProperties": true,
478
- "properties": {
479
- "summary": {
480
- "type": "string",
481
- "description": "Human-readable summary of the response / final output."
482
- },
483
- "finalOutputSchema": {
484
- "type": "object",
485
- "description": "JSON Schema for the final output value (tooling validates at runtime when enabled)."
486
- }
487
- }
488
- }
489
- }
490
- }
491
-
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "https://graphenix.dev/schema/graphenix-format-1.0.0.json",
4
+ "title": "Graphenix Format 1.0.0",
5
+ "description": "JSON Schema for the Graphenix graph description format (version 1.0.0). Execution semantics are out of scope.",
6
+ "type": "object",
7
+ "required": ["formatVersion", "id", "graph"],
8
+ "additionalProperties": false,
9
+ "properties": {
10
+ "formatVersion": {
11
+ "type": "string",
12
+ "description": "Semantic version of the graphenix-format used by this document (e.g. 1.0.0)."
13
+ },
14
+ "id": {
15
+ "type": "string",
16
+ "description": "Globally unique identifier for this graph within the system."
17
+ },
18
+ "name": {
19
+ "type": "string",
20
+ "description": "Human-readable name for the graph."
21
+ },
22
+ "description": {
23
+ "type": "string",
24
+ "description": "Free-form description of the graph."
25
+ },
26
+ "tags": {
27
+ "type": "array",
28
+ "items": {
29
+ "type": "string"
30
+ },
31
+ "description": "Tags for classification, search, and filtering."
32
+ },
33
+ "graph": {
34
+ "$ref": "#/$defs/Graph"
35
+ },
36
+ "types": {
37
+ "type": "array",
38
+ "items": {
39
+ "$ref": "#/$defs/TypeDefinition"
40
+ },
41
+ "description": "Custom logical types referenced by nodes and ports."
42
+ },
43
+ "subgraphs": {
44
+ "type": "array",
45
+ "items": {
46
+ "$ref": "#/$defs/SubgraphDefinition"
47
+ },
48
+ "description": "Inlined reusable graphs."
49
+ },
50
+ "extensions": {
51
+ "type": "object",
52
+ "description": "Namespaced extension object. Engines that do not recognize an extension namespace must ignore it.",
53
+ "additionalProperties": true
54
+ },
55
+ "metadata": {
56
+ "type": "object",
57
+ "description": "Optional document metadata. `graphEntry` and `graphResponse` align with worox-graph graph JSON contracts (I/O layers 01 and 08). Optional `catalogRequests` is planning-only (worox-graph). Other keys are allowed for tooling.",
58
+ "additionalProperties": true,
59
+ "properties": {
60
+ "graphEntry": {
61
+ "$ref": "#/$defs/GraphEntryContract"
62
+ },
63
+ "graphResponse": {
64
+ "$ref": "#/$defs/GraphResponseContract"
65
+ },
66
+ "catalogRequests": {
67
+ "$ref": "#/$defs/WoroxCatalogRequests"
68
+ }
69
+ }
70
+ }
71
+ },
72
+ "$defs": {
73
+ "Graph": {
74
+ "type": "object",
75
+ "required": ["nodes", "edges", "inputs", "outputs"],
76
+ "additionalProperties": false,
77
+ "properties": {
78
+ "nodes": {
79
+ "type": "array",
80
+ "items": {
81
+ "$ref": "#/$defs/Node"
82
+ }
83
+ },
84
+ "edges": {
85
+ "type": "array",
86
+ "items": {
87
+ "$ref": "#/$defs/Edge"
88
+ }
89
+ },
90
+ "inputs": {
91
+ "type": "array",
92
+ "items": {
93
+ "$ref": "#/$defs/GraphInput"
94
+ }
95
+ },
96
+ "outputs": {
97
+ "type": "array",
98
+ "items": {
99
+ "$ref": "#/$defs/GraphOutput"
100
+ }
101
+ },
102
+ "metadata": {
103
+ "type": "object",
104
+ "description": "Arbitrary metadata not affecting execution semantics.",
105
+ "additionalProperties": true
106
+ }
107
+ }
108
+ },
109
+ "Node": {
110
+ "type": "object",
111
+ "required": ["id", "kind"],
112
+ "additionalProperties": false,
113
+ "properties": {
114
+ "id": {
115
+ "type": "string",
116
+ "description": "Unique identifier within the containing graph."
117
+ },
118
+ "name": {
119
+ "type": "string",
120
+ "description": "Human-readable name for UIs and logs."
121
+ },
122
+ "kind": {
123
+ "type": "string",
124
+ "description": "Logical type of node determining how the executor interprets it (e.g. builtin:map, task:http-request, subgraph:graph:user-validation)."
125
+ },
126
+ "inputs": {
127
+ "type": "array",
128
+ "items": {
129
+ "$ref": "#/$defs/PortDefinition"
130
+ },
131
+ "default": []
132
+ },
133
+ "outputs": {
134
+ "type": "array",
135
+ "items": {
136
+ "$ref": "#/$defs/PortDefinition"
137
+ },
138
+ "default": []
139
+ },
140
+ "parameters": {
141
+ "type": "object",
142
+ "description": "Static configuration for the node. Interpretation is executor-specific based on kind.",
143
+ "additionalProperties": true,
144
+ "default": {}
145
+ },
146
+ "metadata": {
147
+ "type": "object",
148
+ "description": "Arbitrary metadata not affecting execution semantics (e.g. UI position). Worox-graph task nodes may use planning-only `catalogBinding` / `catalogRequest` (execution unchanged).",
149
+ "additionalProperties": true,
150
+ "properties": {
151
+ "catalogBinding": {
152
+ "$ref": "#/$defs/WoroxCatalogBinding"
153
+ },
154
+ "catalogRequest": {
155
+ "$ref": "#/$defs/WoroxCatalogRequest"
156
+ }
157
+ }
158
+ },
159
+ "extensions": {
160
+ "type": "object",
161
+ "description": "Namespaced extension data.",
162
+ "additionalProperties": true
163
+ }
164
+ }
165
+ },
166
+ "PortDefinition": {
167
+ "type": "object",
168
+ "required": ["id", "direction", "type"],
169
+ "additionalProperties": false,
170
+ "properties": {
171
+ "id": {
172
+ "type": "string",
173
+ "description": "Unique identifier within the node."
174
+ },
175
+ "name": {
176
+ "type": "string",
177
+ "description": "Human-readable label."
178
+ },
179
+ "direction": {
180
+ "type": "string",
181
+ "enum": ["input", "output"],
182
+ "description": "Direction of data flow."
183
+ },
184
+ "type": {
185
+ "type": "string",
186
+ "description": "Type identifier (built-in type or custom type id)."
187
+ },
188
+ "required": {
189
+ "type": "boolean",
190
+ "description": "Indicates if a value must be present for the node to execute.",
191
+ "default": false
192
+ },
193
+ "default": {
194
+ "description": "Default value when no incoming edge provides one. Must be compatible with the declared type.",
195
+ "type": ["string", "number", "boolean", "array", "object", "null"]
196
+ }
197
+ }
198
+ },
199
+ "EdgeEndpoint": {
200
+ "type": "object",
201
+ "required": ["nodeId", "portId"],
202
+ "additionalProperties": false,
203
+ "properties": {
204
+ "nodeId": {
205
+ "type": "string",
206
+ "description": "ID of the node."
207
+ },
208
+ "portId": {
209
+ "type": "string",
210
+ "description": "ID of the port on the referenced node."
211
+ }
212
+ }
213
+ },
214
+ "Edge": {
215
+ "type": "object",
216
+ "required": ["id", "from", "to"],
217
+ "additionalProperties": false,
218
+ "properties": {
219
+ "id": {
220
+ "type": "string",
221
+ "description": "Unique identifier within the graph."
222
+ },
223
+ "from": {
224
+ "$ref": "#/$defs/EdgeEndpoint",
225
+ "description": "Source of the edge; must reference an existing node/output port."
226
+ },
227
+ "to": {
228
+ "$ref": "#/$defs/EdgeEndpoint",
229
+ "description": "Target of the edge; must reference an existing node/input port."
230
+ },
231
+ "metadata": {
232
+ "type": "object",
233
+ "description": "Metadata not affecting execution (e.g. edge label in UI).",
234
+ "additionalProperties": true
235
+ },
236
+ "extensions": {
237
+ "type": "object",
238
+ "description": "Namespaced extension data.",
239
+ "additionalProperties": true
240
+ }
241
+ }
242
+ },
243
+ "GraphInput": {
244
+ "type": "object",
245
+ "required": ["id", "type", "target"],
246
+ "additionalProperties": false,
247
+ "properties": {
248
+ "id": {
249
+ "type": "string",
250
+ "description": "Unique identifier within the graph."
251
+ },
252
+ "name": {
253
+ "type": "string",
254
+ "description": "Human-readable name."
255
+ },
256
+ "type": {
257
+ "type": "string",
258
+ "description": "Logical type identifier for the external input."
259
+ },
260
+ "target": {
261
+ "$ref": "#/$defs/EdgeEndpoint",
262
+ "description": "Node and input port that consume this graph input."
263
+ },
264
+ "metadata": {
265
+ "type": "object",
266
+ "description": "Metadata not affecting execution.",
267
+ "additionalProperties": true
268
+ },
269
+ "extensions": {
270
+ "type": "object",
271
+ "description": "Namespaced extension data.",
272
+ "additionalProperties": true
273
+ }
274
+ }
275
+ },
276
+ "GraphOutput": {
277
+ "type": "object",
278
+ "required": ["id", "type", "source"],
279
+ "additionalProperties": false,
280
+ "properties": {
281
+ "id": {
282
+ "type": "string",
283
+ "description": "Unique identifier within the graph."
284
+ },
285
+ "name": {
286
+ "type": "string",
287
+ "description": "Human-readable name."
288
+ },
289
+ "type": {
290
+ "type": "string",
291
+ "description": "Logical type identifier for the external output."
292
+ },
293
+ "source": {
294
+ "$ref": "#/$defs/EdgeEndpoint",
295
+ "description": "Node and output port that provide this graph output."
296
+ },
297
+ "metadata": {
298
+ "type": "object",
299
+ "description": "Metadata not affecting execution.",
300
+ "additionalProperties": true
301
+ },
302
+ "extensions": {
303
+ "type": "object",
304
+ "description": "Namespaced extension data.",
305
+ "additionalProperties": true
306
+ }
307
+ }
308
+ },
309
+ "TypeField": {
310
+ "type": "object",
311
+ "required": ["name", "type"],
312
+ "additionalProperties": false,
313
+ "properties": {
314
+ "name": {
315
+ "type": "string",
316
+ "description": "Field name."
317
+ },
318
+ "type": {
319
+ "type": "string",
320
+ "description": "Type identifier for the field (built-in or custom)."
321
+ },
322
+ "required": {
323
+ "type": "boolean",
324
+ "description": "Whether this field must be present.",
325
+ "default": false
326
+ }
327
+ }
328
+ },
329
+ "TypeObject": {
330
+ "type": "object",
331
+ "required": ["id", "kind", "fields"],
332
+ "additionalProperties": false,
333
+ "properties": {
334
+ "id": {
335
+ "type": "string",
336
+ "description": "Unique type identifier (e.g. type:User)."
337
+ },
338
+ "kind": {
339
+ "const": "object"
340
+ },
341
+ "description": {
342
+ "type": "string"
343
+ },
344
+ "fields": {
345
+ "type": "array",
346
+ "items": {
347
+ "$ref": "#/$defs/TypeField"
348
+ }
349
+ },
350
+ "metadata": {
351
+ "type": "object",
352
+ "additionalProperties": true
353
+ },
354
+ "extensions": {
355
+ "type": "object",
356
+ "additionalProperties": true
357
+ }
358
+ }
359
+ },
360
+ "TypeUnion": {
361
+ "type": "object",
362
+ "required": ["id", "kind", "options"],
363
+ "additionalProperties": false,
364
+ "properties": {
365
+ "id": {
366
+ "type": "string",
367
+ "description": "Unique type identifier."
368
+ },
369
+ "kind": {
370
+ "const": "union"
371
+ },
372
+ "description": {
373
+ "type": "string"
374
+ },
375
+ "options": {
376
+ "type": "array",
377
+ "items": {
378
+ "type": "string"
379
+ },
380
+ "description": "Array of type IDs or built-in types."
381
+ },
382
+ "metadata": {
383
+ "type": "object",
384
+ "additionalProperties": true
385
+ },
386
+ "extensions": {
387
+ "type": "object",
388
+ "additionalProperties": true
389
+ }
390
+ }
391
+ },
392
+ "TypeAlias": {
393
+ "type": "object",
394
+ "required": ["id", "kind", "target"],
395
+ "additionalProperties": false,
396
+ "properties": {
397
+ "id": {
398
+ "type": "string",
399
+ "description": "Unique type identifier."
400
+ },
401
+ "kind": {
402
+ "const": "alias"
403
+ },
404
+ "description": {
405
+ "type": "string"
406
+ },
407
+ "target": {
408
+ "type": "string",
409
+ "description": "Type ID (or built-in) this type refers to."
410
+ },
411
+ "metadata": {
412
+ "type": "object",
413
+ "additionalProperties": true
414
+ },
415
+ "extensions": {
416
+ "type": "object",
417
+ "additionalProperties": true
418
+ }
419
+ }
420
+ },
421
+ "TypeDefinition": {
422
+ "oneOf": [
423
+ {
424
+ "$ref": "#/$defs/TypeObject"
425
+ },
426
+ {
427
+ "$ref": "#/$defs/TypeUnion"
428
+ },
429
+ {
430
+ "$ref": "#/$defs/TypeAlias"
431
+ }
432
+ ]
433
+ },
434
+ "SubgraphDefinition": {
435
+ "type": "object",
436
+ "required": ["id", "graph"],
437
+ "additionalProperties": false,
438
+ "properties": {
439
+ "id": {
440
+ "type": "string",
441
+ "description": "Unique identifier for the subgraph within the document."
442
+ },
443
+ "name": {
444
+ "type": "string",
445
+ "description": "Human-readable name for the subgraph."
446
+ },
447
+ "graph": {
448
+ "$ref": "#/$defs/Graph"
449
+ },
450
+ "metadata": {
451
+ "type": "object",
452
+ "additionalProperties": true
453
+ },
454
+ "extensions": {
455
+ "type": "object",
456
+ "additionalProperties": true
457
+ }
458
+ }
459
+ },
460
+ "GraphEntryContract": {
461
+ "type": "object",
462
+ "description": "Worox-graph entry contract: execution inputs and paths (layer 01). Additional properties may be added by worox-graph.",
463
+ "additionalProperties": true,
464
+ "properties": {
465
+ "summary": {
466
+ "type": "string",
467
+ "description": "Human-readable summary of entry expectations."
468
+ },
469
+ "requiredExecutionPaths": {
470
+ "type": "array",
471
+ "description": "Descriptors for execution paths that must be satisfied (engine-specific item shape).",
472
+ "items": {}
473
+ },
474
+ "executionSchema": {
475
+ "type": "object",
476
+ "description": "JSON Schema for the merged execution object (tooling validates at runtime when enabled)."
477
+ },
478
+ "notableExecutionPaths": {
479
+ "type": "array",
480
+ "description": "Notable optional or diagnostic execution paths.",
481
+ "items": {}
482
+ }
483
+ }
484
+ },
485
+ "GraphResponseContract": {
486
+ "type": "object",
487
+ "description": "Worox-graph response contract: final output shape (layer 08). Additional properties may be added by worox-graph.",
488
+ "additionalProperties": true,
489
+ "properties": {
490
+ "summary": {
491
+ "type": "string",
492
+ "description": "Human-readable summary of the response / final output."
493
+ },
494
+ "finalOutputSchema": {
495
+ "type": "object",
496
+ "description": "JSON Schema for the final output value (tooling validates at runtime when enabled)."
497
+ }
498
+ }
499
+ },
500
+ "WoroxCatalogRequest": {
501
+ "type": "object",
502
+ "description": "Planning-only catalog request on a worox-graph task node (`node.metadata.catalogRequest`). Execution is unchanged. Canonical field set: `@woroces/worox-graph` `refs.ts`.",
503
+ "additionalProperties": true
504
+ },
505
+ "WoroxCatalogBinding": {
506
+ "type": "object",
507
+ "description": "Planning-only catalog binding on a worox-graph task node (`node.metadata.catalogBinding`). Execution is unchanged. Canonical field set: `@woroces/worox-graph` `refs.ts`.",
508
+ "additionalProperties": true
509
+ },
510
+ "WoroxCatalogRequests": {
511
+ "description": "Planning-only document-level catalog requests (`metadata.catalogRequests` on worox graph JSON). Execution is unchanged. Shape may be a list or a map; see `@woroces/worox-graph` `refs.ts`.",
512
+ "oneOf": [
513
+ {
514
+ "type": "array",
515
+ "items": {
516
+ "$ref": "#/$defs/WoroxCatalogRequest"
517
+ }
518
+ },
519
+ {
520
+ "type": "object",
521
+ "additionalProperties": {
522
+ "$ref": "#/$defs/WoroxCatalogRequest"
523
+ }
524
+ }
525
+ ]
526
+ }
527
+ }
528
+ }
529
+