-
Notifications
You must be signed in to change notification settings - Fork 216
/
protocol-envelope.json
107 lines (107 loc) · 4.69 KB
/
protocol-envelope.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "The Ditto Protocol envelope of a Ditto Protocol message. This wraps the actual payload in the `value` field.",
"title": "Ditto Protocol envelope",
"properties": {
"topic": {
"type": "string",
"description": "Contains information about the contents of the payload:\n * the affected Thing (namespace and Thing ID)\n * the type of operation (command/event, create/retrieve/modify/delete) \n\nExample: `com.acme/xdk_53/things/twin/commands/modify`"
},
"headers": {
"type": "object",
"description": "Additional headers.",
"properties": {
"content-type": {
"type": "string",
"description": "The content-type which describes the value of Ditto Protocol messages."
},
"correlation-id": {
"type": "string",
"description": "The correlation-id header is used for linking one message with another. It typically links a reply message with its requesting message."
},
"ditto-originator": {
"type": "string",
"description": "Contains the first authorization subject of the command that caused the sending of this message. Set by Ditto."
},
"If-Match": {
"type": "string",
"description": "The `If-Match` header which has to conform to RFC-7232 (Conditional Requests). Common usages are:\n * optimistic locking by specifying the `ETag` from a previous response, e.g. `If-Match: \"hash:a75ece4e\"`\n * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`"
},
"If-None-Match": {
"type": "string",
"description": "The `If-None-Match` header which has to conform to RFC-7232 (Conditional Requests)."
},
"if-equal": {
"type": "string",
"description": "The `if-equal` header can take the values 'update' (which is the default if omitted) or 'skip'.\nIf 'update' is defined, the entity will always be updated, even if it will be equal than before the update.\nIf 'skip' is defined, the entity not be updated if it will be equal than before the update. In this case a 'Not Modified' 304 status is returned."
},
"response-required": {
"type": "boolean",
"description": "Whether a response to a command is required or if it may be omitted (fire and forget semantics)."
},
"requested-acks": {
"description": "Defining which acknowledgements (\"ack\") are requested for a command processed by Ditto.",
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"description": "A single acknowledgement label containing at least 3 characters.",
"pattern": "[a-zA-Z0-9-_:]{3,100}"
}
},
"timeout": {
"type": "string",
"description": "The timeout value to apply on the Ditto server side, e.g. applied when waiting for requested acknowledgements. Examples:\n * `42s`\n * `250ms`\n * `1m`\n * `60` (interpreted as seconds)",
"examples": [
"42s",
"250ms",
"1m",
"60"
]
},
"version": {
"type": "integer",
"description": "Determines the schema version of the payload.",
"minimum": 1,
"maximum": 2
},
"condition": {
"type": "string",
"description": "The `condition` header which should be valid RQL syntax."
}
},
"required": [ "correlation-id" ]
},
"path": {
"type": "string",
"description": "A Path that references a part of a Thing which is affected by this message.\nExamples:\n * `/features/location/properties/longitude` (a single sensor value)\n * `/` (the whole Thing)"
},
"fields": {
"type": "string",
"description": "The fields that should be included in the response.\nExample: `thingId,attributes(location)`"
},
"value": {
"type": ["object","string","number","array","boolean"],
"description": "The `value` field contains the actual payload e.g. a sensor value."
},
"extra": {
"type": "object",
"description": "The `extra` object contains the `extraFields` which have optionally been selected to additionally be included."
},
"revision": {
"type": "number",
"description": "For events this field contains the revision number of the event."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "For events this field contains the modification timestamp of the event."
}
},
"required": [
"topic",
"headers",
"path"
]
}