Ids and errors
Это содержимое пока не доступно на вашем языке.
Reference for schemas/common/1.0/ids.schema.json, units.schema.json and problem.schema.json
. Licence: NativeMindNONC.
Identifiers (ids.schema.json#/$defs/…)
Section titled “Identifiers (ids.schema.json#/$defs/…)”| Definition | Format | Used for |
|---|---|---|
uuidv7 |
lowercase UUIDv7 xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx |
server-owned resources (assets, jobs, uploads, sessions, envelope id) |
uuid |
any lowercase UUID | ids written by older tools (e.g. .dome meta.id) |
docId |
^[A-Za-z0-9._-]{1,64}$, unique within the parent |
.dome displays, assets, playlists, cues; nested path segments |
venueRef |
docId or default |
{venueId} path parameter |
playerRef |
docId or main |
{playerId} path parameter |
revision |
integer ≥ 0 | resource revision; strong ETag derived from it |
sha256 |
64 lowercase hex | asset / download digests, ETag of downloads |
semver |
SemVer 2.0.0 | versions in getInfo, contract releases |
topic |
seg(/seg)*, seg = [A-Za-z0-9._-]+ |
concrete event topics |
topicFilter |
topic with + levels and an optional final # |
subscriptions |
operationId |
camelCase | OpenAPI operations = WS / socket.io call ops |
scope |
<area>:<action> |
authorisation scopes |
Units (units.schema.json#/$defs/…): timestamp (RFC 3339 UTC with ms, …T12:00:00.000Z), seconds,
position, metres, degrees, hertz, unitInterval (0..1: brightness, linear volume, progress), gainDb
(−144..+24), colour (#rrggbb), mediaType. Localised text: i18n-text.schema.json ({"en": "…", "ru": "…"};
#/$defs/textOrI18n also accepts a plain string).
Errors (problem.schema.json)
Section titled “Errors (problem.schema.json)”RFC 9457 problem details, media type application/problem+json. Required: type, title, code; usual: status,
detail, instance, traceId, errors[] ({pointer, detail, code?}, JSON Pointer into the request body).
code is the stable machine key and the last path segment of type
(https://freedome.nativemind.us/problems/<code>). The same object is the data of a WS error message, the
socket.io ack error and GraphQL errors[].extensions.problem.
The catalogue is open (new codes are a minor change; clients map unknown codes by status). For catalogue codes
the schema binds the HTTP status:
code |
status |
When |
|---|---|---|
validation-failed |
422 | body / parameters invalid; errors[] lists the fields |
not-found |
404 | resource or alias unknown |
conflict |
409 | state conflict, same Idempotency-Key with a different body, delete while playing |
precondition-failed |
412 | If-Match stale; detail carries the current revision |
precondition-required |
428 | If-Match missing on a venue / show / playlist / timeline / cue / layout / config update |
unauthenticated |
401 | no / invalid / expired token; cloud token on an unlinked installation |
forbidden |
403 | missing scope (detail names it) |
rate-limited |
429 | with Retry-After, RateLimit, RateLimit-Policy |
payload-too-large |
413 | JSON body > 4 MB, archive limits |
unsupported-format |
415 | unknown media / content format |
engine-unavailable |
503 | freedome-engined (or an audio engine) not reachable |
engine-incompatible |
503 | engine protocol version not supported |
degraded |
503 | service running with reduced capability |
job-failed |
— | inside job results (Job.problem), no HTTP status of its own |
upload-checksum-mismatch |
422 | tus upload finished with a wrong sha256 |
legacy-unsupported |
501 | legacy-profile request with no native equivalent |
internal |
500 | unexpected server error (traceId for support) |
clock-unlocked |
409 | multi-node scheduled start / seek refused: a node clock is not locked within the sync threshold |
not-configured |
503 | feature needs configuration / credentials that are not set (e.g. OAuth provider, SMTP) |
authorization-pending |
400 | RFC 8628 device flow: the user has not approved yet — poll again after interval |
slow-down |
400 | RFC 8628 device flow: polling too fast — increase the interval |
access-denied |
403 | RFC 8628 device flow: the request was denied |
expired-token |
400 | RFC 8628 device flow: the device code expired |
token-reused |
401 | a rotated refresh token was presented again; the whole token family is revoked |
idempotency-key-reused |
409 | same Idempotency-Key with a different request body |
idempotency-in-progress |
409 | the first request with this Idempotency-Key is still running |
Codes added at the v1.0.0 freeze (from MS / CL rc feedback): clock-unlocked … idempotency-in-progress above.
Extension members in use (problem objects are open; clients ignore unknown members): scope (forbidden), reason,
retryAfter, interval (device flow), feature (not-configured), ownedOrganisations (cloud account deletion),
requestId (cloud), revision (precondition-failed).
Examples: examples/common/{valid,invalid}/problem--*.json.