[#1228] documentation review:

* renamed haeder "on-live-channel-timeout" to "live-channel-timeout-strategy"
* added more docs on "time:" placeholder to be usable in conditions
* fixed some fingings in OpenAPI

Signed-off-by: Thomas Jaeckle <thomas.jaeckle@bosch.io>

documentation/src/main/resources/openapi/sources/api-2-index.yml

@@ -168,6 +168,8 @@ components:
       $ref: "./responses/notModified.yml"
     PreconditionFailed:
       $ref: "./responses/preconditionFailed.yml"
+    DependencyFailed:
+      $ref: "./responses/dependencyFailed.yml"
 
   parameters:
     AllowPolicyLockoutParam:
@@ -182,8 +184,8 @@ components:
       $ref: "./parameters/conditionParam.yml"
     LiveChannelConditionParam:
       $ref: "./parameters/liveChannelConditionParam.yml"
-    OnLiveChannelTimeoutParam:
-      $ref: "./parameters/onLiveChannelTimeoutParam.yml"
+    LiveChannelTimeoutStrategyParam:
+      $ref: "./parameters/liveChannelTimeoutStrategyParam.yml"
     DesiredPropertiesFieldsQueryParam:
       $ref: "./parameters/desiredPropertiesFieldsQueryParam.yml"
     FeatureFieldsQueryParam:

documentation/src/main/resources/openapi/sources/parameters/channelParam.yml

@@ -12,7 +12,7 @@ name: channel
 in: query
 description: |-
   Defines to which channel to route the command: `twin` (digital twin) or `live` (the device).
-  * If setting the channel parameter is omitted, the `twin` channel is set by default and the command is routed to the digital representation of a thing in Bosch IoT Things backend.
+  * If setting the channel parameter is omitted, the `twin` channel is set by default and the command is routed to the persisted representation of a thing in Eclipse Ditto.
   * When using the `live` channel, the command/message is sent towards the device.
 required: false
 schema:

documentation/src/main/resources/openapi/sources/parameters/channelParamPutDescription.yml

@@ -2,7 +2,7 @@ name: channel
 in: query
 description: |-
   Defines to which channel to route the command: `twin` (digital twin) or `live` (the device).
-  * If setting the channel parameter is omitted, the `twin` channel is set by default and the command is routed to the digital representation of a thing in Bosch IoT Things backend.
+  * If setting the channel parameter is omitted, the `twin` channel is set by default and the command is routed to the persisted representation of a thing in Eclipse Ditto.
   * When using the `live` channel, the command/message is sent towards the device.
 
   The option `live` is not available when a new thing should be created, only for updating an

documentation/src/main/resources/openapi/sources/parameters/conditionParam.yml

@@ -12,25 +12,29 @@ name: condition
 in: query
 description: >-
   Defines that the request should only be applied to a thing if the given condition is met.
-  The condition can be specified using RQL syntax, e.g. if the temperature is not 23.9 update it to 23.9.
+  The condition can be specified using RQL syntax. 
 
-   ```PUT /api/2/things/org.eclipse.ditto:my-fancy-car-1/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)```
+  #### Examples
+  
+  E.g. if the temperature is not 23.9 update it to 23.9:
 
-   `body: 23.9`
+  * ```PUT /api/2/things/{thingId}/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)```
+  
+     `body: 23.9`
+  
+  Further example conditions:
 
-  Further condition examples:
+  * ```?condition=eq(features/temperature/properties/unit,"Celsius")```
 
-  * ```eq(features/temperature/properties/unit,"Celsius")```
+  * ```?condition=ge(features/temperature/properties/lastModified,"2021-08-22T19:45:00Z")```
+  
+  * ```?condition=gt(_modified,"2021-08-05T12:17:00Z")```
 
-  * ```ge(features/temperature/properties/lastModified,"2021-08-22T19:45:00")```
+  * ```?condition=exists(features/temperature/properties/value)```
 
-  * ```gt(_modified,"2021-08-05T12:17")```
+  * ```?condition=and(gt(features/temperature/properties/value,18.5),lt(features/temperature/properties/value,25.2))```
 
-  * ```exists(features/temperature/properties/value)```
-
-  * ```and(gt(features/temperature/properties/value,18.5),lt(features/temperature/properties/value,25.2))```
-
-  * ```or(gt(features/temperature/properties/value,18.5),not(exists(features/temperature/properties/value))```
+  * ```?condition=or(gt(features/temperature/properties/value,18.5),not(exists(features/temperature/properties/value))```
 
 required: false
 schema:

documentation/src/main/resources/openapi/sources/parameters/liveChannelConditionParam.yml

@@ -11,8 +11,14 @@
 name: live-channel-condition
 in: query
 description: >-
-  Defines that the request should fetch thing data via live channel if the given condition is met.
+  Defines that the request should fetch thing data via `live` channel if the given condition is met.
   The condition can be specified using RQL syntax.
+  
+  #### Examples
+
+    * ```?live-channel-condition=lt(_modified,"2021-12-24T12:23:42Z")```
+  
+    * ```?live-channel-condition=ge(features/ConnectionStatus/properties/status/readyUntil,time:now)```
 
 required: false
 schema:

documentation/src/main/resources/openapi/sources/parameters/onLiveChannelTimeoutParam.yml → documentation/src/main/resources/openapi/sources/parameters/liveChannelTimeoutStrategyParam.yml

@@ -8,10 +8,11 @@
 # http://www.eclipse.org/legal/epl-2.0
 #
 # SPDX-License-Identifier: EPL-2.0
-name: on-live-channel-timeout
+name: live-channel-timeout-strategy
 in: query
 description: >-
-  Defines a strategy how to handle timeouts of a live response to a request sent with a matching live-channel-condition.
+  Defines a strategy how to handle timeouts of a live response to a request sent via `channel=true` or with a matching 
+  live-channel-condition.
 
 required: false
 schema:

documentation/src/main/resources/openapi/sources/paths/features/definition.yml

@@ -23,7 +23,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The definition was successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/features/desiredProperties.yml

@@ -24,7 +24,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The desired properties were successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/features/desiredProperty.yml

@@ -31,7 +31,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The desired property was successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/features/feature.yml

@@ -25,7 +25,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The feature was successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/features/index.yml

@@ -25,7 +25,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: |-

documentation/src/main/resources/openapi/sources/paths/features/properties.yml

@@ -24,7 +24,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The properties were successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/features/property.yml

@@ -30,7 +30,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The property was successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/things/attribute.yml

@@ -30,7 +30,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The attribute was successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/things/attributes.yml

@@ -23,7 +23,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The attributes of the specific thing were successfully retrieved.

documentation/src/main/resources/openapi/sources/paths/things/definition.yml

@@ -22,7 +22,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The request successfully returned the definition of the specific thing.

documentation/src/main/resources/openapi/sources/paths/things/policyId.yml

@@ -22,7 +22,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The request successfully returned the policy ID.

documentation/src/main/resources/openapi/sources/paths/things/thing.yml

@@ -30,7 +30,7 @@ get:
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParamPutDescription.yml'
     - $ref: '../../parameters/liveChannelConditionParam.yml'
-    - $ref: '../../parameters/onLiveChannelTimeoutParam.yml'
+    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
   responses:
     '200':
       description: The request successfully returned the specific thing.

documentation/src/main/resources/openapi/sources/schemas/acknowledgements/acknowledgements.yml

@@ -11,8 +11,6 @@
 properties:
   acknowledgementLabel1:
     $ref: 'acknowledgement.yml'
-  acknowledgementLabelN:
-    $ref: 'acknowledgement.yml'
 example:
   acknowledgementLabel1:
     status: 200

documentation/src/main/resources/pages/ditto/basic-conditional-requests.md

@@ -71,13 +71,13 @@ and Ditto Java Client which is based on the WebSocket protocol.
 Using the HTTP API it is possible to specify the condition via query parameter
 
 ```
-curl -X PUT -H 'Content-Type: application/json' /api/2/things/org.eclipse.ditto:fancy-thing/features/temperature/properties/value?condition=gt(features/temperature/properties/lastModified,2021-08-10T15:10:02.592Z) -d 19.26
+curl -X PUT -H 'Content-Type: application/json' /api/2/things/org.eclipse.ditto:fancy-thing/features/temperature/properties/value?condition=gt(features/temperature/properties/lastModified,'2021-08-10T15:10:02.592Z') -d 19.26
 ```
 
 or via HTTP header
 
 ```
-curl -X PUT -H 'Content-Type: application/json' -H 'condition: gt(features/temperature/properties/lastModified,2021-08-10T15:10:02.592Z)' /api/2/things/org.eclipse.ditto:fancy-thing/features/temperature/properties/value -d 19.26
+curl -X PUT -H 'Content-Type: application/json' -H 'condition: gt(features/temperature/properties/lastModified,"2021-08-10T15:10:02.592Z")' /api/2/things/org.eclipse.ditto:fancy-thing/features/temperature/properties/value -d 19.26
 ```
 
 ### Ditto protocol
@@ -118,19 +118,48 @@ client.twin().forFeature(ThingId.of("org.eclipse.ditto:fancy-thing"), "temperatu
 
 ## Live channel condition
 
-Ditto also supports retrieving thing data with an automatic approach for switching between [twin](protocol-twinlive.html#twin) and [live](protocol-twinlive.html#live) channel.
+Ditto also supports retrieving thing data with an automatic approach for switching between 
+[twin](protocol-twinlive.html#twin) and [live](protocol-twinlive.html#live) channel.
 
-Conditions are defined with RQL as described [before](#defining-conditions). If a condition is matched, the Thing data is retrieved from the device itself.
+Conditions are defined with RQL as described [before](#defining-conditions). 
+If a condition is matched, the Thing data is retrieved from the device itself.
 
+Example: retrieve data from the device itself if a certain attribute is configured at the twin:
 ```
-GET .../things/{thingId}?live-channel-condition=eq(attributes/useLiveChannel,'true')
+GET .../things/{thingId}?live-channel-condition=eq(attributes/useLiveChannel,true)
 ```
 
-Additionally, a strategy to handle timeouts for retrieving live thing data can be specified with the http header `on-live-channel-timeout`.
-The request can either `fail` with a status code 408 or `use-twin` as a fallback, in that case the Thing date would be returned from Ditto directly.
+Example: retrieve data from the device itself if the last modification timestamp is behind a specified timestamp:
+```
+GET .../things/{thingId}?live-channel-condition=lt(_modified,"2021-12-24T12:23:42Z")
+```
+
+### Live channel condition headers
+
+Additionally, a strategy to handle timeouts for retrieving live thing data can be specified with the header
+`live-channel-timeout-strategy`.  
+The header value holds a **strategy** what to do in case a timeout (can also be specified as header) was encountered.
+
+* If the value cannot be retrieved live from the device itself during the specified timeout, the request will
+  `fail` (which is the default strategy if not specified otherwise) with a status code 408.
+* Alternatively, if `use-twin` was defined as the `live-channel-timeout-strategy` strategy, the request will fall back 
+  to the persisted twin and return the latest value stored in the digital twin.
+
+
+### Live channel condition response headers
+
+The response includes two additional headers to indicate which channel was used to retrieve the thing data:
+
+* `live-channel-condition-matched` – value could be `true` or `false` and states whether the passed live-channel-condition was a match or not
+* `channel` – value could be `twin` or `live` and defines which channel was the origin of the returned data.
+
+In line with the procedure described above on how to retrieve live data directly from a device, a new type of 
+pre-configured payload mapping, namely [UpdateTwinWithLiveResponse](connectivity-mapping.html#updatetwinwithliveresponse-mapper)
+was introduced.
+
+Upon activation, the digital twin stored in Eclipse Ditto will implicitly be updated with the latest data from the 
+_live response_ sent by the device.
 
-The response includes two additional http headers `live-channel-condition-matched` and `channel` to indicate which channel was used to retrieve the thing data.
-Also, it can be used to update the twin state via a specific [payload mapper](connectivity-mapping.html#updatetwinwithliveresponse-mapper).
 
 ## Further reading on RQL expressions
 

documentation/src/main/resources/pages/ditto/basic-rql.md

@@ -66,9 +66,9 @@ When using an RQL expression in order to e.g. filter for certain
 field in JSON representation inside the Thing.
 
 Currently supported placeholders for RQL expressions are:
-* 
 * `topic:<placeholder-name>`
 * `resource:<placeholder-name>`
+* `time:<placeholder-name>`
 
 The [placeholder](basic-placeholders.html#scope-rql-expressions-when-filtering-for-ditto-protocol-messages) 
 documentation describes which placeholder names are supported.