ditto-api-1.yml

# Copyright (c) 2017 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Eclipse Public License 2.0 which is available at
# http://www.eclipse.org/legal/epl-2.0
#
# SPDX-License-Identifier: EPL-2.0
openapi: 3.0.0
info:
  title: Eclipse Ditto HTTP API
  description: JSON-based, REST-like API for Eclipse Ditto
  version: "1"
servers:
  - url: https://ditto.eclipse.org/api/1
    description: "online Ditto Sandbox"
  - url: /api/1
    description: "local Ditto"
tags:
  - name: Things
    description: Manage every Thing
  - name: Features
    description: Structure the Features of your Things
  - name: Things-Search
    description: Find every Thing
  - name: Messages
    description: Talk with your Things
security:
#  - Google:
#    - openid
  - basicAuth: []
  - bearerAuth: []
paths:
  /things:
    get:
      summary: List all available Things
      description: |-
        Returns all Things passed in by the required parameter `ids`.

        Optionally you can use field selectors (see parameter `fields`) to only get the specified fields.

        To retrieve all Things the logged in user is allowed to read, please use the `GET /search/things` operation.
      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'
      responses:
        '200':
          description: The successfully completed request contains as its result the first 200 for the user available Things, sorted by their `thingId`.
          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 the Thing defined in the optional JSON body.

        The ID of the created Thing is a UUID generated by the service with the default namespace `org.eclipse.ditto`.
        Any `thingId`
        specified in the request body is therefore ignored. The ACL of the created Thing must include at least one
        entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`.
        If no ACL is provided, a default ACL with an entry for the authorized subject with all permissions set to
        `true` will be created.
      tags:
        - Things
      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. The JSON of the Thing to be created was invalid or the `thingId` was
            wrongly set in the request body.
          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'
        '412':
          $ref: '#/components/responses/preconditionFailed'
        '413':
          $ref: '#/components/responses/entityTooLarge'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThing'
            example: {}
        description: |-
          JSON representation of the Thing to be created.


          Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
  /things/{thingId}:
    get:
      summary: Retrieve a specific Thing
      description: |-
        Returns the Thing identified by the `thingId` path parameter.
        The response includes all details about the Thing.
        Optionally you can use field selectors (see parameter `fields`) to only get the specified fields.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/thingFieldsQueryParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or 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'
        '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. The `thingId` has to:

          * contain a mandatory namespace prefix (java package notation + `:` colon) - periods (`.`) may be used in namespace but not as first or last character
          * conform to RFC-2396 (URI)

        #### Valid examples

          * `org.eclipse.ditto.myproject:myFridge1`
          * `mynamespace:myFridge1`

        #### Invalid examples

          * `42:myFridge1`
          * `.foo:myFridge1`
          * `bar.:myFridge1`

        The ID of a Thing can't be changed after creation. Any `thingId` specified in the request body is therefore ignored.

        ### Creation of a new Thing

        The ACL of the created Thing must include at least one entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`.
        If no ACL is provided, a default ACL with an entry for the authorized subject with all permissions set to `true` will be created.


        Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.

        ### Permissions for updating an existing Thing

        For updating an existing Thing the authorized subject has to have the `WRITE` permission.
        If the new Thing to update contains an `acl` entry, the authorized subject additionally has to have the `ADMINISTRATE` permission.
        For authorized subjects which don't have the `ADMINISTRATE` permission, the complete Thing may be updated if the `acl` entry is not set.

        ### Partially updating an existing Thing

        When updating an existing Thing already containing `attributes`, `acl` or `features` the already 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.


        For example: A Thing already exists with this content:

        ```

        {
          "thingId": "namespace:thing-name",
          "acl": {...},
          "attributes": {
            "foo": 1
          },
          "features": {...}
        }

        ```

        The Thing's `attributes` may be modified without having to pass the `acl` or the `features` in again. The content
        of the request's body would be sufficient for updating the `attributes`:

        ```

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

        ```

        The `acl` and `features` of the Thing will not be overwritten, the Thing will be merged as one would expect it:

        ```

        {
          "thingId": "namespace:thing-name",
          "acl": {...},
          "attributes": {
            "foo": 2,
            "bar": false
          },
          "features": {...}
        }

        ```
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON of the Thing to be created/modified was either invalid or did contain a `thingId` which did not match the ID in the URL.
          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 as the caller had insufficient permissions.
            For modifying an existing Thing `WRITE` permission is required.

            If the `acl` of the Thing should be updated as well, the permission `ADMINISTRATE` is additionally required.
            The complete Thing without `acl` can however be updated with `WRITE` permission if the body does not contain an `acl` entry.
          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: {}
        description: |-
          JSON representation of the Thing to be modified.


          Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
    delete:
      summary: Delete a specific Thing
      description: |-
        Deletes the Thing identified by the `thingId` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Thing was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had insufficient permissions.
            For deleting an existing Thing `WRITE` and `ADMINISTRATE` permissions are 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'
  /things/{thingId}/acl:
    get:
      summary: Retrieve the complete ACL of a Thing
      description: |-
        Returns the Access Control List (ACL) of the Thing identified by the `thingId` path parameter.
        The response contains the ACL as JSON object containing a key for each subject having ACL permissions.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned completed and returned is the Access Control List.
          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/Acl'
              example:
                {
                  "authorizationSubject1": {
                    "READ": true,
                    "WRITE": true,
                    "ADMINISTRATE": true
                  },
                  "authorizationSubjectN": {
                    "READ": true,
                    "WRITE": true,
                    "ADMINISTRATE": true
                  }
                }
        '304':
          $ref: '#/components/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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: Modify the complete ACL of a Thing
      description: |-
        Modify the complete Access Control List (ACL) of the Thing identified by the `thingId` path parameter.

        The ACL must include at least one entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Access Control List 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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON was invalid, or no valid ACL 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 as the caller had insufficient permissions.
            For modifying the ACL of an existing Thing `ADMINISTRATE` 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 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/Acl'
            example:
              {
                "{{ request:subjectId }}":{
                  "READ": true,
                  "WRITE": true,
                  "ADMINISTRATE": true
                }
              }
        description: |-
          JSON representation of the Access Control List (ACL).


          Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
        required: true
  /things/{thingId}/acl/{authorizationSubject}:
    get:
      summary: Retrieve one ACL entry of a Thing for a specific subject
      description: |-
        Returns one Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject
        identified by the `authorizationSubject` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/authorizationSubjectPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned completed and returned is the ACL 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/AclEntry'
        '304':
          $ref: '#/components/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 ACL 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 one ACL entry of a Thing for a specific subject
      description: |-
        Create or modify the Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject
        identified by the `authorizationSubject` path parameter.

        An ACL entry must contain values for `READ`, `WRITE` and `ADMINISTRATE` permissions, all other permissions will be ignored.
        The ACL must contain at least one entry with all permissions set to `true`.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/authorizationSubjectPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The ACL 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 ACL entry
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AclEntry'
        '204':
          description: The ACL 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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON was invalid, or no valid ACL 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 as the caller had insufficient permissions.
            For modifying an ACL entry of an existing Thing `ADMINISTRATE` 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 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:
        $ref: '#/components/requestBodies/AclEntry'
    delete:
      summary: Delete one ACL entry of a Thing for a specific subject
      description: |-
        Deletes the the Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject
        identified by the `authorizationSubject` path parameter.

        The ACL must contain at least one entry with all permissions set to `true`.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/authorizationSubjectPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The ACL entry was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had insufficient permissions.
            For deleting an ACL entry of an existing Thing `ADMINISTRATE` 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 in the context of the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '412':
          $ref: '#/components/responses/preconditionFailed'
  '/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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 at once.
        The Attributes will be replaced by the request body's JSON.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON was invalid or 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 as the caller had 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 at once.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Attributes were successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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:
      ummary: 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), e.g.:
        `/things/{thingId}/attributes/address/city` in order to retrieve the `city` field of an `address` object.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/attributePathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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.
        The Attribute will be created if it doesn't exist or else updated. The Attribute (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901), e.g.:
        `/things/{thingId}/attributes/address/city` in order to create/update the `city` field of an `address` object.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/attributePathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had insufficient permissions. For modifying 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 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), e.g.:
        `/things/{thingId}/attributes/address/city` in order to delete the `city` field of an `address` object.
      tags:
        - Things
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/attributePathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Attribute was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or 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'
        '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 the Features of a Thing identified by the `thingId` path parameter at once. The list of Features will be replaced by the request body's JSON.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON was invalid or 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 as the caller had 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: {}
        description: |-
          JSON object of the Features to be modified at once. It can be also `null` or an empty object `{}` (all features cleared).
        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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Features were successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or 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'
        '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.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON of the Feature to be created 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'
        '403':
          description: |-
            The request could not be completed as the caller had 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: {}
        description: |-
          JSON representation of the Feature to be created/modified. It can also be `null` or an empty object `{}`.
        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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Feature was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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 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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or 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'
        '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 at once. The Definition will be replaced
        by the request body's JSON array.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON 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'
        '403':
          description: |-
            The request could not be completed as the caller had 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: {}
        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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Definition was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or 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'
        '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 at once.
        The Properties will be replaced by the request body's JSON.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON 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'
        '403':
          description: |-
            The request could not be completed as the caller had 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: {}
        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/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Properties were successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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 as the caller had 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 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), e.g.:
        `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to retrieve the `latitude` field of an `location` Property.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/propertyPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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), e.g.:
        `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to create/update the `latitude` field of an `location` object.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/propertyPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or the JSON 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'
        '403':
          description: |-
            The request could not be completed as the caller had 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), e.g.:
        `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to delete the `latitude` field of an `location` Property.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/propertyPathPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Property was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          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}/inbox/claim:
    post:
      summary: Initiates claiming a specific Thing in order to gain access.
      description: |-
        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 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.
        No special permissions are required to issue a Claim message.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/messageClaimTimeoutParam'
      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. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or at least one of the defined path 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'
        '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'
      requestBody:
        $ref: '#/components/requestBodies/Payload'
  /things/{thingId}/inbox/messages/{messageSubject}:
    post:
      summary: Send a message TO a specific Thing.
      description: |-
        Send a message with the subject `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
        API does not provide any kind of acknowledgement that the message was
        received by the Thing. In order to send a message, the user needs `WRITE`
        permission at the Thing level.

        The HTTP request 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.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/messageSubjectPathParam'
        - $ref: '#/components/parameters/messageTimeoutParam'
      responses:
        '202':
          description: The message was sent but not necessarly received by the Thing (fire and forget).
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or at least one of the defined path 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'
        '403':
          description: |-
            The request could not be completed as the caller does not have `WRITE` permission at the Thing level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/messageTooLarge'
      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.
        In order to send a message, the user needs `WRITE` permission at the
        Thing level.

        The HTTP request 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.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/messageSubjectPathParam'
        - $ref: '#/components/parameters/messageTimeoutParam'
      responses:
        '202':
          description: The message was sent (fire and forget).
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or at least one of the defined path 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'
        '403':
          description: |-
            The request could not be completed as the caller does not have `WRITE` permission at the Thing level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/messageTooLarge'
      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 API does not provide any kind of acknowledgement that the
        message was received by the Feature. In order to send a message, the user needs `WRITE` permission at the Thing level.

        The HTTP request 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.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/messageSubjectPathParam'
        - $ref: '#/components/parameters/messageTimeoutParam'
      responses:
        '202':
          description: The message was sent but not necessarly received by the Feature (fire and forget).
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or at least one of the defined path 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'
        '403':
          description: |-
            The request could not be completed as the caller does not have `WRITE` permission at the Thing level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/messageTooLarge'
      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. In order to send a message, the user needs `WRITE` permission
        at the Thing level.

        The HTTP request 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.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/thingIdPathParam'
        - $ref: '#/components/parameters/featureIdPathPathParam'
        - $ref: '#/components/parameters/messageSubjectPathParam'
        - $ref: '#/components/parameters/messageTimeoutParam'
      responses:
        '202':
          description: The message was sent (fire and forget).
        '400':
          description: |-
            The request could not be completed. The `thingId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)

            Or at least one of the defined path 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'
        '403':
          description: |-
            The request could not be completed as the caller does not have `WRITE` permission at the Thing level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedError'
        '413':
          $ref: '#/components/responses/messageTooLarge'
      requestBody:
        $ref: '#/components/requestBodies/Payload'
  /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 there are returned all things which the logged
        in user is allowed to read. The resource supports sorting
        and paging. If paging is not explicitly specified by means of the `limit`
        option, a default count of `25` documents is returned.

        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:
        - name: option
          in: query
          description: "Possible values for the parameter:\n###### sort operations\n* ```sort([+|-]{property})``` \n* ```sort([+|-]{property},[+|-]{property},...)```\n\n###### paging operations\n* ```limit({offset},{count})```  default is ```limit(0,25)```, maximum allowed count is `200`\n\n##### Examples:\n* ```sort(+thingId)```\n* ```sort(-attributes/manufacturer)```\n* ```sort(+thingId,-attributes/manufacturer)```\n* ```limit(0,10)``` return the first ten results \n* ```limit(10,10)```  return the next ten results\n\n##### Combine:\n\n 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. \n\n ```limit(0,200),sort(+thingId)```\n"
          required: false
          schema:
            type: array
            items:
              type: string
        - $ref: '#/components/parameters/thingFieldsQueryParam'

      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 was 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'

      tags:
        - Things-Search
      responses:
        '200':
          description: A number indicating the amount of matched things
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultThingsCount'
        '400':
          description: The request could not be completed. A provided parameter was 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'

components:
  requestBodies:
    Attributes:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Attributes'
          example: {}
      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 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\-]*
          * an empty object: `{}`
      required: true
    AclEntry:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AclEntry'
          example:
            {
              "READ": true,
              "WRITE": true,
              "ADMINISTRATE": true
            }
      description: |-
        JSON representation of the Access Control List (ACL) entry for a single
        authorization subject
      required: true
    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
  securitySchemes:
    basicAuth:
      type: http
      description: |-
        Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        A JSON Web Token issued by a supported OAuth 2.0 Identity Provider, e.g. a Google "id_token"
  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.
    FeatureDefinition:
      type: array
      items:
        $ref: '#/components/schemas/FeatureDefinitionString'
    FeatureDefinitionString:
      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.
    Feature:
      type: object
      properties:
        definition:
          $ref: '#/components/schemas/FeatureDefinition'
          description: The Definition of this Feature
        properties:
          $ref: '#/components/schemas/FeatureProperties'
          description: The Properties of this Feature
    SearchResultThings:
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Thing'
        nextPageOffset:
          type: integer
    SearchResultThingsCount:
      type: integer
    NewThing:
      type: object
      properties:
        acl:
          $ref: '#/components/schemas/Acl'
          description: The Access Control List of this Thing containing one AclEntry for each
        attributes:
          $ref: '#/components/schemas/Attributes'
          description: The attributes of this Thing
        features:
          $ref: '#/components/schemas/Features'
          description: The Features of this Thing
    Thing:
      type: object
      required:
        - thingId
        - acl
        - attributes
        - features
      properties:
        thingId:
          type: string
          description: |-
            Unique identifier representing the Thing - has to:

              * contain the mandatory namespace prefix (java package notation + `:` colon) - periods (`.`) may be used in namespace but not as first or last character
              * conform to RFC-2396 (URI)
        acl:
          $ref: '#/components/schemas/Acl'
          description: The Access Control List of this Thing containing one AclEntry for each arbitrary `authorizationSubject` key
        attributes:
          $ref: '#/components/schemas/Attributes'
          description: The attributes of this Thing
        features:
          $ref: '#/components/schemas/Features'
          description: The Features of this Thing
    Acl:
      type: object
      description: Access Control List containing one AclEntry for each arbitrary `authorizationSubject` key
      properties:
      additionalProperties:
        $ref: '#/components/schemas/AclEntry'
    AclEntry:
      type: object
      description: Single Access Control List entry containing the permissions (READ, WRITE, ADMINISTRATE) for the Authorization Subject.
      required:
        - READ
        - WRITE
        - ADMINISTRATE
      properties:
        READ:
          type: boolean
          description: Whether the Authorization Subject has permissions to read this entity
        WRITE:
          type: boolean
          description: Whether the Authorization Subject has permissions to modify this entity
        ADMINISTRATE:
          type: boolean
          description: Whether the Authorization Subject has permissions to modify this entity's Access Control List
    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.
      properties:
      additionalProperties:
        $ref: '#/components/schemas/Feature'
  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'
    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, when 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:
    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
    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
    featureIdPathPathParam:
      name: featureId
      in: path
      description: The ID of the Feature - has to conform to RFC-2396 (URI)
      required: true
      schema:
        type: string
    attributePathPathParam:
      name: attributePath
      in: path
      description: The path to the Attribute
      required: true
      schema:
        type: string
    thingIdPathParam:
      name: thingId
      in: path
      description: |-
        The ID of the Thing - has to:

          * contain the mandatory namespace prefix (java package notation + `:` colon)
          * conform to RFC-2396 (URI)
      required: true
      schema:
        type: string
    messageSubjectPathParam:
      name: messageSubject
      in: path
      description: The subject of the Message - has to conform to RFC-2396 (URI)
      required: true
      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
    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
    authorizationSubjectPathParam:
      name: authorizationSubject
      in: path
      description: The subject for authorization (e.g. a user id) inside an ACL
      required: true
      schema:
        type: string
    propertyPathPathParam:
      name: propertyPath
      in: path
      description: The path to the Property
      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`

        * `acl`

        * `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/make` would select only `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=attributes(model,make)` would select only `model` and `make` attribute values (if present)
               * `?fields=attributes(location/longitude)` would select the `longitude` value inside the `location` 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.

        * `_modified`

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

        #### Examples

        * `?fields=thingId,attributes,features`

        * `?fields=attributes(model,make),features`

        * `?fields=thingId,attributes/location/longitude,attributes/address(city,street)`

      required: false
      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 only `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
    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
    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
    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
    searchFilter:
      name: filter
      in: query
      description: |-
        Possible values for the parameter:

        ##### Filter operations

        * ```eq({property},{value})```

        * ```ne({property},{value})```

        * ```gt({property},{value})```

        * ```ge({property},{value})```

        * ```lt({property},{value})```

        * ```le({property},{value})```

        * ```in({property},{value},{value},...)```

        * ```like({property},{value})```

        * ```exists({property})```


        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 have the `owner` attribute.


        ##### logical operations

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

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

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


        ##### Examples

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

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

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

        * ```or(eq(attributes/location,"kitchen"),eq(attributes/location,"living-room"))```
      required: false
      schema:
        type: string
    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. When this parameter is omitted, all namespaces will be queried.


        #### Examples:

        * `?namespaces=com.example.namespace`

        * `?namespaces=com.example.namespace1,com.example.namespace2`
      required: false
      schema:
        type: string