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
  - name: CloudEvents
    description: Process CloudEvents in Ditto
security:
  - Google:
      - openid
  - NginxBasic: []
  - Bearer: []
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:
        $ref: '#/components/requestBodies/Definition'
    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:
        $ref: '#/components/requestBodies/Attributes'
    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:
        $ref: '#/components/requestBodies/Value'
    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: '#/components/requestBodies/Value'
    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: '#/components/requestBodies/Value'
    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:
        $ref: '#/components/requestBodies/Payload'
  '/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: '#/components/requestBodies/Payload'
  '/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: '#/components/requestBodies/Payload'
  '/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: '#/components/requestBodies/Payload'
  '/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: '#/components/requestBodies/Payload'
  '/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 of a thing, 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/NewPolicy'
        '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/NewPolicy'
            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}/actions/activateTokenIntegration':
    post:
      summary: Activate subjects for this policy derived from the token
      description: |-
        **This action only works when authenticated with a Json Web Token (JWT).**

        Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
        * the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
        * one of the subject IDs is contained in the authenticated token
        * at least one `READ` permission to a `thing:/` resource path is granted

        a new subject is **injected into the matched policy entry** calculated with information extracted from the
        authenticated JWT.

        The injected subjects expire when the JWT expires.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
      responses:
        '204':
          description: The request was successful. Subjects were injected into authorized policy entries.
        '400':
          description: The request could not be completed because the authentication was not performed with a JWT.
        '403':
          description: |-
            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
            entries of the policy.
        '404':
          description: |-
            The request could not be completed because no policy entry matched the following conditions:
            * containing a a subject ID matching the JWT's authenticated subject
            * containing a `READ` permission granted to a `thing:/` resource path
      requestBody:
        $ref: '#/components/requestBodies/ActivateTokenIntegration'
  '/policies/{policyId}/actions/deactivateTokenIntegration':
    post:
      summary: Deactivate subjects for this policy derived from the token
      description: |-
        **This action only works when authenticated with a Json Web Token (JWT).**

        Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
        * the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
        * one of the subject IDs is contained in the authenticated token

        the calculated subject with information extracted from the authenticated JWT is **removed
        from the matched policy entry**.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
      responses:
        '204':
          description: The request was successful. Subjects were removed from authorized policy entries.
        '400':
          description: The request could not be completed because the authentication was not performed with a JWT.
        '403':
          description: |-
            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
            entries of the policy.
        '404':
          description: |-
            The request could not be completed because no policy entry matched the following conditions:
            * containing a a subject ID matching the JWT's authenticated subject
  '/policies/{policyId}/entries':
    get:
      summary: Retrieve the entries of a specific policy
      description: |-
        Returns all policy entries of the policy identified by the `policyId`
        path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The request successfully returned completed and returned are the
            policy entries.
          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/PolicyEntries'
        '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: Modify the entries of a specific policy
      description: |-
        Modify the policy entries of the policy identified by the `policyId`
        path parameter.

        Note: Take care to not lock yourself out. Use the placeholder {{ request:subjectId }}
        in order to let the backend insert the authenticated subjectId of the HTTP request.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The policy entries 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 `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 `policy:/entries` resource,
              without any revoke in a deeper path of the policy resource.
          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/PolicyEntries'
            example:
              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 entries.
          Use the placeholder `{{ request:subjectId }}` in order to let the
          backend insert the authenticated subjectId of the HTTP request.
        required: true
  '/policies/{policyId}/entries/{label}':
    get:
      summary: Retrieve the entries of a specific Label of a specific policy
      description: |-
        Returns all entries (subjects, resources, etc.) of the policy identified by the `policyId` path
        parameter, and by the `label` path parameter.
        Example label: DEFAULT.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The request successfully returned completed and returned is the
            policy entry.
          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/PolicyEntry'
        '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 or
            the policy entry 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 modify the entries of a specific Label of a specific policy
      description: |-
        Create or modify the policy entry identified by the
        `policyId` path parameter and with the label identified by the `label`
        path parameter.
        * If you specify a new label, the respective policy entry will be created
        * If you specify an existig label, the respective policy entry will be updated
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The policy entry 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 entry
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyEntry'
        '204':
          description: The policy entry 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 entry 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 `policy:/entries/{label}` resource,
                without any revoke in a deeper path of the policy resource.
          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/PolicyEntry'
            example:
              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 entry.
          Use the placeholder `{{ request:subjectId }}` in order to let the
          backend insert the authenticated subjectId of the HTTP request.
          ### Example
          Given your policy "com.acme.coffeemaker:policy-01" only has the
          DEFAULT entry, and you want to add a "Consumer" section which additionally allows USER-01
          (managed within a Nginx reverse proxy) to
          *read* the thing and to trigger a "makeCoffee" operation (i.e. POST such a message - see
          POST /things/{thingId}/inbox/messages/{messageSubject}).
          Set the label value to **Consumer** and the following request body:
          ```
          {
            "subjects": {
              "nginx:USER-01": {
                "type": "pre authenticated user from nginx"
              }
            },
            "resources": {
              "thing:/": {
                "grant": [
                  "READ"
                ],
                "revoke": []
              },
              "message:/": {
                "grant": [
                  "WRITE"
                ],
                "revoke": []
              }
            }
          }
          ```
        required: true
    delete:
      summary: Delete the entries of a specific Label of a specific policy
      description: |-
        Deletes the entry of the policy identified by the `policyId` path
        parameter and with the label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The policy entry 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 `policy:/entries/{label}` resource,
               without any revoke in a deeper path of the policy resource.
          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/{label}/actions/activateTokenIntegration':
    post:
      summary: Activate a subject for this policy entry derived from the token
      description: |-
        **This action only works when authenticated with a Json Web Token (JWT).**

        Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
        * the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
        * one of the subject IDs is contained in the authenticated token
        * at least one `READ` permission to a `thing:/` resource path is granted

        When all conditions match, a new subject is **injected into this policy entry** calculated with information
        extracted from the authenticated JWT.

        The injected subjects expire when the JWT expires.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
      responses:
        '204':
          description: The request was successful. The subject was injected.
        '400':
          description: The request could not be completed because the authentication was not performed with a JWT.
        '403':
          description: |-
            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on this
            policy entry.
        '404':
          description: |-
            The request could not be completed because this policy entry did not match the following conditions:
            * containing a a subject ID matching the JWT's authenticated subject
            * containing a `READ` permission granted to a `thing:/` resource path
      requestBody:
        $ref: '#/components/requestBodies/ActivateTokenIntegration'
  '/policies/{policyId}/entries/{label}/actions/deactivateTokenIntegration':
    post:
      summary: Deactivate a subject for this policy entry derived from the token
      description: |-
        **This action only works when authenticated with a Json Web Token (JWT).**

        Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
        * the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
        * one of the subject IDs is contained in the authenticated token

        When all conditions match, the calculated subject with information extracted from the authenticated JWT is **removed
        from this policy entry**.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
      responses:
        '204':
          description: The request was successful. The subject was removed.
        '400':
          description: The request could not be completed because the authentication was not performed with a JWT.
        '403':
          description: The request could not be completed because the user did not have the `EXECUTE` permission on this policy entry.
        '404':
          description: |-
            The request could not be completed because this policy entry did not match the following conditions:
            * containing a a subject ID matching the JWT's authenticated subject
  '/policies/{policyId}/entries/{label}/subjects':
    get:
      summary: Retrieve all Subjects for a specific Label of a specific policy
      description: |-
        Returns all subject entries of the policy identified by the
        `policyId` path parameter, and by the `label`
        path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The request successfully returned. The subjects are returned.
          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/Subjects'
        '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 or
            the policy entry 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 modify all Subjects for a specific Label of a specific policy
      description: |-
        Create or modify at once ALL subjects of the policy entry identified
        by the `policyId` path parameter, and by the `label` path parameter.

        ### Example - delete all subjects
        To delete all subjects set an empty body { }

        ### Example - entities authenticated by nginx
        To add a user authenticated via pre-authentication at nginx:

        ```
        {
          "nginx:ID-user": {
            "type": "pre authenticated user from nginx"
          }
        }
        ```
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The Subjects were successfully created or 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 subjects 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 `policy:/entries/{label}/subjects` resource,
              without any revoke in a deeper path of the policy resource.
          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/Subjects'
        description: |-
          JSON representation of the Subjects.


          Use the placeholder `{{ request:subjectId }}` in order to let the
          backend insert the authenticated subjectId of the HTTP request.
        required: true
  '/policies/{policyId}/entries/{label}/subjects/{subjectId}':
    get:
      summary: Retrieve one specific Subject for a specific Label of a specific policy
      description: |-
        Returns the subject with ID `subjectId` of the policy entry identified
        by the `policyId` path parameter, and by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/SubjectIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The request successfully returned completed and returned is the
            Subject.
          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/SubjectEntry'
        '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,
            the policy entry or the Subject 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 modify one specific Subject for a specific Label of a specific policy
      description: |-
        Create or modify the subject with ID `subjectId` of the policy identified
        by the `policyId` path parameter, and by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/SubjectIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The Subject 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 Subject
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectEntry'
        '204':
          description: The Subject 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 subject 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:/entries/{label}/subjects/{subjectId}` resource,
              without any revoke in a deeper path of the policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID or
            the policy entry 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/SubjectEntry'
        description: JSON representation of the Subject
        required: true
    delete:
      summary: Delete one specific Subject for a specific Label of a specific policy
      description: |-
        Deletes the subject with ID `subjectId` from the policy identified
        by the `policyId` path parameter and
        by the `label` path parameter.

        Note: If the subject is used in other labels, it will not be deleted there,
        i.e. it will not lose those permissions, but only the permissions defined in the
        label specified at this path.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/SubjectIdPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The Subject 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:/entries/{label}/subjects/{subjectId}` resource,
              without any revoke in a deeper path of the policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID,
            the policy entry or the Subject 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/{label}/resources':
    get:
      summary: Retrieve all Resources for a specific Label of a specific policy
      description: |-
        Returns all resource entries of the policy identified by
        the `policyId` path parameter,
        and by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: The request successfully returned. The resources are returned.
          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/Resources'
        '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 or
            the policy entry 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 modify all Resources for a specific Label of a specific policy
      description: |-
        Create or modify all resources of the policy
        identified by the `policyId` path parameter,
        and by the `label` path parameter.

        ### Delete all resource entries

        Set the empty body part, if you need to delete all resource entries: { }

        ### Set max permissions on all ressources
        ```
        {
          "policy:/": {
            "grant": [
              "READ",
              "WRITE"
            ],
            "revoke": []
          },
          "thing:/": {
            "grant": [
              "READ",
              "WRITE"
            ],
            "revoke": []
          },
          "message:/": {
            "grant": [
              "READ",
              "WRITE"
            ],
            "revoke": []
          }
        }
        ```
        ### Allow to read all parts of a thing except the "confidential" feature
        ```
        {
          "thing:/": {
            "grant": [
              "READ"
            ],
            "revoke": []
          },
          "things:/features/confidential": {
            "grant": [],
            "revoke": [
              "READ"
            ]
          }
        }
        ```
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The Resources were successfully created or 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 is invalid, or no valid Resources 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.
              You need `WRITE` permission on the root `policy:/entries/{label}/resources` resource,
              without any revoke in a deeper path of the policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID or
            the policy entry 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/Resources'
        description: JSON representation of the Resources
        required: true
  '/policies/{policyId}/entries/{label}/resources/{resourcePath}':
    get:
      summary: Retrieve one specific Resource for a specific Label of a specific policy
      description: |-
        Returns the resource with path `resourcePath` of the policy identified
        by the `policyId` path parameter, and
        by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/ResourcePathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
      responses:
        '200':
          description: |-
            The request successfully returned completed and returned is the
            Resource.
          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/ResourceEntry'
        '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,
            the policy entry or the Resource 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 modify one specific Resource for a specific Label of a specific policy
      description: |-
        Create or modify the Resource with path `resourcePath` of the policy
        entry identified by the `label` path parameter belonging to the policy
        identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/ResourcePathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '201':
          description: The Resource 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 Resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceEntry'
        '204':
          description: The Resource 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
        '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))
              * the JSON is invalid, or no valid Resource 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.
                You need `WRITE` permission on the `policy:/entries/{label}/resources/{resourcePath}` resource,
                without any revoke in a deeper path of the policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID or
            the policy entry 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/ResourceEntry'
        description: JSON representation of the Resource
        required: true
    delete:
      summary: Delete one specific Resource for a specific Label of a specific policy
      description: |-
        Deletes the resource with path `resourcePath` from the policy
        identified by the the `policyId` path parameter, and by the
        `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PolicyIdPathParam'
        - $ref: '#/components/parameters/LabelPathParam'
        - $ref: '#/components/parameters/ResourcePathPathParam'
        - $ref: '#/components/parameters/IfMatchHeaderParamHash'
        - $ref: '#/components/parameters/IfNoneMatchHeaderParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/ResponseRequiredParam'
      responses:
        '204':
          description: The Resource 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 `policy:/entries/{label}/resources/{resourcePath}` resource,
                without any revoke in a deeper path of the policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '404':
          description: |-
            The request could not be completed. The policy with the given ID,
            the policy entry or the Resource was not found in the context of the
            authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /whoami:
    get:
      summary: Retrieve information about the current caller
      description: 'Get information about the current caller, e.g. the auth subjects that are generated for the caller.'
      tags:
        - Policies
      responses:
        '200':
          description: The request successfully returned information about the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoAmI'
        '401':
          description: The request could not be completed due to missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
  /search/things:
    get:
      summary: Search for things
      description: |-
        This resource can be used to search for things.

        * The query parameter `filter` is not mandatory. If it is not set, the
          result contains all things which the logged in user is allowed to read.

        * The search is case sensitive. In case you don't know how exactly the
          spelling of value of the namespace, name, attribute, feature etc. is, use the *like*
          notation instead of *eq* for filtering.

        * The resource supports sorting and paging. If paging is not explicitly
          specified by means of the `size` option, a default count of `25`
          documents is returned.

        * The internal search index is "eventually consistent".  Consistency with the latest
          thing updates should recover within milliseconds.
      parameters:
        - $ref: '#/components/parameters/SearchFilter'
        - $ref: '#/components/parameters/NamespacesFilter'
        - $ref: '#/components/parameters/ThingFieldsQueryParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - name: option
          in: query
          description: |-
            Possible values for the parameter:

            #### Sort operations

            * ```sort([+|-]{property})```
            * ```sort([+|-]{property},[+|-]{property},...)```

            #### Paging operations

            * ```size({page-size})```  Maximum allowed page size is `200`. Default page size is `25`.
            * ```cursor({cursor-id})```  Start the search from the cursor location. Specify the cursor ID without
            quotation marks. Cursor IDs are given in search responses and mark the position after the last entry of
            the previous search. The meaning of cursor IDs is unspecified and may change without notice.

            The paging option `limit({offset},{count})` is deprecated.
            It may result in slow queries or timeouts and will be removed eventually.

            #### Examples:

            * ```sort(+thingId)```
            * ```sort(-attributes/manufacturer)```
            * ```sort(+thingId,-attributes/manufacturer)```
            * ```size(10)``` return 10 results
            * ```cursor(LOREMIPSUM)```  return results after the position of the cursor `LOREMIPSUM`.

            #### Combine:

            If you need to specify multiple options, when using the swagger UI just write each option in a new line.
            When using the plain REST API programmatically,
            you will need to separate the options using a comma (,) character.

            ```size(200),cursor(LOREMIPSUM)```

            The deprecated paging option `limit` may not be combined with the other paging options `size` and `cursor`.
          required: false
          schema:
            type: string
      tags:
        - Things-Search
      responses:
        '200':
          description: An array of the matching things.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultThings'
        '400':
          description: |-
            The request could not be completed. A provided parameter is in a
            wrong format.
          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 due to an invalid authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '504':
          description: The request ran out of time to execute on the the back-end. Optimize your query and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
  /search/things/count:
    get:
      summary: Count things
      description: |-
        This resource can be used to count things.

        The query parameter `filter` is not mandatory. If it is not set there is
        returned the total amount of things which the logged in user is allowed
        to read.

        To search for nested properties, we use JSON Pointer notation
        (RFC-6901). See the following example how to search for the sub property
        `location` of the parent property `attributes` with a forward slash as
        separator:

        ```eq(attributes/location,"kitchen")```
      parameters:
        - $ref: '#/components/parameters/SearchFilter'
        - $ref: '#/components/parameters/NamespacesFilter'
        - $ref: '#/components/parameters/TimeoutParam'
      tags:
        - Things-Search
      responses:
        '200':
          description: A number indicating the amount of matched things
          content:
            application/json:
              schema:
                type: integer
        '400':
          description: |-
            The request could not be completed. A provided parameter is in a
            wrong format.
          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 due to an invalid authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '504':
          description: The request ran out of time to execute on the the back-end. Optimize your query and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
  /cloudevents:
    post:
      summary: Processes a CloudEvent sent in Ditto Protocol
      description: |-
        Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md)
        in [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html).

        The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination.

        Find more documentation on that [here](https://www.eclipse.org/ditto/httpapi-protocol-bindings-cloudevents.html).
      tags:
        - CloudEvents
      parameters:
        - in: header
          name: ce-specversion
          description: The CloudEvents "specversion".
          schema:
            type: string
            example: '1.0'
          required: true
        - in: header
          name: ce-type
          description: The CloudEvents event "type".
          schema:
            type: string
            example: com.example.someevent
          required: true
        - in: header
          name: ce-source
          description: The CloudEvents event "source".
          schema:
            type: string
            example: /mycontext
          required: true
        - in: header
          name: ce-id
          description: The CloudEvents event "id".
          schema:
            type: string
            example: 1234-1234-1234
          required: true
        - in: header
          name: ce-time
          description: The CloudEvents event "time".
          schema:
            type: string
            format: date-time
            example: '2020-12-31T23:59:59Z'
          required: true
        - in: header
          name: ce-dataschema
          description: 'The CloudEvents event "dataschema". If provided, this must start with `ditto:`.'
          schema:
            type: string
          required: false
      responses:
        '202':
          description: 'The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence.'
        '400':
          description: |-
            The request could not be completed. Possible reasons:
              * the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request
              * the payload was missing from the CloudEvent
              * the [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) message could not be parsed or was missing a required field
          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.
          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 perform the contained Ditto Protocol command.
          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'
        '415':
          description: The `Content-Type` of the request was not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
      requestBody:
        content:
          application/vnd.eclipse.ditto+json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                  description: |-
                    Contains information about the contents of the payload:
                    * the affected Thing (namespace and Thing ID)
                    * the type of operation (command/event, create/retrieve/modify/delete)
                  example: org.eclipse.ditto/thing-1/things/twin/commands/modify
                headers:
                  type: object
                  description: Additional headers.
                  properties:
                    correlation-id:
                      type: string
                      description: |-
                        The correlation-id header is used for linking one message with another.
                        It typically links a reply message with its requesting message.
                  example:
                    correlation-id: 1234-4321-1234
                path:
                  type: string
                  description: References the part of a Thing which is affected by this message.
                  example: /features/location/properties/longitude
                value:
                  oneOf:
                    - type: object
                    - type: string
                    - type: number
                    - type: array
                    - type: boolean
                  description: The `value` field contains the actual payload e.g. a sensor value.
              required:
                - topic
                - path
            example:
              topic: org.eclipse.ditto/thing-1/things/twin/commands/modify
              path: /
              value:
                attributes:
                  foo: 42
        description: |-
          The [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) payload defining which
          command to process.
components:
  requestBodies:
    Attributes:
      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
    Definition:
      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: `""`
    Payload:
      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.
    Value:
      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
    ActivateTokenIntegration:
      content:
        application/json:
          schema:
            properties:
              announcement:
                $ref: '#/components/schemas/SubjectAnnouncement'
          example:
            announcement:
              beforeExpiry: 5m
              whenDeleted: true
      description: Optional request payload for `activateTokenIntegration` policy action.
      required: false
  responses:
    EntityTooLarge:
      description: The created or modified entity is larger than the accepted limit of 100 kB.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdvancedError'
    MessageTimeout:
      description: The request could not be completed as there is no consumer for this message connected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdvancedError'
    MessageTooLarge:
      description: The size of the send message is larger than the accepted limit of 250 kB.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdvancedError'
    NotModified:
      description: |-
        The (sub-)resource has not been modified. This happens when you specified a If-None-Match header which
         matches the current ETag of the (sub-)resource.
      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
    PreconditionFailed:
      description: |-
        A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you
        specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of
        the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a
        failing If-None-Match header for a read request, status 304 will be returned instead.
      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/AdvancedError'
  parameters:
    AllowPolicyLockoutParam:
      name: allow-policy-lockout
      in: query
      description: |-
        Defines whether a subject is allowed to create a policy without having WRITE permission on the policy
        resource of the created policy.

        The default (if ommited) is `false`.
      required: false
      schema:
        type: boolean
    AttributesPathPathParam:
      name: attributePath
      in: path
      description: 'The path to the attribute, e.g. **manufacturer/name**'
      required: true
      schema:
        type: string
    AttributesFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields from the attributes to be
        included in the returned JSON.

        #### Selectable fields

        Supports selecting arbitrary sub-fields as defined in the attributes by
        using a comma-separated list:
          * several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

            For example:
              * `?fields=model` would select only `model` attribute value (if present)
              * `?fields=model,make` would select `model` and `make` attribute values (if present)

        Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
        inside parentheses `( )`:
          * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
          * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield

            For example:
             * `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` attribute

        #### Examples

        * `?fields=model,make,location(longitude,latitude)`

        * `?fields=listOfAddresses/postal(city,street))`
      required: false
      schema:
        type: string
    DesiredPropertiesFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields from the desiredProperties to be
        included in the returned JSON.

        #### Selectable fields

        Supports selecting arbitrary sub-fields as defined in the desiredProperties by
        using a comma-separated list:
          * several desiredProperties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

            For example:
              * `?fields=temperature` would select only `temperature` property value of desiredProperties (if present)
              * `?fields=temperature,humidity` would select only `temperature` and `humidity` property values of desiredProperties (if present)

        Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
        inside parentheses `( )`:
          * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
          * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield

            For example:
             * `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` property of desiredProperties

        #### Examples

        * `?fields=temperature,humidity,location(longitude,latitude)`

        * `?fields=configuration,status(powerConsumption/watts)`
      required: false
      schema:
        type: string
    FeatureFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields from the selected feature to be
        included in the returned JSON.

        #### Selectable fields

        * `properties`

          Supports selecting arbitrary sub-fields by using a comma-separated list:
            * several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

              For example:
                * `?fields=properties/color` would select only `color` property value (if present)
                * `?fields=properties/color,properties/brightness` would select only `color` and `brightness` property values (if present)

          Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
            * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
            * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield

              For example:
               * `?fields=properties(color,brightness)` would select only `color` and `brightness` property values (if present)
               * `?fields=properties(location/longitude)` would select the `longitude` value inside the `location` object

        #### Examples

        * `?fields=properties(color,brightness)`
      required: false
      schema:
        type: string
    FeatureIdPathPathParam:
      name: featureId
      in: path
      description: The ID of the feature - has to conform to RFC-3986 (URI)
      required: true
      schema:
        type: string
    FeaturesFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields from one or more features to be
        included in the returned JSON.

        #### Selectable fields

        * `{featureId}` The ID of the feature to select properties in
          * `properties`
            Supports selecting arbitrary sub-fields by using a comma-separated list:
              * several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
                For example:
                  * `?fields={featureId}/properties/color` would select only `color` property value (if present) of the feature identified with `{featureId}`
                  * `?fields={featureId}/properties/color,properties/brightness` would select only `color` and `brightness` property values (if present) of the feature identified with `{featureId}`
            Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
              * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
              * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
                For example:
                 * `?fields={featureId}/properties(color,brightness)` would select only `color` and `brightness` property values (if present) of the feature identified with `{featureId}`
                 * `?fields={featureId}/properties(location/longitude)` would select the `longitude` value inside the `location` object of the feature identified with `{featureId}`


        #### Examples
        * `?fields=EnvironmentScanner/properties(temperature,humidity)`
        * `?fields=EnvironmentScanner/properties(temperature,humidity),Vehicle/properties/configuration`
      required: false
      schema:
        type: string
    IfMatchHeaderParam:
      name: If-Match
      in: header
      description: |-
        The `If-Match` header, which has to conform to RFC-7232 (Conditional Requests). Common usages are:
          * optimistic locking by specifying the `ETag` from a previous GET response, e.g. `If-Match: "rev:4711"`
          * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`
      required: false
      schema:
        type: string
    IfMatchHeaderParamHash:
      name: If-Match
      in: header
      description: |-
        The `If-Match` header which has to conform to RFC-7232 (Conditional Requests). Common usages are:
          * optimistic locking by specifying the `ETag` from a previous HTTP response, e.g. `If-Match: "hash:a75ece4e"`
          * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`
      required: false
      schema:
        type: string
    IfNoneMatchHeaderParam:
      name: If-None-Match
      in: header
      description: 'The `If-None-Match` header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying `If-None-Match: *`.'
      required: false
      schema:
        type: string
    LabelPathParam:
      name: label
      in: path
      description: The label of a policy entry
      required: true
      schema:
        type: string
    LiveMessageRequestedAcksParam:
      name: requested-acks
      in: query
      description: |-
        Contains the "requested acknowledgements" for this request as comma separated list. The HTTP call will
        block until all requested acknowledgements were aggregated or will time out based on the specified `timeout`
        parameter.

        The default (if omitted) requested acks is `requested-acks=live-response` which will block the
        HTTP call until a subscriber of the live message sends a response.
      required: false
      schema:
        type: string
    MessageClaimTimeoutParam:
      name: timeout
      in: query
      description: |-
        Contains an optional timeout (in seconds) of how long to wait for the Claim response and therefore block the
        HTTP request. Default value (if omitted): 60 seconds. Maximum value: 600 seconds. A value of 0 seconds applies
        fire and forget semantics for the message.
      required: false
      schema:
        type: integer
    MessageSubjectPathParam:
      name: messageSubject
      in: path
      description: The subject of the Message - has to conform to RFC-3986 (URI)
      required: true
      schema:
        type: string
    MessageTimeoutParam:
      name: timeout
      in: query
      description: |-
        Contains an optional timeout (in seconds) of how long to wait for the message response and therefore block the
        HTTP request. Default value (if omitted): 10 seconds. Maximum value: 60 seconds. A value of 0 seconds applies
        fire and forget semantics for the message.
      required: false
      schema:
        type: integer
    NamespacesFilter:
      name: namespaces
      in: query
      description: |-
        A comma-separated list of namespaces. This list is used to limit the query to things in the given namespaces
        only.


        #### Examples:

        * `?namespaces=com.example.namespace`

        * `?namespaces=com.example.namespace1,com.example.namespace2`
      required: false
      schema:
        type: string
    PolicyIdPathParam:
      name: policyId
      in: path
      description: |-
        The ID of the policy needs to follow 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 namespace needs to:
        * conform to the reverse domain name notation
      required: true
      schema:
        type: string
    PropertiesFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields from the properties to be
        included in the returned JSON.

        #### Selectable fields

        Supports selecting arbitrary sub-fields as defined in the properties by
        using a comma-separated list:
          * several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

            For example:
              * `?fields=temperature` would select only `temperature` property value (if present)
              * `?fields=temperature,humidity` would select only `temperature` and `humidity` property values (if present)

        Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
        inside parentheses `( )`:
          * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
          * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield

            For example:
             * `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` property

        #### Examples

        * `?fields=temperature,humidity,location(longitude,latitude)`

        * `?fields=configuration,status(powerConsumption/watts)`
      required: false
      schema:
        type: string
    PropertyPathPathParam:
      name: propertyPath
      in: path
      description: The path to the property
      required: true
      schema:
        type: string
    PutMetadataParam:
      name: put-metadata
      in: header
      description: 'The `put-metadata` header, which sets Metadata information in the Thing.'
      required: false
      schema:
        type: array
        description: An array of objects containing metadata to apply.
        items:
          type: object
          description: Object containing a `key` where to apply the metadata and a `value` with the metadata value to apply.
          additionalProperties:
            properties:
              key:
                type: string
                description: The JsonPointer to set the metadata `value` to. May start with `*/<key>` in order to apply the metadata to all affected JSON leaves.
              value:
                description: The arbitrary JSON value to set as metadata.
    RequestedAcksParam:
      name: requested-acks
      in: query
      description: |-
        Contains the "requested acknowledgements" for this modifying request as comma separated list. The HTTP call will
        block until all requested acknowledgements were aggregated or will time out based on the specified `timeout`
        parameter.

        The default (if omitted) requested acks is `requested-acks=twin-persisted` which will block the
        HTTP call until the change was persited to the twin.
      required: false
      schema:
        type: string
    ResourcePathPathParam:
      name: resourcePath
      in: path
      description: The path of an (Authorization) Resource
      required: true
      schema:
        type: string
    ResponseRequiredParam:
      name: response-required
      in: query
      description: |-
        Defines whether a response is required to the API call or not - if set to `false` the response will directly
        sent back with a status code of `202` (Accepted).

        The default (if ommited) response is `true`.
      required: false
      schema:
        type: boolean
    SearchFilter:
      name: filter
      in: query
      description: |-

        #### Filter predicates:

        * ```eq({property},{value})```  (i.e. equal to the given value)

        * ```ne({property},{value})```  (i.e. not equal to the given value)

        * ```gt({property},{value})```  (i.e. greater than the given value)

        * ```ge({property},{value})```  (i.e. equal to the given value or greater than it)

        * ```lt({property},{value})```  (i.e. lower than the given value or equal to it)

        * ```le({property},{value})```  (i.e. lower than the given value)

        * ```in({property},{value},{value},...)```  (i.e. contains at least one of the values listed)

        * ```like({property},{value})```  (i.e. contains values similar to the expressions listed)

        * ```exists({property})```  (i.e. all things in which the given path exists)


        Note: When using filter operations, only things with the specified properties are returned.
        For example, the filter `ne(attributes/owner, "SID123")` will only return things that do have
        the `owner` attribute.


        #### Logical operations:


        * ```and({query},{query},...)```

        * ```or({query},{query},...)```

        * ```not({query})```


        #### Examples:

        * ```eq(attributes/location,"kitchen")```

        * ```ge(thingId,"myThing1")```

        * ```gt(_created,"2020-08-05T12:17")```

        * ```exists(features/featureId)```

        * ```and(eq(attributes/location,"kitchen"),eq(attributes/color,"red"))```

        * ```or(eq(attributes/location,"kitchen"),eq(attributes/location,"living-room"))```

        * ```like(attributes/key1,"known-chars-at-start*")```

        * ```like(attributes/key1,"*known-chars-at-end")```

        * ```like(attributes/key1,"*known-chars-in-between*")```

        * ```like(attributes/key1,"just-som?-char?-unkn?wn")```

        The `like` filters with the wildcard `*` at the beginning can slow down your search request.
      required: false
      schema:
        type: string
    SubjectIdPathParam:
      name: subjectId
      in: path
      description: The ID of an (Authorization) Subject
      required: true
      schema:
        type: string
    ThingFieldsQueryParam:
      name: fields
      in: query
      description: |-
        Contains a comma-separated list of fields to be included in the returned
        JSON. attributes can be selected in the same manner.

        #### Selectable fields

        * `thingId`
        * `policyId`
        * `definition`
        * `attributes`

           Supports selecting arbitrary sub-fields by using a comma-separated list:
            * several attribute paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

              For example:
                * `?fields=attributes/model` would select only `model` attribute value (if present)
                * `?fields=attributes/model,attributes/location` would select only `model` and
                   `location` attribute values (if present)

          Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
            * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901)
              separated with `/`) to select

            * sub-selectors can be used to request only specific sub-fields by placing expressions
              in parentheses `( )` after a selected subfield

              For example:
               * `?fields=attributes(model,location)` would select only `model`
                  and `location` attribute values (if present)
               * `?fields=attributes(coffeemaker/serialno)` would select the `serialno` value
                  inside the `coffeemaker` object
               * `?fields=attributes/address/postal(city,street)` would select the `city` and
                  `street` values inside the `postal` object inside the `address` object

        * `features`

          Supports selecting arbitrary fields in features similar to `attributes` (see also features documentation for more details)

        * `_namespace`

          Specifically selects the namespace also contained in the `thingId`

        * `_revision`

          Specifically selects the revision of the thing. The revision is a counter, which is incremented on each modification of a thing.

        * `_created`

          Specifically selects the created timestamp of the thing in ISO-8601 UTC format. The timestamp is set on creation of a thing.

        * `_modified`

          Specifically selects the modified timestamp of the thing in ISO-8601 UTC format. The timestamp is set on each modification of a thing.

        * `_metadata`

          Specifically selects the Metadata of the thing. The content is a JSON object having the Thing's JSON structure with the difference that the JSON leaves of the Thing are JSON objects containing the metadata.

        * `_policy`

          Specifically selects the content of the policy associated to the thing. (By default, only the policyId is returned.)

        #### Examples

        * `?fields=thingId,attributes,features`
        * `?fields=attributes(model,manufacturer),features`
      required: false
      schema:
        type: string
    ThingIdPathParam:
      name: thingId
      in: path
      description: 'The ID of a thing needs to follow 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
      schema:
        type: string
    TimeoutParam:
      name: timeout
      in: query
      description: |-
        Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested
        acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or
        together with `s`, `ms` or `m` unit. Example: `42s`, `1m`.

        The default (if omitted) timeout is `10s`. Maximum value: `60s`.

        A value of `0` applies fire and forget semantics for the command resulting in setting `response-required=false`.
      required: false
      schema:
        type: string
  schemas:
    Error:
      properties:
        status:
          type: integer
          description: The HTTP status of the error
        message:
          type: string
          description: The message of the error - what went wrong
        description:
          type: string
          description: A description how to fix the error or more details
        href:
          type: string
          description: A link to further information about the error and how to fix it
      required:
        - status
        - message
    AdvancedError:
      properties:
        status:
          type: integer
          description: The HTTP status of the error
        error:
          type: string
          description: The error code of the occurred exception
        message:
          type: string
          description: The message of the error - what went wrong
        description:
          type: string
          description: A description how to fix the error or more details
        href:
          type: string
          description: A link to further information about the error and how to fix it
      required:
        - status
        - error
        - message
    Attributes:
      type: object
      description: An arbitrary JSON object describing the attributes of a thing.
    Definition:
      type: string
      description: 'A single fully qualified identifier of a definition in the form ''namespace:name:version'''
      pattern: '([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+)'
    FeatureDefinition:
      type: array
      description: The definitions of a feature.
      items:
        type: string
        description: 'A single fully qualified identifier of a feature definition in the form ''namespace:name:version'''
        pattern: '([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+)'
    FeatureProperties:
      type: object
      description: An arbitrary JSON object describing the properties of a feature.
    FeatureDesiredProperties:
      type: object
      description: An arbitrary JSON object describing the desired properties of a feature.
    Feature:
      type: object
      properties:
        definition:
          $ref: '#/components/schemas/FeatureDefinition'
        properties:
          $ref: '#/components/schemas/FeatureProperties'
        desiredProperties:
          $ref: '#/components/schemas/FeatureDesiredProperties'
    SearchResultThings:
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Thing'
        cursor:
          type: string
    SearchResultThingsCount:
      type: integer
    NewThing:
      type: object
      properties:
        _policy:
          allOf:
            - $ref: '#/components/schemas/Policy'
          description: |-
            The initial policy to create for this thing. This will create a separate policy entity managed by resource `/policies/{thingId}`.


            Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
        _copyPolicyFrom:
          type: string
          description: |-
            This field may contain
            * the policy ID of an existing policy.

              The policy is copied and used for this newly created thing. The
              caller needs to have READ and WRITE<sup>*</sup> access to the policy.
            * a placeholder reference to a thing in the format {{ ref:things/[thingId]/policyId }} where you need to
              replace [thingId] with a valid thing ID.

              The newly created thing will then obtain a copy of the policy of
              the referenced thing. The caller needs to have READ access to the thing and READ and WRITE<sup>*</sup>
              access to the policy of the thing.


            <sup>*</sup> The check for WRITE permission avoids locking yourself out of the newly created policy. You can
            bypass this check by setting the header `allowPolicyLockout` to `true`. Be aware that the authorized
            subject cannot modify the policy if you do not assign WRITE permission on the policy resource!

            If you want to specify a policy ID for the copied policy, use the policyId field.

            This field must not be used together with the field _policy. If you specify both _policy and _copyPolicyFrom
            this will lead to an error response.
        policyId:
          type: string
          description: |-
            The policy ID used for controlling access to this thing. Managed by
            resource `/policies/{policyId}`.
        definition:
          $ref: '#/components/schemas/Definition'
        attributes:
          $ref: '#/components/schemas/Attributes'
        features:
          $ref: '#/components/schemas/Features'
      required:
        - policyId
    Thing:
      type: object
      properties:
        thingId:
          type: string
          description: Unique identifier representing the thing
        policyId:
          type: string
          description: 'The ID of the policy which controls the access to this thing. policies are managed by resource `/policies/{policyId}`'
        definition:
          $ref: '#/components/schemas/Definition'
        attributes:
          $ref: '#/components/schemas/Attributes'
        features:
          $ref: '#/components/schemas/Features'
        _revision:
          type: string
          description: |-
            _(read-only)_ The revision is a counter which is incremented on each modification of a Thing. This field
            is not returned by default but must be selected explicitly.
        _created:
          type: string
          description: |-
            _(read-only)_ The created timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on creation
            of a Thing. This field is not returned by default but must be selected explicitly.
        _modified:
          type: string
          description: |-
            _(read-only)_ The modified timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on each
            modification of a Thing. This field is not returned by default but must be selected explicitly.
        _metadata:
          type: object
          description: _(read-only)_ The Metadata of the Thing. This field is not returned by default but must be selected explicitly.
      required:
        - thingId
        - policyId
    NewPolicy:
      type: object
      description: Policy consisting of policy entries
      properties:
        entries:
          $ref: '#/components/schemas/PolicyEntries'
      required:
        - entries
    Policy:
      type: object
      description: Policy consisting of policy entries
      properties:
        policyId:
          type: string
          description: Unique identifier representing the policy
        entries:
          $ref: '#/components/schemas/PolicyEntries'
      required:
        - policyId
        - entries
    PolicyEntries:
      type: object
      description: Policy entries containing one policy entry for each arbitrary `label` key
      properties:
        label1:
          $ref: '#/components/schemas/PolicyEntry'
        labelN:
          $ref: '#/components/schemas/PolicyEntry'
    PolicyEntry:
      type: object
      description: Single policy entry containing Subjects and Resources.
      properties:
        subjects:
          $ref: '#/components/schemas/Subjects'
        resources:
          $ref: '#/components/schemas/Resources'
      required:
        - subjects
        - resources
    Subjects:
      type: object
      description: A SubjectEntry defines who is addressed.
      properties:
        'nginx:subjectId1':
          $ref: '#/components/schemas/SubjectEntry'
        'nginx:subjectIdN':
          $ref: '#/components/schemas/SubjectEntry'
    SubjectEntry:
      type: object
      description: Single (Authorization) Subject entry holding its type.
      required:
        - type
      properties:
        type:
          type: string
          description: 'The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.'
        expiry:
          type: string
          description: The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.
          format: date-time
        announcement:
          $ref: '#/components/schemas/SubjectAnnouncement'
      example:
        type: 'This is some description for this subject, adjust as needed.'
        expiry: '2020-12-07T11:36:40Z'
        announcement:
          beforeExpiry: 5m
          whenDeleted: true
    Resources:
      type: object
      description: |-
        (Authorization) Resources containing one ResourceEntry for each
        `type:path` key, `type` being one of the following `thing`, `policy`, `message`.
      additionalProperties:
        $ref: '#/components/schemas/ResourceEntry'
      example:
        'thing:/':
          grant:
            - READ
            - WRITE
          revoke: null
        'thing:/attributes/some/path':
          grant: null
          revoke:
            - READ
        'policy:/':
          grant:
            - READ
            - WRITE
          revoke: null
        'message:/':
          grant:
            - READ
            - WRITE
          revoke: null
    ResourceEntry:
      type: object
      description: |-
        Single (Authorization) Resource entry defining permissions per effect.
        Allowed effects are `grant` and `revoke`.
      properties:
        grant:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        revoke:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    Permission:
      type: string
      description: A Permission allows a certain action on an entity
      enum:
        - READ
        - WRITE
    SubjectAnnouncement:
      type: object
      description: Settings for announcements to be made about the subject.
      properties:
        beforeExpiry:
          type: string
          description: |-
            The duration before expiry when an announcement should be made.
            Must be a positive integer followed by one of `h` (hour), `m` (minute) or `s` (second).
        whenDeleted:
          type: boolean
          description: Whether an announcement should be made when this subject is deleted.
      example:
        beforeExpiry: 5m
        whenDeleted: true
    Features:
      type: object
      description: |-
        List of features where the key represents the `featureId` of each feature.
        The `featureId` key must be unique in the list.
      additionalProperties:
        $ref: '#/components/schemas/Feature'
    WhoAmI:
      type: object
      description: Contains information about the current user and the auth subjects available for the used authentication.
      properties:
        defaultSubject:
          $ref: '#/components/schemas/WhoAmISubject'
        subjects:
          type: array
          items:
            $ref: '#/components/schemas/WhoAmISubject'
    WhoAmISubject:
      type: string
      description: An auth subject that can be used to provide access for a caller (e.g. in subject entries of policies).
  securitySchemes:
    NginxBasic:
      type: http
      description: Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
      scheme: basic
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.
    Google:
      type: oauth2
      description: Allow Eclipse Ditto to perform OAuth2.0 based authentication accessing your Google-ID.
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
          tokenUrl: /oauth2/google/token
          scopes:
            openid: Access your Google-ID