Interface
This schema describes how an Data Orchestrator interface should be declared.
Properties Summary
| Property | Type | Description | Required |
|---|---|---|---|
| interface_name | string | The name of the interface. This has to be an unique, alphanumeric reverse internet domain name, shorter than 128 characters. | ✔ Yes |
| version_major | integer | A Major version qualifier for this interface. Interfaces with the same id and different version_major number are deemed incompatible. It is then acceptable to redefine any property of the interface when changing the major version number. | ✔ Yes |
| version_minor | integer | A Minor version qualifier for this interface. Interfaces with the same id and major version number and different version_minor number are deemed compatible between each other. When changing the minor number, it is then only possible to insert further mappings. Any other modification might lead to incompatibilities and undefined behavior. | ✔ Yes |
| type | string | Identifies the type of this Interface. Currently two types are supported: datastream and properties. datastream should be used when dealing with streams of non-persistent data, where a single path receives updates and there's no concept of state. properties, instead, are meant to be an actual state and as such they have only a change history, and are retained. | ✔ Yes |
| ownership | string | Identifies the quality of the interface. Interfaces are meant to be unidirectional, and this property defines who's sending or receiving data. device means the device/gateway is sending data to Data Orchestrator, consumer means the device/gateway is receiving data from Data Orchestrator. Bidirectional mode is not supported, you should instantiate another interface for that. | ✔ Yes |
| aggregation | string | Identifies the aggregation of the mappings of the interface. Individual means every mapping changes state or streams data independently, whereas an object aggregation treats the interface as an object, making all the mappings changes interdependent. Choosing the right aggregation might drastically improve performances. | No, default: "individual" |
| description | string | An optional description of the interface. | No |
| doc | string | A string containing documentation that will be injected in the generated client code. | No |
| mappings | Data Orchestrator Mapping Schema [1-1024] | Mappings define the endpoint of the interface, where actual data is stored/streamed. They are defined as relative URLs (e.g. /my/path) and can be parametrized (e.g.: /%{myparam}/path). A valid interface must have no mappings clash, which means that every mapping must resolve to a unique path or collection of paths (including parametrization). Every mapping acquires type, quality and aggregation of the interface. | ✔ Yes |
Property Details
astarte.interface.schema.interface_name ✔
The name of the interface. This has to be an unique, alphanumeric reverse internet domain name, shorter than 128 characters.
- Type:
string - Required: Yes
- Minimum Length:
>= 1 - Allowed Pattern:
^([a-zA-Z][a-zA-Z0-9]*.([a-zA-Z0-9][a-zA-Z0-9-]*.)*)?[a-zA-Z][a-zA-Z0-9]*$
astarte.interface.schema.version_major ✔
A Major version qualifier for this interface. Interfaces with the same id and different version_major number are deemed incompatible. It is then acceptable to redefine any property of the interface when changing the major version number.
- Type:
integer - Required: Yes
astarte.interface.schema.version_minor ✔
A Minor version qualifier for this interface. Interfaces with the same id and major version number and different version_minor number are deemed compatible between each other. When changing the minor number, it is then only possible to insert further mappings. Any other modification might lead to incompatibilities and undefined behavior.
- Type:
integer - Required: Yes
astarte.interface.schema.type ✔
Identifies the type of this Interface. Currently two types are supported: datastream and properties. datastream should be used when dealing with streams of non-persistent data, where a single path receives updates and there's no concept of state. properties, instead, are meant to be an actual state and as such they have only a change history, and are retained.
- Type:
string - Required: Yes
- Allowed values:
"datastream""properties"
astarte.interface.schema.ownership ✔
Identifies the quality of the interface. Interfaces are meant to be unidirectional, and this property defines who's sending or receiving data. device means the device/gateway is sending data to Data Orchestrator, server means the server is sending data. Bidirectional mode is not supported, you should instantiate another interface for that.
- Type:
string - Required: Yes
- Allowed values:
"device""server"
astarte.interface.schema.aggregation
Identifies the aggregation of the mappings of the interface. individual means every mapping changes state or streams data independently, whereas an object aggregation treats the interface as an object, making all the mappings changes interdependent. Choosing the right aggregation might drastically improve performances.
- Type:
string - Required: No, default:
"individual" - Allowed values:
"individual""object"
astarte.interface.schema.description
An optional description of the interface.
- Type:
string - Required: No
astarte.interface.schema.doc
A string containing documentation that will be injected in the generated client code.
- Type:
string - Required: No
astarte.interface.schema.mappings ✔
Mappings define the endpoint of the interface, where actual data is stored/streamed. They are defined as relative URLs (e.g. /my/path) and can be parametrized (e.g.: /%{myparam}/path). A valid interface must have no mappings clash, which means that every mapping must resolve to a unique path or collection of paths (including parametrization). Every mapping acquires type, quality and aggregation of the interface.
- Type: Array of
Data Orchestrator Mapping Schema[1-1024] - Required: Yes