Schema

Description

The schema module handles the mapping from arbitrary identifier to human readable format. It defines all the required mappings to ensure every service or property identifier can be mapped to human readable format and provide further information about available methods or for example unit information for a given service.

Events

Following events are transmitted via the websocket.

SCHEMA_ADD

SCHEMA_UPDATE

SCHEMA_DELETE

This event will be sent over the websocket when a new schema is added. This event requires read access to the resource schemas.

Name	Description
type stringconstant	Constant value: SCHEMA_ADD
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
schema object
schema.name string	The name for the given service.
schema.description stringoptional	The service entry description.
schema.properties dictionary	Any properties in this Service. The keys of this object need to be a hex-string in the format `0x0....0`. The key does represent the number that identifies a property.
schema.properties. #.name string	The property name
schema.properties. #.description stringoptional	An optional property description
schema.properties. #.type stringenum	The property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.enum. #.name string	The property name
schema.properties. #.enum. #.description stringoptional	Optional enum description
schema.properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
schema.properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
schema.properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
schema.properties. #.readonly booleanoptional	Whenever the property is readonly or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
schema.properties. #.actionable booleanoptional	Whenever the property is actionable or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
schema.properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
schema.properties. #.hint stringoptional	Any hint for given property. Freetext, that can for example be used to indicate a property is a `script` or an `email` or anything else.
schema.properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
schema.properties. #.translations dictionaryoptional
schema.properties. #.translations. #.name stringoptional	The property name
schema.properties. #.translations. #.description stringoptional	An optional property description
schema.properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
schema.properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.translations. #.enum. #.name string	The property name
schema.properties. #.translations. #.enum. #.description stringoptional	Optional enum description
schema.methods dictionaryoptional	Any methods that this Service exposes for usage. The key used for each method will be the method name.
schema.methods. #.description stringoptional	Description of a method
schema.methods. #.parameters dictionaryoptional	A set of input parameters for this method.
schema.methods. #.parameters. #.name string	The human readable parameter name.
schema.methods. #.parameters. #.description stringoptional	The parameter description.
schema.methods. #.parameters. #.type stringenum	The parameter type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.methods. #.parameters. #.optional booleanoptional	Whenever this parameter is optional or not.
schema.methods. #.success dictionary	Any properties returned with a successful method call
schema.methods. #.success. #.name string	The human returned property name.
schema.methods. #.success. #.description stringoptional	The returned property description.
schema.methods. #.success. #.type stringenum	The returned property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.methods. #.success. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.methods. #.success. #.enum. #.name string	The property name
schema.methods. #.success. #.enum. #.description stringoptional	Optional enum description
schema.methods. #.failure dictionaryoptional	A enum-like mapping of error-codes to human values
schema.methods. #.failure. #.name string	The error name.
schema.methods. #.failure. #.description stringoptional	The errod description.
schema.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
schema.translations dictionaryoptional
schema.translations. #.name stringoptional	The name for the given service.
schema.translations. #.description stringoptional	The service entry description.

API

Endpoints

GET

Get Schemas

POST

Create Schema

GET

Get Schema

PATCH

Update a Schema

DEL

Delete single Schema

Get Schemas

Returns a list of service identifier for which a schema has been created. Using the query parameter depth will return the schema directly in combination with the service identifier.

GET

/api/v1/schemas

Access

This endpoint requires read permission for the resource schemas.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.
lang stringoptional	A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated booleanoptional	Whenever to return the config as is or translate specific fields

Response

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
schema objectoptional	The service definition for that service identifier. Returned when the depth query parameter is used.
schema.name string	The name for the given service.
schema.description stringoptional	The service entry description.
schema.properties dictionary	Any properties in this Service. The keys of this object need to be a hex-string in the format `0x0....0`. The key does represent the number that identifies a property.
schema.properties. #.name string	The property name
schema.properties. #.description stringoptional	An optional property description
schema.properties. #.type stringenum	The property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.enum. #.name string	The property name
schema.properties. #.enum. #.description stringoptional	Optional enum description
schema.properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
schema.properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
schema.properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
schema.properties. #.readonly booleanoptional	Whenever the property is readonly or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
schema.properties. #.actionable booleanoptional	Whenever the property is actionable or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
schema.properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
schema.properties. #.hint stringoptional	Any hint for given property. Freetext, that can for example be used to indicate a property is a `script` or an `email` or anything else.
schema.properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
schema.properties. #.translations dictionaryoptional
schema.properties. #.translations. #.name stringoptional	The property name
schema.properties. #.translations. #.description stringoptional	An optional property description
schema.properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
schema.properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.properties. #.translations. #.enum. #.name string	The property name
schema.properties. #.translations. #.enum. #.description stringoptional	Optional enum description
schema.methods dictionaryoptional	Any methods that this Service exposes for usage. The key used for each method will be the method name.
schema.methods. #.description stringoptional	Description of a method
schema.methods. #.parameters dictionaryoptional	A set of input parameters for this method.
schema.methods. #.parameters. #.name string	The human readable parameter name.
schema.methods. #.parameters. #.description stringoptional	The parameter description.
schema.methods. #.parameters. #.type stringenum	The parameter type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.methods. #.parameters. #.optional booleanoptional	Whenever this parameter is optional or not.
schema.methods. #.success dictionary	Any properties returned with a successful method call
schema.methods. #.success. #.name string	The human returned property name.
schema.methods. #.success. #.description stringoptional	The returned property description.
schema.methods. #.success. #.type stringenum	The returned property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
schema.methods. #.success. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
schema.methods. #.success. #.enum. #.name string	The property name
schema.methods. #.success. #.enum. #.description stringoptional	Optional enum description
schema.methods. #.failure dictionaryoptional	A enum-like mapping of error-codes to human values
schema.methods. #.failure. #.name string	The error name.
schema.methods. #.failure. #.description stringoptional	The errod description.
schema.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
schema.translations dictionaryoptional
schema.translations. #.name stringoptional	The name for the given service.
schema.translations. #.description stringoptional	The service entry description.

Create Schema

Using this endpoint will create a new service definition if not present.

POST

/api/v1/schemas

Access

This endpoint requires create permission for the resource schemas.

Request Body

Name	Description
$id stringoptional	The specific Flake-Schemas ID. This should be a URL to the schema document.
$schema stringoptional	The Flake Schema used to describe this specific schema. This also clarifies which version of the Flake Schema is used
title stringoptional	A title for the specific schema
services dictionary	The object that contains the services. The keys of this objects
services. #.name string	The name for the given service.
services. #.description stringoptional	The service entry description.
services. #.properties dictionary	Any properties in this Service. The keys of this object need to be a hex-string in the format `0x0....0`. The key does represent the number that identifies a property.
services. #.properties. #.name string	The property name
services. #.properties. #.description stringoptional	An optional property description
services. #.properties. #.type stringenum	The property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
services. #.properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
services. #.properties. #.enum. #.name string	The property name
services. #.properties. #.enum. #.description stringoptional	Optional enum description
services. #.properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
services. #.properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
services. #.properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
services. #.properties. #.readonly booleanoptional	Whenever the property is readonly or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
services. #.properties. #.actionable booleanoptional	Whenever the property is actionable or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
services. #.properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
services. #.properties. #.hint stringoptional	Any hint for given property. Freetext, that can for example be used to indicate a property is a `script` or an `email` or anything else.
services. #.properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
services. #.properties. #.translations dictionaryoptional
services. #.properties. #.translations. #.name stringoptional	The property name
services. #.properties. #.translations. #.description stringoptional	An optional property description
services. #.properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
services. #.properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
services. #.properties. #.translations. #.enum. #.name string	The property name
services. #.properties. #.translations. #.enum. #.description stringoptional	Optional enum description
services. #.methods dictionaryoptional	Any methods that this Service exposes for usage. The key used for each method will be the method name.
services. #.methods. #.description stringoptional	Description of a method
services. #.methods. #.parameters dictionaryoptional	A set of input parameters for this method.
services. #.methods. #.parameters. #.name string	The human readable parameter name.
services. #.methods. #.parameters. #.description stringoptional	The parameter description.
services. #.methods. #.parameters. #.type stringenum	The parameter type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
services. #.methods. #.parameters. #.optional booleanoptional	Whenever this parameter is optional or not.
services. #.methods. #.success dictionary	Any properties returned with a successful method call
services. #.methods. #.success. #.name string	The human returned property name.
services. #.methods. #.success. #.description stringoptional	The returned property description.
services. #.methods. #.success. #.type stringenum	The returned property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
services. #.methods. #.success. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
services. #.methods. #.success. #.enum. #.name string	The property name
services. #.methods. #.success. #.enum. #.description stringoptional	Optional enum description
services. #.methods. #.failure dictionaryoptional	A enum-like mapping of error-codes to human values
services. #.methods. #.failure. #.name string	The error name.
services. #.methods. #.failure. #.description stringoptional	The errod description.
services. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
services. #.translations dictionaryoptional
services. #.translations. #.name stringoptional	The name for the given service.
services. #.translations. #.description stringoptional	The service entry description.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get Schema

Returns the definition for a given service identifier

GET

/api/v1/schemas/:serviceIdentifier

Access

This endpoint requires read permission for the resource schemas.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.

Query Parameter

Name	Description
lang stringoptional	A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated booleanoptional	Whenever to return the config as is or translate specific fields

Response

Name	Description
name string	The name for the given service.
description stringoptional	The service entry description.
properties dictionary	Any properties in this Service. The keys of this object need to be a hex-string in the format `0x0....0`. The key does represent the number that identifies a property.
properties. #.name string	The property name
properties. #.description stringoptional	An optional property description
properties. #.type stringenum	The property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.enum. #.name string	The property name
properties. #.enum. #.description stringoptional	Optional enum description
properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
properties. #.readonly booleanoptional	Whenever the property is readonly or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
properties. #.actionable booleanoptional	Whenever the property is actionable or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
properties. #.hint stringoptional	Any hint for given property. Freetext, that can for example be used to indicate a property is a `script` or an `email` or anything else.
properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
properties. #.translations dictionaryoptional
properties. #.translations. #.name stringoptional	The property name
properties. #.translations. #.description stringoptional	An optional property description
properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.translations. #.enum. #.name string	The property name
properties. #.translations. #.enum. #.description stringoptional	Optional enum description
methods dictionaryoptional	Any methods that this Service exposes for usage. The key used for each method will be the method name.
methods. #.description stringoptional	Description of a method
methods. #.parameters dictionaryoptional	A set of input parameters for this method.
methods. #.parameters. #.name string	The human readable parameter name.
methods. #.parameters. #.description stringoptional	The parameter description.
methods. #.parameters. #.type stringenum	The parameter type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
methods. #.parameters. #.optional booleanoptional	Whenever this parameter is optional or not.
methods. #.success dictionary	Any properties returned with a successful method call
methods. #.success. #.name string	The human returned property name.
methods. #.success. #.description stringoptional	The returned property description.
methods. #.success. #.type stringenum	The returned property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
methods. #.success. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
methods. #.success. #.enum. #.name string	The property name
methods. #.success. #.enum. #.description stringoptional	Optional enum description
methods. #.failure dictionaryoptional	A enum-like mapping of error-codes to human values
methods. #.failure. #.name string	The error name.
methods. #.failure. #.description stringoptional	The errod description.
__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
translations dictionaryoptional
translations. #.name stringoptional	The name for the given service.
translations. #.description stringoptional	The service entry description.

Update a Schema

This endpoint can be used by sending a partial service definition. This definition will be merged with the current one. Duplicate keys will be overwritten.

PATCH

/api/v1/schemas/:serviceIdentifier

Access

This endpoint requires update permission for the resource schemas.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.

Request Body

Name	Description
name stringoptional	The name for the given service.
description stringoptional	The service entry description.
properties dictionaryoptional	Any properties in this Service. The keys of this object need to be a hex-string in the format `0x0....0`. The key does represent the number that identifies a property.
properties. #.name stringoptional	The property name
properties. #.type stringoptionalenum	The property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
properties. #.description stringoptional	An optional property description
properties. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.enum. #.name string	The property name
properties. #.enum. #.description stringoptional	Optional enum description
properties. #.rangeMin numberoptional	Applicable to numeric types, this specifies the minimum value, range inclusive.
properties. #.rangeMax numberoptional	Applicable to numeric type, this specifies the maximum value, range exclusive.
properties. #.unit stringoptional	Applicable to any type (most likely numeric), specifies the unit of the value
properties. #.readonly booleanoptional	Whenever the property is readonly or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
properties. #.actionable booleanoptional	Whenever the property is actionable or not. This will only act as a hint to the backend and the user interface. The final say has the device that actually transmitted the property.
properties. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
properties. #.hint stringoptional	Any hint for given property. Freetext, that can for example be used to indicate a property is a `script` or an `email` or anything else.
properties. #.__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
properties. #.translations dictionaryoptional
properties. #.translations. #.name stringoptional	The property name
properties. #.translations. #.description stringoptional	An optional property description
properties. #.translations. #.group stringoptional	The group the property belongs to. Can be used to further organize properties to different subjects.
properties. #.translations. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
properties. #.translations. #.enum. #.name string	The property name
properties. #.translations. #.enum. #.description stringoptional	Optional enum description
methods dictionaryoptional	Any methods that this Service exposes for usage. The key used for each method will be the method name.
methods. #.description stringoptional	Description of a method
methods. #.parameters dictionaryoptional	A set of input parameters for this method.
methods. #.parameters. #.name stringoptional	The human readable parameter name.
methods. #.parameters. #.description stringoptional	The parameter description.
methods. #.parameters. #.type stringenum	The parameter type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
methods. #.parameters. #.optional booleanoptional	Whenever this parameter is optional or not.
methods. #.success dictionaryoptional	Any properties returned with a successful method call
methods. #.success. #.name string	The human returned property name.
methods. #.success. #.description stringoptional	The returned property description.
methods. #.success. #.type stringenum	The returned property type Possible values: uint8, uint16, uint32, int8, int16, int32, bool, uuid, float, datetime, string, binary, binary-stream, string-stream
methods. #.success. #.enum dictionaryoptional	Treat this property as an enumeration and map the values as follows
methods. #.success. #.enum. #.name string	The property name
methods. #.success. #.enum. #.description stringoptional	Optional enum description
methods. #.failure dictionaryoptional	A enum-like mapping of error-codes to human values
methods. #.failure. #.name string	The error name.
methods. #.failure. #.description stringoptional	The error description.
__i18nSupport booleanoptional	A required key for easier parsing when actually using translations. Default: true
translations dictionaryoptional
translations. #.name stringoptional	The name for the given service.
translations. #.description stringoptional	The service entry description.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete single Schema

Delete a single given schema.

DELETE

/api/v1/schemas/:serviceIdentifier

Access

This endpoint requires delete permission for the resource schemas.

URL Parameter

Name	Description
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.