A JSON Schema of the messages

GET

/gateway/{alias}/v1/schemas/{file}

curl --request GET \
  --url https://example.com/gateway/example/v1/schemas/common.json \
  --header 'Authorization: Bearer <token>'

One JSON Schema (draft 2020-12) per message, as {name}.json; cross-references are relative, so the schemas resolve side by side. The same schemas are the components of this description.

Authorizations

• appKey
• appKeyHeader
• controlPlane

Parameters

Path Parameters

alias

required

string

The connection (abonnement) to call through, as Verbindingen in the connector names it.

file

required

string

Allowed values: common.json point.json equipment.json location.json discover-response.json readings-response.json setpoint-write.json fallback-policy-patch.json building-command.json topology-response.json receipt.json error.json

{name}.json, e.g. point.json.

Responses

200

The schema.

Media typeapplication/schema+json

object

Example ^generated

{}

401

From the backend: unauthenticated: no or a wrong key. From the gateway: unauthenticated: no key, an unknown key, or an invalid token of the control plane.

Media typeapplication/json

Any of:

ErrorResponse

ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object

buildinglinks_version

required

Protocol version, carried by every response.

string

/^1\.[0-9]+$/

building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string

>= 1 characters

error

required

object

code

required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string

message

required

string

retryable

required

boolean

target

Which field caused it, for example setpoints[0].value.

string

retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string

/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/

details

Array<object> recursive

object

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "invalid_request"
  }
}

403

forbidden: the key lacks the gateway scope, its app may not use this connection, or the app may only read. The provider’s data plane refuses with 403 what the agreement does not cover.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}

404

not_found: no schema with this name.

Media typeapplication/json

ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object

buildinglinks_version

required

Protocol version, carried by every response.

string

/^1\.[0-9]+$/

building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string

>= 1 characters

error

required

object

code

required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string

message

required

string

retryable

required

boolean

target

Which field caused it, for example setpoints[0].value.

string

retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string

/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/

details

Array<object> recursive

Example

{
  "error": {
    "code": "invalid_request"
  }
}

502

upstream_unavailable: the provider’s data plane could not be reached, its answer was larger than 16 MiB, or, when the agreement requires signed requests, its answer had no valid signature.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}

503

upstream_unavailable: the connection is not active (yet), or renewing the access token failed; evidence_unavailable: the agreement requires signed requests and the request or answer could not be recorded; standby: another instance of this data plane is active. Retryable.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object

error

required

object

code

required

string

message

required

string

retryable

required

Whether the same request may succeed later.

boolean

Example

{
  "error": {
    "code": "forbidden"
  }
}