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/…)

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)

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.