Repository navigation
Expand file tree
/
Copy pathopal_kernel.yaml
More file actions
3291 lines (3281 loc) · 127 KB
/
Copy pathopal_kernel.yaml
File metadata and controls
3291 lines (3281 loc) · 127 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# OPAL Suite Kernel — shared contract base for all OPAL service specs.
# Consumed via external $ref; never published standalone. See info.description.
openapi: 3.1.0
info:
title: OPAL Suite Kernel
version: '0.1.0'
description: 'Shared contract kernel for the OPAL suite (SUITE STANDARD v3.0.0).
This document is never served directly. Service specs under `openapi/` mount its reusable Path Items and reference
its components via external `$ref`s; published single-file artifacts are produced by `npm run bundle`.
Conventions encoded here: the four X-Opal-* correlation headers on every request and response; strong ETag +
mandatory If-Match on mutable configuration (428 missing, 412 stale); 204 for empty deletion; 201 + Location
for creation; the OpalError envelope for all 4xx/5xx JSON bodies; and the standard health/settings/config/profiles/engines
route families. If-Match concurrency covers portable logical configuration only: `config load`, `config
setting set`, and `config setting remove` require it; runtime-data deletes (events, executions, failed
utterances, sessions) are exempt by design; `config save` and `config validate` neither mutate live
configuration nor bump the live revision, so they take no If-Match. Collections return bounded arrays;
list endpoints that can grow unboundedly declare the `limit` query parameter (server caps apply); opaque cursors
are used only where bounded arrays cannot bound a dataset. Configuration save/load/validate replaces the
retired backup/restore and export/import interfaces; snapshots capture persistent desired configuration
only - never history, sessions, binaries, secrets, or observed runtime inventory.
Kernel schemas are deliberately open (`additionalProperties: true`) on union types: suite-standard required
fields are normative, and each service layers its own domain fields on top. The namespaced profile
schemas (`OpalProfile`, `OpalProfileCreate`, `OpalProfilePatch`, v3.0.0) are the documented exception:
their envelopes are closed, module-owned fields live only inside `shared` and per-module `modules`
compartments declared in this document, and lifecycle semantics are defined by `x-opal-profiles`.'
paths: {}
x-opal-authorization:
version: '1.0'
description: Suite REST authentication and authorization semantics. Loopback-only deployments may explicitly disable
authentication; non-loopback deployments require authentication. Privileged configuration operations require
authorization. 401 means missing or invalid authentication; 403 means authenticated but not permitted. Correlation
IDs are never authorization credentials. Secret values must not appear in responses, exports, or error details.
semantics:
missing_or_invalid_credentials: '401'
authenticated_but_not_permitted: '403'
loopback: authentication may be explicitly disabled on loopback deployments
non_loopback: authentication required
privileged_operations: authorization required for configuration mutations
credentials: correlation headers are transport context, never authorization credentials
secrets: secret values must not appear in responses, exports, or error details
x-opal-event-envelope:
propagate:
- session_id
- transaction_id
- request_id
- causation_id
zero_mq_frames: 2
compatibility: metadata_schema_version versions the optional data.metadata block only; the two-frame wire envelope
(topic + JSON with topic/data) is unchanged across versions. Consumers extract known correlation keys (session_id,
transaction_id, request_id, causation_id) and MUST ignore unknown metadata fields; producers may emit any metadata_schema_version
without breaking the wire contract.
x-opal-cli-format:
version: '1.0'
description: Canonical CLI binding for OPAL operations. Every annotated operation maps to one canonical
command `opal <service> [parent] [group] <command>`; `aliases` names alternate complete spellings that dispatch
to the same operation (e.g. Think's `ask`/`chat`/`create` invoke `task add`). Kernel Path Items carry
per-operation descriptors directly and are the single source of truth for shared-operation bindings,
including all `config`/`config setting`, `info`, `service`, `profile`, and `persona` commands.
Readers hoist
a path-level
per-method map onto each
operation for module-declared mounts; both forms carry the same descriptor shape.
descriptor:
command: required - canonical verb, kebab-case (`list`, `add`, `show`, `update`, `remove`, `save`,
`load`, `validate`, ...)
group: optional - command group (`task`, `persona`, `setting`, `info`, ...)
parent: optional - super-group above `group` (`config`, `data`)
aliases: optional - array of alternate complete command spellings for this operation
options: optional - array of named-option descriptors; each carries `flag` (long option spelling),
`value` (metavar such as NAME/VALUE/FILE), `required` (default false), optional `description`, and
`binds` describing how the option feeds the REST call - `{kind, target, parse?}` with kind `path` |
`query` | `body` | `header` | `local_in` | `local_out`.
placement:
operation: '`x-opal-cli: <descriptor>`'
path_item: '`x-opal-cli: {<method>: <descriptor>}` - for module-declared bindings on a `$ref`-mounted
path item (an extension beside `$ref` cannot inject into operations defined in another document).
Kernel-owned Path Items use the operation form instead.'
local_file_options:
local_in: The CLI reads and parses a client-local file, then submits the parsed object in the request
body at `target`. The service never sees the client filename. For snapshot operations, `.yaml`/`.yml`
select YAML parsing and `.json` selects JSON; other extensions are client errors, never server errors.
Profile operations use the same convention for nested structured input - `--in FILE` targets the
whole request body (the portable profile document or patch document), `--shared FILE` targets
`shared`, and `--module FILE` targets `modules.<module-key>`, a placeholder the receiving
service substitutes with its own declared compartment key
(`x-opal-profile-namespace.compartment`) when generating commands, so a published binding
reads e.g. `modules.opal-say` on opal-say.
local_out: The CLI writes the named response field to a client-local file, serialized as YAML for
`.yaml`/`.yml` or JSON for `.json`; other extensions are client errors. The service never sees the
client filename. For `config save`, `--out FILE` also switches request `destination` to `response`
so no managed snapshot is written.
parse_json_or_string: For `config setting set --value`, the CLI parses the argument as JSON first; valid
JSON becomes the native JSON value, otherwise the exact string is sent. JSON `null` is a nullable
value, never a deletion instruction.
example:
parent: config
group: persona
command: list
x-opal-persona:
version: '1.0'
description: >-
Portable OPAL persona contract. A persona is an identity with optional
per-service bindings. OPAL Think hosts the authoritative registry; every
service keeps full local CRUD for standalone operation, and the owner
record wins on conflict when a consumer is configured to reach it.
ownership:
authoritative_writer: OPAL Think
obtain: >-
Consumers resolve an unknown persona_id from
GET {owner_url}/api/v1/persona/{persona_id}, cache it with its ETag
(origin: owner), and revalidate on use. No owner_url means standalone:
local personas only.
conflict: owner record wins when owner_url is configured; local records are retained.
profiles_vs_personas:
profile: >-
A profile is a portable document of named presets: a `shared` section
plus one compartment per module (`modules.<module-id>`), stored locally
by each service. At most one profile is active per service at a time —
a local runtime/configuration selection, not part of the portable
payload; an empty local catalog is legal. The active profile's shared
values and the service's own compartment fill in any setting a request
leaves out. See `x-opal-profiles`.
persona: >-
A persona is an identity — who the user interacts with — that can carry
service-specific bindings (a Say voice, Think model/instructions). New
users pick a persona when they want a consistent character across
requests without repeating its bound settings.
difference: >-
Profiles change what a service does by default; personas change who the
service is for the user. They compose: the persona's bindings sit
between the selected profile and explicit request fields in resolution.
resolution:
order: explicit request field > persona binding > selected profile's module override > selected profile's shared value > service default
per_field: true
bindings:
voice_id: OPAL Say validates resolvability; other services treat it as an opaque nullable reference.
think: model/instructions binding lives in Think's service-local fields; Think validates.
validation: >-
POST /api/v1/persona/{persona_id}/validate reports that service's
binding resolvability, not a suite-wide verdict.
errors:
unknown_persona: 404 on read, 422 when referenced by a request
binding_unresolvable: 422 on use; /validate reports it without deleting the persona
disabled: 422/409 on use; record and bindings remain readable
examples:
think_only:
persona_id: amy
name: Amy
enabled: true
description: Persona with only a Think model/instructions binding (service-local fields).
say_only:
persona_id: vox
name: Vox
voice_id: en-gb-alan-low
enabled: true
description: Persona with only a Say voice binding.
combined:
persona_id: amy
name: Amy
description: Ops assistant.
voice_id: en-gb-alan-low
enabled: true
origin: owner
description_of_example: Think model + instructions plus a Say voice, synced from the owner.
x-opal-profiles:
version: '1.0'
description: >-
Portable namespaced OPAL profile contract. A profile is one document
carrying a `shared` object plus a `modules` map of module-owned
compartments keyed by canonical module identity. Each service stores its
own local profile records, reads only `shared` and its own compartment,
and preserves all other compartments verbatim. Namespace schemas and the
compartment catalog live in this document's `components.schemas`.
storage:
locality: >-
Profiles are per-service local configuration. A portable document may
hold compartments for many modules; copying or loading it transfers an
explicit snapshot into the receiving service's local record. Edits
affect only the receiving service's copy - propagating an updated
compartment to another service requires explicitly transferring the
configuration (config save on the source, config load on the target).
activation: >-
Active selection is local runtime/configuration state: at most one
profile is active per service, and an empty local catalog is legal.
`is_active` on responses is a read projection of that local selection,
not portable payload; it is stored so config save/load restores the
selection coherently. On select, the service applies `shared` plus its
own compartment; missing compartments mean no profile overrides (the
existing defaults apply).
lifecycle: >-
Profile edits apply to new work admitted after the edit; work already
admitted keeps the resolved values it was admitted under, consistent
with each service's existing lifecycle guarantees.
patch_semantics: >-
Ordinary partial edits may change `name`, `description`, `is_active`,
`shared` and the receiving module's own compartment only. Omitted
properties stay unchanged; a supplied compartment merges field-wise so
sibling fields and all other compartments are preserved; arrays replace
as whole values; explicit JSON `null` on a compartment field removes that
override and restores inheritance (distinct from stored `null` values a
field declares as meaningful, e.g. `sample_rate`). Attempting to change
another module's compartment is rejected with 422 and its stored contents
are preserved. Patches and validation failures are atomic: nothing
partial is persisted.
validation: >-
`shared` and every declared compartment are validated structurally
against the kernel's namespace schemas (closed objects). The receiving
module additionally validates its own compartment's local resource
references semantically (e.g. opal-say checks `voice_id` resolvability);
foreign voice/model/pipeline references are portable references and are
not resolved by non-owning services. Well-formed compartments for
unrecognized module ids are preserved verbatim and reported as
unverified where a reporting surface exists.
creation: >-
Creation and config load may ingest a full portable document with
compartments for multiple modules, subject to normal authorization and
validation. Omitted `shared`/`modules` normalize to empty objects; a
stored complete record always carries both as objects.
migration: >-
v3.0.0 replaces the v2 flat profile union. The old-field-to-new-path
table, runtime persistence obligations and affected consumers are
recorded in docs/PROFILE_MIGRATION.md.
components:
headers:
OpalSessionIdHeader:
description: Effective OPAL session context for this response. Returned when a session identifier is known;
conditionally present.
required: false
schema:
type: string
minLength: 1
maxLength: 128
OpalTransactionIdHeader:
description: Logical transaction identifier for this exchange. Always returned; generated when the inbound
request lacks one.
required: true
schema:
type: string
minLength: 1
maxLength: 128
OpalRequestIdHeader:
description: Identifier of this inbound HTTP exchange. Always returned; regenerated for each downstream hop.
required: true
schema:
type: string
minLength: 1
maxLength: 128
OpalCausationIdHeader:
description: Immediate parent event/request identifier for this response. Returned when applicable; conditionally
present.
required: false
schema:
type: string
minLength: 1
maxLength: 128
ETag:
description: Strong revision of the portable logical configuration.
schema:
type: string
Location:
description: Canonical path of created resource.
schema:
type: string
parameters:
OpalSessionIdParameter:
name: X-Opal-Session-Id
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 128
pattern: ^[!-~]+$
description: OPAL suite context propagation; opaque and not an authentication credential.
OpalTransactionIdParameter:
name: X-Opal-Transaction-Id
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 128
pattern: ^[!-~]+$
description: OPAL suite context propagation; opaque and not an authentication credential.
OpalRequestIdParameter:
name: X-Opal-Request-Id
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 128
pattern: ^[!-~]+$
description: OPAL suite context propagation; opaque and not an authentication credential.
OpalCausationIdParameter:
name: X-Opal-Causation-Id
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 128
pattern: ^[!-~]+$
description: OPAL suite context propagation; opaque and not an authentication credential.
IfMatch:
name: If-Match
in: header
required: true
description: Required current strong ETag of the complete logical configuration. Missing returns 428, stale
returns 412. One exact strong quoted tag required; weak tags, lists and * are rejected with 422.
schema:
type: string
pattern: ^"[^"]+"$
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: Optional caller-scoped deduplication key for admissions that accept it. Repeating a request
with the same key and an identical request body replays the original admission result; reusing the key
with a different body is rejected with 409 Conflict. Each service documents which operations honor the
key and how long key/fingerprint records are retained.
schema:
type: string
minLength: 1
maxLength: 128
Limit:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 500
default: 100
description: Maximum items to return. Suite cap is 500; callers needing more must
narrow with filters. Applies only to growing collections; bounded catalogs return
everything.
SettingKey:
name: key
in: path
required: true
description: Setting key.
schema:
type: string
minLength: 1
ProfileId:
name: profile_id
in: path
required: true
description: Profile identifier.
schema:
type: string
minLength: 1
example: home
EngineId:
name: engine_id
in: path
required: true
description: Stable implementation-defined identifier of an installed TTS engine.
schema:
type: string
minLength: 1
example: piper
ServiceLogLines:
name: lines
in: query
required: false
description: Number of trailing log lines to return.
schema:
type: integer
minimum: 1
maximum: 1000
default: 10
OpalPersonaIdParameter:
name: persona_id
in: path
required: true
description: Globally unique OPAL persona identifier.
schema:
type: string
minLength: 1
maxLength: 200
pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
example: amy
responses:
BadRequest:
description: Malformed request syntax or invalid parameter encoding.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
Unauthorized:
description: Missing or invalid authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
Forbidden:
description: Authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
NotFound:
description: The addressed resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
Conflict:
description: The request conflicts with current resource state.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
PreconditionFailed:
description: 'If-Match precondition failed: the supplied ETag is stale.'
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
PayloadTooLarge:
description: Request payload exceeds the advertised limit.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
PreconditionRequired:
description: If-Match precondition required but missing.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
UnprocessableEntity:
description: Request was well-formed but failed semantic validation.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
TooManyRequests:
description: Rate limit exceeded; retry after the advertised interval.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
OperationFailed:
description: The operation was accepted but failed during execution.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
ServiceUnavailable:
description: The service or a required dependency is currently unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/OpalError'
headers:
X-Opal-Session-Id:
$ref: '#/components/headers/OpalSessionIdHeader'
X-Opal-Transaction-Id:
$ref: '#/components/headers/OpalTransactionIdHeader'
X-Opal-Request-Id:
$ref: '#/components/headers/OpalRequestIdHeader'
X-Opal-Causation-Id:
$ref: '#/components/headers/OpalCausationIdHeader'
schemas:
OpalErrorBody:
type: object
properties:
code:
type: string
description: Stable machine-readable error code.
message:
type: string
description: Human-readable diagnostic.
details:
description: Structured diagnostic detail; shape is code-specific.
request_id:
type: string
transaction_id:
type: string
session_id:
type:
- string
- 'null'
causation_id:
type:
- string
- 'null'
retryable:
type: boolean
description: Whether the caller may retry the same request.
required:
- code
- message
- request_id
- transaction_id
additionalProperties: false
description: Canonical OPAL suite error body; correlation identifiers mirror the response headers.
OpalError:
type: object
properties:
error:
$ref: '#/components/schemas/OpalErrorBody'
required:
- error
additionalProperties: false
description: Standard OPAL error envelope for all 4xx/5xx JSON responses.
OpalHealthProbe:
type: object
required:
- status
- ready
properties:
status:
type: string
enum:
- ok
- degraded
- unavailable
ready:
type: boolean
details:
type: object
additionalProperties: true
version:
type: string
description: Service implementation version; conditionally present.
additionalProperties: true
OpalHealthReport:
type: object
properties:
name:
type: string
description: Service implementation name.
example: opal-say-svc
version:
type: string
description: Service implementation (package) version.
example: 1.0.0
api_version:
type: string
description: OPAL API contract version.
example: v1
status:
type: string
enum:
- ok
- degraded
- error
description: Overall state using the canonical vocabulary. `degraded` and `error` reports still
return HTTP 200 whenever the report itself can be produced.
live:
type: boolean
description: True while the service process is alive. Carries the information the retired
`GET /api/v1/info/ping` route and `info ping`/`info live` commands used to report.
ready:
type: boolean
description: True when the service can perform useful work. May be false while `live` stays
true; the report still returns HTTP 200 whenever it is available.
details:
type: object
additionalProperties: true
description: 'Module-defined diagnostics, always present (empty object when a module reports no
extra diagnostics). Each module declares its known members via its `x-opal-health-details`
extension: `stats` carries opal-event''s event and execution counters; `audio_devices` carries
opal-listen''s host input device list. Diagnostics that older revisions returned at the top
level (`engines`, `checks`, `components`, `metrics`, `models_available`, `broker_running`,
`database_ready`, `event`, `active_tasks`) now live under this object with their existing
meaning and access requirements.'
active_profile_id:
anyOf:
- type: string
minLength: 1
- type: 'null'
description: Locally active profile id, or null when no profile is active.
checked_at:
type: string
format: date-time
description: Time this report was assembled.
uptime_seconds:
type: number
minimum: 0
pending_restart:
anyOf:
- type: boolean
- type: array
items:
type: string
description: Restart-pending indicator (boolean) or list of pending fields (array); `pending_restart_fields`
is the canonical list form.
pending_restart_fields:
type: array
items:
type: string
required:
- name
- version
- api_version
- status
- live
- ready
- details
additionalProperties: true
description: Aggregate service health report - the single source for service identity, liveness,
readiness and diagnostics. Replaces the retired `GET /api/v1/info/` and `GET /api/v1/info/ping`
reports; module-defined diagnostics live under `details`.
SettingRead:
type: object
properties:
id:
title: Id
type: integer
key:
title: Key
type: string
value:
title: Value
description: Effective native JSON value after environment and .env overlays.
configured_value:
title: Configured Value
description: Persistent desired value before environment/.env overlays; equals the registered
default when no override exists.
updated_at:
format: date-time
title: Updated At
type: string
default:
description: Registered default native JSON value, when safe to expose.
has_override:
type: boolean
description: True when a persistent user override exists for this key.
is_default:
type: boolean
description: True when the effective value comes from the registered default (provenance, not
value equality).
source:
type: string
enum:
- default
- persisted
- dotenv
- environment
description: 'Provenance of the effective value. Precedence, highest first: environment, dotenv,
persisted, default.'
restart_required:
type: boolean
description: True when changing this setting requires a service restart to take effect.
pending_restart:
type: boolean
description: 'For restart-only settings, true when the desired effective value diverges from the
currently running value. An environment-masked persistent edit reports masked (via
`source`/`configured_value`), not pending_restart.'
warnings:
type: array
items:
$ref: '#/components/schemas/OpalValidationIssue'
description: Structured warnings, e.g. an environment overlay masking the persisted value.
required:
- key
- value
- configured_value
- default
- has_override
- is_default
- source
- restart_required
- pending_restart
additionalProperties: true
description: One setting record with effective/configured/default values and provenance metadata.
Lifecycle metadata such as `pending_restart_fields` never appears inside the settings map itself.
SettingUpdate:
type: object
properties:
value:
description: New native JSON value for the setting.
required:
- value
additionalProperties: false
description: Replacement value for a single setting key.
OpalSettingsMap:
type: object
additionalProperties: true
description: 'The complete portable settings map: flat map of registered setting keys to effective
native JSON values. Secret material is never included. Lifecycle metadata such as
`pending_restart_fields` is never mixed into this map.'
OpalValidationReport:
type: object
properties:
valid:
type: boolean
description: True when the validated object/configuration is usable under current validation rules.
errors:
type: array
items:
anyOf:
- type: string
- type: object
description: Diagnostic entries (errors); string or structured object per service.
warnings:
type: array
items:
anyOf:
- type: string
- type: object
description: Diagnostic entries (warnings); string or structured object per service.
details:
type: object
additionalProperties: true
description: Optional implementation-specific validation details.
issues:
type: array
items:
type: object
additionalProperties: true
description: Service-defined section.
resolved_capabilities:
type: array
items:
type: string
estimated_resources:
type: object
additionalProperties: true
required:
- valid
additionalProperties: true
description: Non-mutating validation result. `valid` is suite-standard; remaining fields describe per-service
diagnostics.
OpalValidationIssue:
type: object
properties:
code:
type: string
description: Stable machine-readable issue or warning code.
path:
type: string
description: 'Field or resource path the issue applies to (e.g. `settings.vad.threshold`,
`resources.profiles[2].id`); empty string for whole-snapshot issues.'
message:
type: string
description: Human-readable description of the issue.
required:
- code
- path
- message
additionalProperties: true
description: One structured validation issue or warning.
OpalConfigSnapshot:
type: object
properties:
format_version:
type: string
description: Snapshot envelope format version. This contract accepts `1.0.0` only; other
versions are rejected explicitly.
module:
type: string
minLength: 1
description: 'Canonical module identity (e.g. `opal-listen`). Snapshots for a different module
are rejected before application.'
created_at:
type: string
format: date-time
settings:
type: object
additionalProperties: true
description: 'Flat map of registered setting-key overrides to native JSON values (booleans,
numbers, arrays and objects are never stringified). Unknown setting keys are rejected
explicitly.'
resources:
type: object
additionalProperties: true
description: 'Module-owned declarative configuration sections (e.g. profiles, personas, engine
configurations, voices, wakewords, intents, slots, rules, actions, device definitions, peers,
groups, sharing policies, orchestrator service definitions). `profiles` carries complete
namespaced profile documents - every stored module compartment and the local `is_active`
selection - and foreign compartments are preserved verbatim through save/load. Each module
declares its sections via `x-opal-snapshot.resources`; unknown sections are
rejected explicitly.'
required:
- format_version
- module
- created_at
- settings
- resources
additionalProperties: false
description: 'Versioned portable configuration snapshot. Closed envelope: `settings` and `resources`
are the only variable slots. Contains persistent desired configuration only: credential references
but never secret values; never history, sessions, tasks, streams, generated media, model binaries,
hardware-discovery caches, database files, runtime IDs, or synchronization status.'
OpalConfigSaveRequest:
type: object
properties:
destination:
type: string
enum:
- managed
- response
default: managed
description: '`managed` atomically creates or replaces the module''s default managed snapshot;
`response` returns the snapshot in the body for the caller to store (CLI `config save --out`
maps here) and never replaces the managed snapshot.'
additionalProperties: false
OpalConfigSaveResult:
type: object
properties:
snapshot:
$ref: '#/components/schemas/OpalConfigSnapshot'
managed:
type: boolean
description: True when the default managed snapshot was written.
required:
- snapshot
- managed
additionalProperties: true
OpalConfigLoadRequest:
type: object
properties:
snapshot:
$ref: '#/components/schemas/OpalConfigSnapshot'
description: 'Candidate snapshot. Omit or send `{}` to load the managed snapshot; an explicit
null is invalid.'
additionalProperties: false
OpalConfigLoadResult:
type: object
properties:
applied:
type: boolean
const: true
description: 'Always true on HTTP 200; failed loads use the shared error envelope, never
`applied: false`.'
pending_restart_fields:
type: array
items:
type: string
description: Setting keys whose new values require a service restart to take effect.
warnings:
type: array
items:
$ref: '#/components/schemas/OpalValidationIssue'
required:
- applied
additionalProperties: true
OpalConfigValidateRequest:
type: object
properties:
snapshot:
type: object
description: 'Candidate snapshot to validate. Typed loosely as a JSON object so malformed
envelopes are reported as structured issues rather than rejected as a malformed request;
an explicit null is invalid. Omit to validate the current live configuration.'
additionalProperties: false
OpalConfigValidation:
type: object
properties:
valid:
type: boolean
description: True exactly when `errors` is empty.
errors:
type: array
items:
$ref: '#/components/schemas/OpalValidationIssue'
warnings:
type: array
items:
$ref: '#/components/schemas/OpalValidationIssue'
required:
- valid
- errors
- warnings
additionalProperties: true
description: 'Non-mutating configuration validation result. Load performs equivalent checks
internally; a prior successful validate call never bypasses load checks.'
OpalLifecycleStatus:
type: string
description: 'Shared lifecycle vocabulary for asynchronous work (tasks, executions,
steps). Terminal states are completed, failed, cancelled, and timed_out. A service may
document additional terminal states for its own semantics — for example EVENT adds
dropped for executions lost to queue saturation — but it must use these names for
these concepts.'
enum:
- queued
- running
- completed
- failed
- cancelled
- timed_out
OpalProfile:
type: object
properties:
id:
type: string
minLength: 1
readOnly: true
description: Opaque profile identifier.