Schema

A schema describes how a service should be presented: names, units, descriptions, enums, value ranges, display formats and callable methods — per service identifier, so one schema covers every device exposing that service. Schemas live in the backend and are not enforced on the device: labels, enums and units can change without touching firmware.

Property ids use the same canonical hex form (0x0800) as the flake module, so schema entries match property listings directly, no conversion needed. Methods declared here are callable via POST /devices/…/messages/{name}.

POST	Create a schema/api/v1/schema
GET	List schemas/api/v1/schema
GET	Read one schema/api/v1/schema/:serviceIdentifier
PATCH	Update a schema/api/v1/schema/:serviceIdentifier
DELETE	Delete a schema/api/v1/schema/:serviceIdentifier

Create a schema

Stores the schema for a service identifier — one per service, shared by every device exposing it.

POST/api/v1/schema

Body

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
namestring	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarray	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarray	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
tenantIdstringoptional	Tenant to create the schema in; defaults to the caller's tenant. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409	A schema for this service identifier already exists; change it with PATCH.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

List schemas

Lists every schema of the tenant; depth=1 includes the full entries.

GET/api/v1/schema?depth=0

Query Parameters

Name	Description
depthintegeroptional	How many levels of nested resources the response includes; 0 returns only the top level. Default: 0 min 0

Response

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
schemaobjectoptionaldepth ≥ 1	The full schema entry; included at depth ≥ 1.
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
namestring	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarray	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarray	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Read one schema

The schema stored for this service identifier.

GET/api/v1/schema/00000000-0000-2001-8003-006d0099ab53

Path Parameters

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Response

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
namestring	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarray	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarray	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No schema stored for this service identifier.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Update a schema

Merges changes into the stored schema. List entries are matched by id (properties) or name (methods); remove: true deletes the matched entry.

PATCH/api/v1/schema/00000000-0000-2001-8003-006d0099ab53

Path Parameters

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Body

Name	Description
namestringoptional	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarrayoptional	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
removeoptional	Delete the matched entry instead of merging into it.
namestringoptional	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeoptionalenum	Wire type of the property (UINT16, FLOAT, STRING, …). Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
removeoptional	Delete the matched entry instead of merging into it.
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarrayoptional	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No schema stored for this service identifier.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The merged result of the PATCH would not be a valid schema — e.g. a new property added without its required fields. message says what is wrong.	message: string
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Delete a schema

Removes the schema of this service identifier.

DELETE/api/v1/schema/00000000-0000-2001-8003-006d0099ab53

Path Parameters

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No schema stored for this service identifier.
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Events

Published on the tenant's event stream and delivered over the websocket to every subscriber holding read on the resource the message names. resourceIdentifier is the resource the action changed; the payload is the shape below.

Event	Description
SCHEMA_CREATE	A service schema was created.
SCHEMA_DELETE	A service schema was removed.
SCHEMA_UPDATE	A service schema was changed.

Schema created

A service schema was created.

EVENTSCHEMA_CREATE

Payload

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
namestring	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarray	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarray	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource

Schema deleted

A service schema was removed.

EVENTSCHEMA_DELETE

Payload

Name	Description

Schema updated

A service schema was changed.

EVENTSCHEMA_UPDATE

Payload

Name	Description
serviceIdentifierstring	Service identifier (UUID) the schema applies to — shared by every device exposing the service. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
namestring	Human-readable name of the service. min length 1 · max length 64
descriptionstringoptional	What the service is, for readers of the schema.
propertiesarray	Property entries of the service, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name shown instead of the numeric id, e.g. temperature. min length 1 · max length 64
descriptionstringoptional	What the property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values, unique by value — lets a UI render a dropdown instead of a numeric input.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
rangeMinnumberoptional	Minimum (inclusive); numeric types only.
rangeMaxnumberoptional	Maximum (exclusive); numeric types only.
unitstringoptional	Unit label, e.g. °C.
readonlybooleanoptional	UI hint: do not offer editing. The device that transmitted the property has the final say.
actionablebooleanoptional	UI hint: writing triggers an action rather than storing a value.
groupstringoptional	Groups properties into subjects for presentation.
hintstringoptional	Free-text hint about the content, e.g. marking a property as a script or an email.
displayobjectoptional	How the raw value is rendered for a reader; absent means “as transmitted”. Fields slice the value, a template words the result.
fieldsarray
keystring	Pattern: ^[a-z][a-z0-9_]{0,15}$
offsetintegeroptional	min 0 · max 63
widthintegeroptional	min 1 · max 64
render
Alternative 1object
kind
radixoptional
Alternative 1
Alternative 2
uppercasebooleanoptional
Alternative 2object
kind
factornumber
offsetnumberoptional
decimalsinteger	min 0 · max 6
Alternative 3object
kind
sizeinteger	min 1 · max 16
radix
Alternative 1
Alternative 2
separatorstring	min length 1 · max length 2 Pattern: ^[.:\-/ ]+$
padbooleanoptional
uppercasebooleanoptional
Alternative 4object
kind
refstring	Pattern: ^[a-z0-9][a-z0-9-]{1,62}$
textstringoptional	min length 1 · max length 120
i18ndictionaryoptional
separatorstringoptional	min length 1 · max length 4 Pattern: ^[,;|/·\-\s]+$
i18ndictionaryoptional	Translations of name, description and group, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
groupstringoptional	Translated group label.
methodsarrayoptional	Methods callable on the service via POST …/messages/{name}, unique by name.
namestring	Method name — also the URL segment of the call. min length 1 · max length 64
descriptionstringoptional	What the method does.
parametersarrayoptional	Parameters the method takes, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Parameter name. min length 1 · max length 64
descriptionstringoptional	What the parameter means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
optionalbooleanoptional	May be omitted in the call.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
successarray	Properties the device returns on success, unique by id.
idstring	Property id in canonical form: 0x + four uppercase hex digits (e.g. 0x0800), exactly as flake property listings report it. Pattern: ^(0x|0X)?[0-9a-fA-F]+$
namestring	Name of the returned property. min length 1 · max length 64
descriptionstringoptional	What the returned property means.
typeenum	Wire type of the returned property. Possible values: uint8, uint16, uint32, uint64, int8, int16, int32, int64, bool, uuid, float, float64, datetime, string, binary, binary-stream, string-stream, int64-array, int32-array, int16-array, int8-array, uint64-array, uint32-array, uint16-array, uint8-array, bool-array, uuid-array, float64-array, float-array, datetime-array, string-array
enumarrayoptional	Named values of the returned property.
valuestring	The raw value as the device transmits it. min length 1
namestring	Label shown for the value. min length 1 · max length 64
descriptionstringoptional	What the value means.
i18ndictionaryoptional	Translations of the label, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
failurearrayoptional	Maps device error codes to human labels, unique by code.
codestring	Error code as the device reports it. min length 1
namestring	Label shown for the error. min length 1 · max length 64
descriptionstringoptional	What the error means.
i18ndictionaryoptional	Translations, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
i18ndictionaryoptional	Translations of name and description, keyed by locale.
namestringoptional	Translated name. min length 1 · max length 64
descriptionstringoptional	Translated description.
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource