openapi/ditto-api-2.yml

openapi: 3.0.0
info:
  title: Eclipse Ditto HTTP API
  version: '2'
  description: |-
    JSON-based, REST-like API for Eclipse Ditto

    The Eclipse Ditto HTTP API uses response status codes (see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6))
    to indicate whether a specific request has been successfully completed, or not.

    However, the descriptions we provide additionally to the status code (e.g. in our API docs, or error codes like. "things.entitiy.tooLarge") might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.
servers:
  - url: 'https://ditto.eclipseprojects.io/api/2'
    description: online Ditto Sandbox
  - url: /api/2
    description: local Ditto
tags:
  - name: Things
    description: Manage every thing
  - name: Features
    description: Structure the features of your things
  - name: Policies
    description: Control access to your things
  - name: Things-Search
    description: Find every thing
  - name: Messages
    description: Talk with your things
security:
  - basicAuth: []
  - bearerAuth: []
paths:
  /things:
    get:
      summary: Retrieve multiple things with specified IDs
      description: |-
        Returns all things passed in by the required parameter `ids`, which you (the authorized subject) are allowed to read.

        Optionally, if you want to retrieve only some of the thing's fields, you can use the specific field selectors (see parameter `fields`) .

        Tip: If you don't know the thing IDs, start with the search resource.
      tags:
        - Things
      parameters:
        - name: ids
          in: query
          description: |-
            Contains a comma-separated list of `thingId`s to retrieve in one
            single request.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ThingFieldsQueryParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The successfully completed request contains as its result the first 200 for the user available Things.
            The Things are sorted in the same order as the Thing IDs were provided in the `ids` parameter.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Thing'
        '400':
          description: |-
            The request could not be completed. At least one of the defined
            query parameters was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '414':
          description: |-
            The request could not be completed due to an URI length exceeding 8k
            characters.
    post:
      summary: Create a new thing
      description: |-
        Creates a thing with a default `thingId` and a default `policyId`.

        The thing will be empty, i.e. no features, definition, attributes etc. by default.

        The default `thingId` consists of your default namespace and a UUID.

        The default `policyId` is identical with the default `thingId`, and allows the currently authorized subject all permissions.

        In case you need to create a thing with a specific ID, use a *PUT* request instead, as any `thingId` specified in the request body will be ignored.

        The field `_created` is filled automatically with the timestamp of the creation. The field is read-only and can
        be retrieved later by explicitly selecting it or used in search filters.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
        - $ref: '#/components/parameters/AllowPolicyLockoutParam'
      responses:
        '201':
          description: The thing was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created thing resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `thingId` must not be set in the request body
              * the JSON body of the thing to be created is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed.
            Possible reasons:
              * the caller would not have access to the thing after creating it with the given policy.
              * the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller had insufficient permissions to read the referenced thing.
              * the policy that should be copied does not exist.
              * the caller had insufficient permissions to read the policy that should be copied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThing'
            example:
              definition: 'com.acme:coffeebrewer:0.1.0'
              attributes:
                manufacturer: ACME demo corp.
                location: 'Berlin, main floor'
                serialno: '42'
                model: Speaking coffee machine
              features:
                coffee-brewer:
                  definition:
                    - 'com.acme:coffeebrewer:0.1.0'
                  properties:
                    brewed-coffees: 0
                water-tank:
                  properties:
                    configuration:
                      smartMode: true
                      brewingTemp: 87
                      tempToHold: 44
                      timeoutSeconds: 6000
                    status:
                      waterAmount: 731
                      temperature: 44
        description: 'JSON representation of the thing to be created. Use { } to create an empty thing with a default policy.'
  '/things/{thingId}':
    get:
      summary: Retrieve a specific thing
      description: |-
        Returns the thing identified by the `thingId` path parameter. The
        response includes details about the thing, including the `policyId`, attributes, definition and features.

        Optionally, you can use the field selectors (see parameter `fields`) to only get specific
        fields, which you are interested in.

        Example: Use the field selector `_policy` to retrieve the content of the policy.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/ThingFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The request successfully returned the specific thing.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
              * at least one of the defined query parameters is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update a thing with a specified ID
      description: |-
        Create or update the thing specified by the `thingId` path parameter and
        the optional JSON body.

        * If you set a new `thingId` in the path, a thing will be created.
        * If you set an existing `thingId` in the path, the thing will be updated.


        ### Create a new thing
        At the initial creation of a thing, only a valid `thingId` is required.
        However, you can create a full-fledged thing all at once.

        Example:
        To create a coffee maker thing, set the `thingId` in the path, e.g. to "com.acme.coffeemaker:BE-42"
        and the body part, like in the following snippet.

        ```
         {
           "definition": "com.acme:coffeebrewer:0.1.0",
           "attributes": {
             "manufacturer": "ACME demo corp.",
             "location": "Berlin, main floor",
             "serialno": "42",
             "model": "Speaking coffee machine"
           },
           "features": {
             "coffee-brewer": {
               "definition": [ "com.acme:coffeebrewer:0.1.0" ],
               "properties": {
                 "brewed-coffees": 0
               }
             },
             "water-tank": {
               "properties": {
                 "configuration": {
                   "smartMode": true,
                   "brewingTemp": 87,
                   "tempToHold": 44,
                   "timeoutSeconds": 6000
                 },
                 "status": {
                   "waterAmount": 731,
                   "temperature": 44
                 }
               }
             }
           }
          }
         ```
        As the example does not set a policy in the request body, but the thing concept requires one,
        the service will create a default policy. The default policy, has the exactly same id
        as the thing, and grants ALL permissions to the authorized subject.

        In case you need to associate the new thing to an already existing policy you can additionally
        set a policy e.g. "policyId": "com.acme.coffeemaker:policy-1" as the first element in the body part.
        Keep in mind, that you can also change the assignment to another policy anytime,
        with a request on the sub-resource "PUT /things/{thingId}/policyId"

        The field `_created` is filled automatically with the timestamp of the creation. The field is read-only and can
        be retrieved later by explicitly selecting it or used in search filters.

        ### Update an existing thing

        For updating an existing thing, the authorized subject needs **WRITE** permission on the thing's root resource.

        The ID of a thing cannot be changed after creation. Any `thingId`
        specified in the request body is therefore ignored.

        ### Partially update an existing thing

        When updating an existing thing, which already contains `attributes`, `definition` `policyId` or `features`,
        the existing fields must not explicitly be provided again.
        For this "PUT thing" request - and only for this top-level update on the thing -
        the top-level field to update is **merged** with the existing top-level fields of the thing.

        ### Example for a partial update

        Given, a thing already exists with this content:

        ```
        {
          "thingId": "namespace:thing-name",
          "policyId": "namespace:policy-name",
          "definition": "namespace:model:version",
          "attributes": {
            "foo": 1
          },
          "features": {...}
        }
        ```

        The thing's `attributes` may be modified without having to pass the `policyId` or
        the `features` in again.
        For updating the `attributes`, following request body would be sufficient :

        ```
        {
          "attributes": {
            "foo": 2,
            "bar": false
          }
        }
        ```

        The `policyId` and `features` of the thing will not be overwritten.
        The thing will be merged into:

        ```
        {
          "thingId": "namespace:thing-name",
          "policyId": "namespace:policy-name",
          "definition": "namespace:model:version",
          "attributes": {
            "foo": 2,
            "bar": false
          },
          "features": {...}
        }
        ```
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/PutMetadataParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The thing was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created thing resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '204':
          description: The thing was successfully modified.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
              * the JSON body of the thing to be created/modified is invalid
              * the JSON body of the thing to be created/modified contains a `thingId`
              which does not match the ID in the path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller would not have access to the thing after creating it with the given policy
              * the caller has insufficient permissions.
                For modifying an existing thing, an unrestricted `WRITE` permission on the thing's root resource is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller has insufficient permissions to read the referenced thing.
              * the policy that should be copied does not exist.
              * the caller has insufficient permissions to read the policy that should be copied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThing'
            example:
              definition: 'com.acme:coffeebrewer:0.1.0'
              attributes:
                manufacturer: ACME demo corp.
                location: 'Berlin, main floor'
                serialno: '42'
                model: Speaking coffee machine
              features:
                coffee-brewer:
                  definition:
                    - 'com.acme:coffeebrewer:0.1.0'
                  properties:
                    brewed-coffees: 0
                water-tank:
                  properties:
                    configuration:
                      smartMode: true
                      brewingTemp: 87
                      tempToHold: 44
                      timeoutSeconds: 6000
                    status:
                      waterAmount: 731
                      temperature: 44
        description: JSON representation of the thing to be modified.
    delete:
      summary: Delete a specific thing
      description: |-
        Deletes the thing identified by the `thingId` path parameter.

        This will not delete the policy, which is used for controlling access to this thing.

        You can delete the policy afterwards via DELETE `/policies/{policyId}` if you don't need it for other things.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The thing was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller had insufficient permissions.
                For deleting an existing thing, an unrestricted `WRITE` permission on the thing's root resource is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/definition':
    get:
      summary: Retrieve the definition of a specific thing
      description: Returns the definition of the thing identified by the `thingId` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The request successfully returned the definition of the specific thing.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:

            * the `thingId` does not conform to the namespaced entity ID notation
            (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying the definition of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update the definition of a specific thing
      description: |-
        * If the thing does not have a definition yet, this request will create it.
        * If the thing already has a definition you can assign it to a new one by setting the new definition in the request body.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The definition was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created definition resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '204':
          description: The definition was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `thingId` does not conform to the namespaced entity ID notation
                (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
              * the JSON was invalid
              * the request body was not a JSON object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying a definition of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Definition'
            example: '"example:test:definition"'
        description: |-
          JSON string of the definition to be modified. Consider that the
          value has to be a JSON string or `null`, examples:

            * an string: `{ ""value"}` -}. Currently the definition should follow the pattern: [_a-zA-Z0-9\-]:[_a-zA-Z0-9\-]:[_a-zA-Z0-9\-]
            * an empty string: `""`
    delete:
      summary: Delete the definition of a specific thing
      description: Deletes the definition of the thing identified by the `thingId`.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The definition was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` does not conform to the namespaced entity ID notation
            (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying a definition of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            its definition was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/policyId':
    get:
      summary: Retrieve the policy ID of a thing
      description: Returns the policy ID of the thing identified by the `thingId` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The request successfully returned the policy ID.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: The request could not be completed. The thing with the given ID was not found in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update the policy ID of a thing
      description: |-
        Create or update the policy ID of the thing identified by the `thingId`
        path parameter.

        ### Create
        If the thing does not have a `policyId` yet, it is
        considered to have been created via API version 1, where the access control list `acl`
        mechanism is used. In that case, this request will create the `policyId`.

        Note: You will need to create the policy content separately.

        ### Update
        If the thing already has a `policyId` you can assign it to an existing policy by setting
        the new `policyId` in the request body.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: 'The policy ID was successfully created. Note: You will need to create the policy content separately.'
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '204':
          description: The policy ID was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: '"your.namespace:your-policy-name"'
        description: |-
          The policy is used for controlling access to this thing. It is managed by
          resource `/policies/{policyId}`.

          The ID of a policy needs to conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
        required: true
  '/things/{thingId}/attributes':
    get:
      summary: List all attributes of a specific thing
      description: Returns all attributes of the thing identified by the `thingId` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/AttributesFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The attributes of the specific thing were successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attributes'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:

            * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: The request could not be completed. The thing with the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update all attributes of a specific thing at once
      description: |-
        Create or update the attributes of a thing identified by the `thingId`
        path parameter. The attributes will be overwritten - all at once - with the
        content (JSON) set in the request body.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The attributes were successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created attribute resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attributes'
        '204':
          description: The attributes were successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body of the attributes to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For modifying the attributes of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attributes'
            example:
              manufacturer:
                name: ACME demo corp.
                location: 'Berlin, main floor'
              coffeemaker:
                serialno: '42'
                model: Speaking coffee machine
        description: |-
          JSON object of all attributes to be modified at once. Consider that the
          value has to be a JSON object or `null`.

          Examples:
           * an empty object: `{}` - would just delete all old attributes
           * a simple object: `{ "key": "value"}` - We strongly recommend to use a restricted set of characters for the key (identifier), as the key might be needed for the (URL) path later.<br> Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
           * a nested object as shown in the example value
        required: true
    delete:
      summary: Delete all attributes of a specific thing at once
      description: |-
        Deletes all attributes of the thing identified by the `thingId` path
        parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The attributes were successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For deleting all attributes of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            its attributes were not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/attributes/{attributePath}':
    get:
      summary: Retrieve a specific attribute of a specific thing
      description: |-
        Returns a specific attribute of the thing identified by the `thingId`
        path parameter.

        The attribute (JSON) can be referenced hierarchically, by
        applying JSON Pointer notation (RFC-6901).

        Example:
        In order to retrieve the `name` field of an `manufacturer` attribute,
        the full path would be
        `/things/{thingId}/attributes/manufacturer/name`
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/AttributesPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The attribute was successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            the attribute at the specified path was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update a specific attribute of a specific thing
      description: |-
        Create or update a specific attribute of the thing identified by the
        `thingId` path parameter.

        * If you specify a new attribute path, this will be created
        * If you specify an existing attribute path, this will be updated

        The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).

        Example: In order to put the `name` field of an `manufacturer` attribute, the full path would be
        `/things/{thingId}/attributes/manufacturer/name`
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/AttributesPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The attribute was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created attribute resource
              schema:
                type: string
        '204':
          description: The attribute was successfully modified.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For modifying an attribute of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {}
        description: |-
          JSON representation of the value to be created/updated. This may be as
          well `null` or an empty object.

          Consider that the value has to be a JSON value, examples:

            * for a number, the JSON value is the number: `42`

            * for a string, the JSON value must be quoted: `"aString"`

            * for a boolean, the JSON value is the boolean: `true`

            * for an object, the JSON value is the object: `{ "key": "value"}` -} We strongly recommend to use a restricted set of characters for the key (identifier). Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*

            * for an list, the JSON value is the list: `[ 1,2,3 ]`
        required: true
    delete:
      summary: Delete a specific attribute of a specific thing
      description: |-
        Deletes a specific attribute of the thing identified by the `thingId`
        path parameter.

        The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).

        Example: In order to delete the `name` field of an `manufacturer` attribute, the full path would be
                `/things/{thingId}/attributes/manufacturer/name`
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/AttributesPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The attribute was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For deleting a single attribute of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            the attribute at the specified path was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features':
    get:
      summary: List all features of a specific thing
      description: |-
        Returns all features of the thing identified by the `thingId` path
        parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeaturesFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The list of features of the specific thing were successfully
            retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Features'
              example:
                featureId1:
                  definition:
                    - 'namespace:definition1:v1.0'
                  properties:
                    property1: value1
                featureId2:
                  definition:
                    - 'namespace:definition2:v1.0'
                  properties:
                    property2: value2
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined query parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found or the features have not been defined.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or modify all features of a specific thing at once
      description: |-
        Create or modify all features of a thing identified by the `thingId`
        path parameter.
        ### Create all features at once
        In case at the initial creation of your thing you have not specified any features, these can be created here.

        ### Update all features at once
        To update all features at once prepare the JSON body accordingly.

        Note: In contrast to the "PUT thing" request, a partial update is not supported here,
        but the content will be **overwritten**.
        If you need to update single features or their paths, please use the sub-resources instead.

        Example:

        ```
        {
             "coffee-brewer": {
               "definition": ["com.acme:coffeebrewer:0.1.0"],
               "properties": {
                 "brewed-coffees": 0
               }
             },
             "water-tank": {
               "properties": {
                 "configuration": {
                   "smartMode": true,
                   "brewingTemp": 87,
                   "tempToHold": 44,
                   "timeoutSeconds": 6000
                 },
                 "status": {
                   "waterAmount": 731,
                   "temperature": 44
                 }
               }
             }
        }
        ```
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The features were successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created features resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Features'
              example: {}
        '204':
          description: The features were successfully modified.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body of the feature to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying all features of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Features'
            example:
              coffee-brewer:
                properties:
                  definition:
                    - 'com.acme:coffeebrewer:0.1.0'
                  brewed-coffees: 0
              water-tank:
                properties:
                  configuration:
                    smartMode: true
                    brewingTemp: 87
                    tempToHold: 44
                    timeoutSeconds: 6000
                  status:
                    waterAmount: 731
                    temperature: 44
        description: |-
          JSON object of all features to be modified at once. Consider that the value has to be a JSON object or null.

          Examples:
          * an empty object: {} - would just delete all old features
          * an empty feature: { "featureId": {} } - We strongly recommend to use a restricted set of characters
            for the `featureId`, as it might be needed for the (URL) path later.

            Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9-]*

          * a nested object with multiple features as shown in the example value field
        required: true
    delete:
      summary: Delete all features of a specific thing
      description: |-
        Deletes all features of the thing identified by the `thingId` path
        parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The features were successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For deleting all features of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found or the features have not been defined.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}':
    get:
      summary: Retrieve a specific feature of a specific thing
      description: |-
        Returns a specific feature identified by the `featureId` path parameter
        of the thing identified by the `thingId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/FeatureFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The feature was successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined query parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            the feature with the specified `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or modify a specific feature of a specific thing
      description: |-
        Create or modify a specific feature identified by the `featureId` path
        parameter of the thing identified by the `thingId` path parameter.

        ### Create feature
        If the feature ID is new, the feature and all content from the JSON body will be created

        ### Update feature
        If the feature ID is used already in this thing, the feature will be overwrittern
        with the content from the JSON body.

        Example: Set the `featureId` to **coffee-brewer** and all properties in the body part.

        ```
        {
          "definition": ["com.acme:coffeebrewer:0.1.0"],
          "properties": {
            "brewed-coffees": 42
          }
        }
        ```
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The feature was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created feature resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '204':
          description: The feature was successfully modified.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body of the feature to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying a single feature of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID was
            not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feature'
            example:
              definition:
                - 'com.acme:coffeemaker:0.1.0'
                - 'com.acme:coffeemaker:1.1.0'
              properties:
                connected: true
                brewed-coffees: 0
        description: |-
          JSON representation of the feature to be created/modified.
          Consider that the value has to be a JSON object or null.

          Examples:
          * an empty object: {} - would just create the featureID but would delete all content of the feature
          * a nested object with multiple model definitions and multiple properties as shown in the example value field
        required: true
    delete:
      summary: Delete a specific feature of a specific thing
      description: |-
        Deletes a specific feature identified by the `featureId` path parameter
        of the thing identified by the `thingId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The feature was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For deleting a single feature of an existing thing, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing with the given ID or
            the feature at the specified path was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}/definition':
    get:
      summary: List the definition of a feature
      description: |-
        Returns the complete definition field of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The definition was successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureDefinition'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined query parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no
            definition or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update the definition of a feature
      description: |-
        Create or update the complete definition of a feature identified by the `thingId`
        and `featureId` path parameter.

        The definition field will be overwritten with the JSON array set in the request body
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The definition was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created definition resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureDefinition'
        '204':
          description: The definition was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                For modifying the definition of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing or the feature with
            the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureDefinition'
            example:
              - 'com.acme:coffeebrewer:0.1.0'
              - 'com.acme:coffeebrewer:1.0.0'
        description: |-
          JSON array of the complete definition to be updated. Consider that the
          value has to be a JSON array or `null`.

          The content of the JSON array
          are strings in the format `"namespace:name:version"` which is
          enforced.
        required: true
    delete:
      summary: Delete the definition of a feature
      description: |-
        Deletes the complete definition of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The definition was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For deleting the definition of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no
            definition or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}/properties':
    get:
      summary: List all properties of a feature
      description: |-
        Returns all properties of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertiesFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The properties were successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureProperties'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined query parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no
            properties or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update all properties of a feature at once
      description: |-
        Create or update the properties of a feature identified by the `thingId`
        and `featureId` path parameter.

        The properties will be overwritten with the JSON content from the request body.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The properties were successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureProperties'
        '204':
          description: The properties were successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body of the feature properties to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying the properties of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing or the feature with
            the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureProperties'
            example:
              configuration:
                smartMode: true
                brewingTemp: 87
                tempToHold: 44
                timeoutSeconds: 6000
              status:
                waterAmount: 731
                temperature: 44
        description: |-
          JSON object of all properties to be updated at once.

          Consider that the value has to be a JSON object or `null`. We strongly recommend to use
          a restricted set of characters for the key (identifier).

          Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
        required: true
    delete:
      summary: Delete all properties of a feature
      description: |-
        Deletes all properties of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The properties were successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For deleting the properties of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no
            properties or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}/properties/{propertyPath}':
    get:
      summary: Retrieve a specific property of a feature
      description: |-
        Returns the a specific property path of the feature identified by the `thingId` and
        `featureId` path parameter.

        The property (JSON) can be referenced
        hierarchically, by applying JSON Pointer notation (RFC-6901)

        ### Example
        To retrieve the value of the `brewingTemp` in the `water-tank` of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The property was successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified property or the
            thing with the specified `thingId` or the feature with `featureId`
            was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update a specific property of a feature
      description: |-
        Create or update a specific property of a feature identified by the
        `thingId` and `featureId` path parameter.

        The property will be created
        if it doesn't exist or else updated.

        The property (JSON) can be
        referenced hierarchically, by applying JSON Pointer notation (RFC-6901),

        ### Example
        To set the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The property was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '204':
          description: The property was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For creating/updating a property of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing or the feature with
            the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1attributes~1%7BattributePath%7D/put/requestBody'
    delete:
      summary: Delete a specific property of a feature
      description: |-
        Deletes a specific property of the feature identified by the `thingId`
        and `featureId` path parameter.

        The property (JSON) can be referenced
        hierarchically, by applying JSON Pointer notation (RFC-6901)

        ### Example
        To delete the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The property was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified property or the
            thing with the specified `thingId` or the feature with `featureId`
            was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}/desiredProperties':
    get:
      summary: List all desired properties of a feature
      description: |-
        Returns all desired properties of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/DesiredPropertiesFieldsQueryParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The desired properties were successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureProperties'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined query parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no desired
            properties or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update all desired properties of a feature at once
      description: |-
        Create or update the desired properties of a feature identified by the `thingId`
        and `featureId` path parameter.

        The desired properties will be overwritten with the JSON content from the request body.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The desired properties were successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureProperties'
        '204':
          description: The desired properties were successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body of the desired feature roperties to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For modifying the desired properties of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing or the feature with
            the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureProperties'
            example:
              configuration:
                smartMode: true
                brewingTemp: 87
                tempToHold: 44
                timeoutSeconds: 6000
              status:
                waterAmount: 731
                temperature: 44
        description: |-
          JSON object of all desried properties to be updated at once.

          Consider that the value has to be a JSON object or `null`. We strongly recommend to use
          a restricted set of characters for the key (identifier).

          Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
        required: true
    delete:
      summary: Delete all desired properties of a feature
      description: |-
        Deletes all desired properties of the feature identified by the `thingId` and
        `featureId` path parameter.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The desired properties were successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For deleting the desired properties of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified feature has no desired
            properties or the thing with the specified `thingId` or the feature
            with `featureId` was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/features/{featureId}/desiredProperties/{propertyPath}':
    get:
      summary: Retrieve a specific desired property of a feature
      description: |-
        Returns the a specific desired property path of the feature identified by the `thingId` and
        `featureId` path parameter.

        The desired property (JSON) can be referenced
        hierarchically, by applying JSON Pointer notation (RFC-6901)

        ### Example
        To retrieve the value of the `brewingTemp` in the `water-tank` of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The desired property was successfully retrieved.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified desired property or the
            thing with the specified `thingId` or the feature with `featureId`
            was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update a specific desired property of a feature
      description: |-
        Create or update a specific desired property of a feature identified by the
        `thingId` and `featureId` path parameter.

        The desired property will be created
        if it doesn't exist or else updated.

        The desired property (JSON) can be
        referenced hierarchically, by applying JSON Pointer notation (RFC-6901),

        ### Example
        To set the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The desired property was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '204':
          description: The desired property was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * the JSON body is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                For creating/updating a desired property of an existing feature, `WRITE` permission is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The thing or the feature with
            the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1attributes~1%7BattributePath%7D/put/requestBody'
    delete:
      summary: Delete a specific desired property of a feature
      description: |-
        Deletes a specific desired property of the feature identified by the `thingId`
        and `featureId` path parameter.

        The desired property (JSON) can be referenced
        hierarchically, by applying JSON Pointer notation (RFC-6901)

        ### Example
        To delete the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:

        `/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/PropertyPathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/RequestedAcksParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The desired property was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The specified desired property or the
            thing with the specified `thingId` or the feature with `featureId`
            was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/things/{thingId}/inbox/claim':
    post:
      summary: Initiates claiming a specific thing in order to gain access
      description: |-
        ### Why
        A claiming process may enable an end-user to claim things and proof ownership thereof.
        Such a process is initially triggered via a claim message.
        This message can be sent to the things service with the HTTP API or the things-client.

        ### How
        At this resource you can send a "claim" message to the thing identified
        by the `thingId` path parameter in order to gain access to it. The "claim" message is forwarded
        together with the request body and `Content-Type` header to client(s)
        which registered for Claim messages of the specific thing.

        The decision whether to grant access (by setting permissions) is
        completely up to the client(s) which handle the "claim" message.

        The HTTP request blocks until all acknowledgement requests are fulfilled.
        By default, it blocks until a response to the issued "claim" message is
        available or until the `timeout` is expired. If many clients respond to
        the issued message, the first response will complete the HTTP request.

        Note that the client chooses which HTTP status code it wants to return. Ditto
        will forward the status code to you. (Also note that '204 - No Content' status code
        will never return a body, even if the client responded with a body).

        ### Who
        No special permission is required to issue a claim message.

        ### Example
        See [Claiming](https://www.eclipse.org/ditto/protocol-specification-things-messages.html#sending-and-handling-claim-messages) concept in detail and example in GitHub.
        However, in that scenario, the policy should grant you READ and WRITE permission on
        the "message:/" resource in order to be able to send the message and read the response.
        Further, the things-client which handles the "claim" message, needs permission to change the policy itself
        (i.e. READ and WRITE permission on the "policy:/" resource).
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/MessageClaimTimeoutParam'
        - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
      responses:
        '200':
          description: |-
            The Claim message was processed successfully and the response body
            contains the custom response. The response body may contain
            arbitrary data chosen by the recipient. The response code defaults
            to `200` but may be chosen by the recipient too.
        '204':
          description: |-
            The Claim message was processed successfully and no custom response
            body was set. The response code defaults to `204` but may be chosen
            by the recipient.
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined path parameters is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '408':
          description: The request could not be completed due to timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/MessageTooLarge'
        '429':
          description: |-
            The user has sent too many requests in a given amount of time ("rate
            limiting").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '503':
          $ref: '#/components/responses/MessageTimeout'
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: ''
          application/octet-stream:
            schema:
              type: string
              example: ''
          text/plain:
            schema:
              type: string
              example: ''
        description: |-
          Payload of the message with max size of 250 kB. It can be any HTTP
          supported content, including binary content.
  '/things/{thingId}/inbox/messages/{messageSubject}':
    post:
      summary: Send a message TO a specific thing
      description: |-
        ### Why
        A message can be sent to a thing or one of its features in order to invoke an operation on the device.

        ### How
        Send a message with a `messageSubject` **to** the thing
        identified by the `thingId` path parameter. The request body contains
        the message payload and the `Content-Type` header defines its type.

        The HTTP request blocks until all acknowledgement requests are fulfilled.
        By default, it blocks until a response to the message is available
        or until the `timeout` is expired. If many clients respond to
        the issued message, the first response will complete the HTTP request.

        In order to handle the message in a fire and forget manner, add
        a query-parameter `timeout=0` to the request.

        Note that the client chooses which HTTP status code it wants to return. Ditto
        will forward the status code to you. (Also note that '204 - No Content' status code
        will never return a body, even if the client responded with a body).

        ### Who
        You will need `WRITE` permission on the root "message:/" resource, or at least
        the resource `message:/inbox/messages/messageSubject`. The receiving device needs `READ` permission on the resource.
        Such permission is managed within the policy which controls the access on the thing.

        ### Example
        Given you have a "coffemaker" thing as shown in the examples for the `things` resources.
        The `messageSubject` understood by such a device would be "makeCoffee".

        Further, as in our example the "brewed-coffees" counter would increase as a response, you would need `WRITE`
        permission for the things resource, at least at the respective path

        `/things/{thingId}/features/coffee-brewer/properties/brewed-coffees`
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/MessageSubjectPathParam'
        - $ref: '#/components/parameters/MessageTimeoutParam'
        - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
      responses:
        '202':
          description: The message was sent but not necessarily received by the thing (fire and forget).
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined path parameters is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                You need `WRITE` permission on the resource `message:/inbox/messages/{messageSubject}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller has insufficient permissions to interact with the messages of referenced thing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '408':
          description: The request could not be completed due to timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/MessageTooLarge'
        '503':
          $ref: '#/components/responses/MessageTimeout'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
  '/things/{thingId}/outbox/messages/{messageSubject}':
    post:
      summary: Send a message FROM a specific thing
      description: |-
        Send a message with the subject `messageSubject` **from** the thing
        identified by the `thingId` path parameter. The request body contains
        the message payload and the `Content-Type` header defines its type.

        The HTTP request blocks until all acknowledgement requests are fulfilled.
        By default, it blocks until a response to the message is available
        or until the `timeout` is expired. If many clients respond to
        the issued message, the first response will complete the HTTP request.

        In order to handle the message in a fire and forget manner, add
        a query-parameter `timeout=0` to the request.

        Note that the client chooses which HTTP status code it wants to return. Ditto
        will forward the status code to you. (Also note that '204 - No Content' status code
        will never return a body, even if the client responded with a body).

        ### Who
        You will need `WRITE` permission on the root "message:/" resource, or at least
        the resource `message:/outbox/messages/messageSubject`.
        Such permission is managed  within the policy which controls the access on the thing.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/MessageSubjectPathParam'
        - $ref: '#/components/parameters/MessageTimeoutParam'
        - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
      responses:
        '202':
          description: The message was sent (fire and forget).
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined path parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                You need `WRITE` permission on the resource `message:/outbox/messages/{messageSubject}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller has insufficient permissions to interact with the messages of referenced thing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '408':
          description: The request could not be completed due to timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/MessageTooLarge'
        '503':
          $ref: '#/components/responses/MessageTimeout'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
  '/things/{thingId}/features/{featureId}/inbox/messages/{messageSubject}':
    post:
      summary: Send a message TO a specific feature of a specific thing
      description: |-
        Send a message with the subject `messageSubject` **to** the feature
        specified by the `featureId` and `thingId` path parameter. The request
        body contains the message payload and the `Content-Type` header defines
        its type.

        The HTTP request blocks until all acknowledgement requests are fulfilled.
        By default, it blocks until a response to the message is available
        or until the `timeout` is expired. If many clients respond to
        the issued message, the first response will complete the HTTP request.

        In order to handle the message in a fire and forget manner, add
        a query-parameter `timeout=0` to the request.

        Note that the client chooses which HTTP status code it wants to return. Ditto
        will forward the status code to you. (Also note that '204 - No Content' status code
        will never return a body, even if the client responded with a body).

        ### Who
        You will need `WRITE` permission on the root "message:/" resource, or at least
        the resource `message:/features/featureId/inbox/messages/messageSubject`. The receiving device needs `READ` permission on the resource.
        Such permission is managed  within the policy which controls the access on the thing.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/MessageSubjectPathParam'
        - $ref: '#/components/parameters/MessageTimeoutParam'
        - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
      responses:
        '202':
          description: |-
            The message was sent but not necessarily received by the feature
            (fire and forget).
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined path parameters is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

             * the caller has insufficient permissions.
               You need `WRITE` permission on the resource `message:/features/{featureId}/inbox/messages/{messageSubject}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller has insufficient permissions to interact with the messages of referenced thing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '408':
          description: The request could not be completed due to timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/MessageTooLarge'
        '503':
          $ref: '#/components/responses/MessageTimeout'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
  '/things/{thingId}/features/{featureId}/outbox/messages/{messageSubject}':
    post:
      summary: Send a message FROM a specific feature of a specific thing
      description: |-
        Send a message with the subject `messageSubject` **from** the feature
        specified by the `featureId` and `thingId` path parameter. The request
        body contains the message payload and the `Content-Type` header defines
        its type.

        The HTTP request blocks until all acknowledgement requests are fulfilled.
        By default, it blocks until a response to the message is available
        or until the `timeout` is expired. If many clients respond to
        the issued message, the first response will complete the HTTP request.

        In order to handle the message in a fire and forget manner, add
        a query-parameter `timeout=0` to the request.

        Note that the client chooses which HTTP status code it wants to return. Ditto
        will forward the status code to you. (Also note that '204 - No Content' status code
        will never return a body, even if the client responded with a body).

        ### Who
        You will need `WRITE` permission on the root "message:/" resource, or at least
        the resource `message:/features/featureId/outbox/messages/messageSubject`.
        Such permission is managed  within the policy which controls the access on the thing.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/ThingIdPathParam'
        - $ref: '#/components/parameters/FeatureIdPathPathParam'
        - $ref: '#/components/parameters/MessageSubjectPathParam'
        - $ref: '#/components/parameters/MessageTimeoutParam'
        - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
      responses:
        '202':
          description: The message was sent (fire and forget).
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
              * at least one of the defined path parameters is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                You need `WRITE` permission on the resource `message:/features/{featureId}/outbox/messages/{messageSubject}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. Possible reasons:
              * the referenced thing does not exist.
              * the caller has insufficient permissions to interact with the messages of referenced thing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '408':
          description: The request could not be completed due to timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/MessageTooLarge'
        '503':
          $ref: '#/components/responses/MessageTimeout'
      requestBody:
        $ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
  '/policies/{policyId}':
    get:
      summary: Retrieve a specific policy
      description: |-
        Returns the complete policy identified by the `policyId` path parameter. The
        response contains the policy as JSON object.

        Tip: If you don't know the policy ID, request it via GET ​/things​/{thingId}.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The request successfully returned completed and returned is the
            policy.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID was
            not found in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    put:
      summary: Create or update a policy with a specified ID
      description: |-
        Create or update the policy specified by the policyId path parameter.
        * If you set a new policyId in the path, a new policy will be created.
        * If you set an existing policyId in the path, the policy will be updated.

        ### Create a new policy
        At the initial creation of a policy, at least one valid entry is required. However, you can create a full-fledged policy all at once.

        By default the authorized subject needs WRITE permission on the root resource of the created policy. You can
        however omit this check by setting the parameter `allow-policy-lockout` to `true`.

        Example: To create a policy for multiple coffee maker things,
        which gives **yourself** all permissions on all resources, set the policyId in the path,
        e.g. to "com.acme.coffeemaker:policy-01" and the body part, like in the following snippet.

        ```
        {
          "entries": {
            "DEFAULT": {
              "subjects": {
                "{{ request:subjectId }}": {
                  "type": "the creator"
                }
              },
              "resources": {
                "policy:/": {
                  "grant": [
                    "READ",
                    "WRITE"
                  ],
                  "revoke": []
                },
                "thing:/": {
                  "grant": [
                    "READ",
                    "WRITE"
                  ],
                  "revoke": []
                },
                "message:/": {
                  "grant": [
                    "READ",
                    "WRITE"
                  ],
                  "revoke": []
                }
              }
            }
          }
        }
        ```

        ### Update an existing policy
        For updating an existing policy, the authorized subject needs WRITE permission on the policy's root resource.

        The ID of a policy cannot be changed after creation. Any `policyId` specified in the request body is therefore ignored.

        ### Partially update an existing policy
        Partial updates are not supported.

        If you need to create or update a specific label, resource, or subject, please use the respective sub-resources.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
        - $ref: '#/components/parameters/AllowPolicyLockoutParam'
      responses:
        '201':
          description: The policy was successfully created.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
            Location:
              description: The location of the created policy resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '204':
          description: The policy was successfully updated.
          headers:
            ETag:
              description: |-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
              schema:
                type: string
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
              * the JSON body of the policy to be created/modified is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:

              * the caller has insufficient permissions.
                You need `WRITE` permission on the root `policy:/` resource,
                without any revoke in a deeper path of the policy resource.
                (You can omit this check by setting the `allow-policy-lockout` parameter.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID was
            not found in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/EntityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
            example:
              entries:
                DEFAULT:
                  subjects:
                    '{{ request:subjectId }}':
                      type: the creator
                  resources:
                    'policy:/':
                      grant:
                        - READ
                        - WRITE
                      revoke: []
                    'thing:/':
                      grant:
                        - READ
                        - WRITE
                      revoke: []
                    'message:/':
                      grant:
                        - READ
                        - WRITE
                      revoke: []
        description: |-
          JSON representation of the policy.
          Use the placeholder `{{ request:subjectId }}` in order to let the
          backend insert the authenticated subjectId of the HTTP request.
        required: true
    delete:
      summary: Delete a specific policy
      description: |-
        Deletes the policy identified by the `policyId` path parameter. Deleting
        a policy does not implicitly delete other entities (e.g. things) which
        use this policy.

        Note: Delete the respective things **before** deleting the
        policy, otherwise nobody has permission to read, update, or delete the things.
        If you accidentally run into such a scenario, re-create the policy via
        PUT `/policies/{policyId}`.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParam'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The policy was successfully deleted.
        '400':
          description: |-
            The request could not be completed. Possible reasons:

              * the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Possible reasons:
              * the caller has insufficient permissions.
                You need `WRITE` permission on the root `policy:/` resource,
                without any revoke in a deeper path of the policy resource.having any revoke.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID was
            not found in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  '/policies/{policyId}/entries':