ditto-api-2.yml

# Copyright (c) 2017 Bosch Software Innovations GmbH.
#
# All rights reserved. This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/org/documents/epl-2.0/index.php
#
# Contributors:
#    Bosch Software Innovations GmbH - initial contribution
swagger: "2.0"
info:
  title: Eclipse Ditto HTTP API
  description: JSON-based, REST-like API for Eclipse Ditto
  version: "2"
schemes:
  - http
  - https
basePath: /api/2
tags:
  - name: Things
    description: Manage every Thing
  - name: Features
    description: Structure the Features of your Things
  - name: Policies
    description: Control access to your Things
  - name: Search
    description: Find every Thing
  - name: Messages
    description: Talk with your Things
securityDefinitions:
  Google:
    type: oauth2
    description: Allow Eclipse Ditto to access your Google-ID.
    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
    tokenUrl: /oauth2/google/token
    x-tokenName: id_token
    flow: accessCode
    scopes:
      openid: Access your Google-ID

produces:
  - application/json
consumes:
  - application/json
security:
  - Google: [openid]

paths:
###
### Things
###
  /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.
      tags:
        - Things
      parameters:
        - name: ids
          in: query
          description: >-
            Contains a comma separated list of `thingId`s to retrieve in one single request.
          required: true
          type: string
        - $ref: '#/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`.
          schema:
            type: array
            items:
              $ref: '#/definitions/Thing'
        '400':
          description: >-
            The request could not be completed. At least one of the defined query parameters was invalid.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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 an
        "empty" namespace. Any `thingId` specified in the request body is
        therefore ignored. The Policy must include at least one entry with
        `WRITE` permission on the `policy:/` resource. If no Policy is provided,
        a default Policy will be created which grants all permissions to the
        authorized subject on the root thing and policy resource.
      tags:
        - Things
      parameters:
        - name: thing
          in: body
          description: JSON representation of the Thing to be created.
          required: false
          schema:
            $ref: '#/definitions/NewThing'
      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>".
              type: string
            Location:
              description: The location of the created Thing resource
              type: string
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/things/{thingId}':
    get:
      summary: Retrieve a specific Thing
      description: >-
        Returns the Thing identified by the `thingId` path parameter. The
        response includes details about the Thing. Note that the Thing's Policy
        is not included in the response per default. Optionally you can use
        field selectors (see parameter `fields`) to only get the specified
        fields. E.g., you can get the Thing's Policy by using a field selector.
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/thingFieldsQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned the specific Thing.
          schema:
            $ref: '#/definitions/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>".
              type: string
        '304':
          $ref: '#/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was
            not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or update a Thing
      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 Policy must include at least one entry with `WRITE` permission on
        the `policy:/` resource. If no Policy is provided, a default Policy will
        be created which grants all permissions to the authorized subject on the
        root thing and policy resource.

        ### Permissions for updating an existing Thing

        For updating an existing Thing the authorized subject has to have an
        unrestricted `WRITE` permission on the Thing's root resource.

        ### Partially updating an existing Thing

        When updating an existing Thing already containing `attributes`, `policyId` 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",
          "policyId": "namespace:policy-name",
          "attributes": {
            "foo": 1
          },
          "features": {...}
        }

        ```

        The Thing's `attributes` may be modified without having to pass the `policyId` 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 `policyId` and `features` of the Thing will not be overwritten, the Thing will be merged as one would expect it:

        ```

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

        ```
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - name: thing
          in: body
          description: JSON representation of the Thing to be modified.
          required: false
          schema:
            $ref: '#/definitions/NewThing'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
            Location:
              description: The location of the created Thing resource
              type: string
          schema:
            $ref: '#/definitions/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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying an existing Thing an unrestricted `WRITE` permission on the Thing's root resource is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    delete:
      summary: Delete a specific Thing
      description: >-
        Deletes the Thing identified by the `thingId` path parameter. This will not delete the Policy used for
        controlling access to this Thing managed by resource `/policies/{policyId}`.
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting an existing Thing an unrestricted `WRITE` permission on the Thing's root resource is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was
            not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/things/{thingId}/policyId':
    get:
      summary: Retrieve the Policy ID of a Thing
      description: >-
        Returns the Policy ID of the Thing identified by the `thingId` path parameter.
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned the Policy ID.
          schema:
            type: string
          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>".
              type: string
        '304':
          $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or update the Policy ID of a Thing
      description: >-
        Create or update the Policy ID of the Thing identified by the `thingId` path parameter. If the Thing had not
        yet a `policyId` set it was considered to be in API version 1, access controlled by the `acl` mechanism.
        In that case PUTing a `policyId` will create the Policy ID.
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - name: policyId
          in: body
          description: >-
            The Policy ID (as JSON String) used for controlling access to this Thing. Managed by resource
            `/policies/{policyId}`.

              * 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)
          schema:
            type: string
            example: "any.namespace:any.policy"
          required: true
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: >-
            The Policy ID was successfully created - the Thing was migrated to API version 2.
          schema:
            type: string
          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>".
              type: string
        '204':
          description: The Policy ID was successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/attributesFieldsQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The Attributes of the specific Thing were successfully retrieved.
          schema:
            $ref: '#/definitions/Attributes'
          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>".
              type: string
        '304':
          $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - name: attributes
          in: body
          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
          schema:
            $ref: '#/definitions/Attributes'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Attributes were successfully created.
          schema:
            $ref: '#/definitions/Attributes'
          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>".
              type: string
            Location:
              description: The location of the created Attributes resource
              type: string
        '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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying the Attributes of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting all Attributes of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID or its Attributes were not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/things/{thingId}/attributes/{attributePath}':
    get:
      summary: Retrieve a specific Attribute of a specific Thing
      description: >-
        Returns a specific Attribute of the Thing identified by the `thingId` path parameter. The Attribute (JSON)
        can be referenced hierarchically by applying JSON Pointer notation (RFC-6901), e.g.:
        `/things/{thingId}/attributes/address/city` in order to retrieve the `city` field of an `address` object.
      tags:
        - Things
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/attributePathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
        '304':
          $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/attributePathPathParam'
        - $ref: '#/parameters/attributeAndPropertyBodyParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
            Location:
              description: The location of the created Attribute resource
              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>".
              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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a single Attribute of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/attributePathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting a single Attribute of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
###
### Features
###
  '/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featuresFieldsQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The list of Features of the specific Thing were successfully retrieved.
          schema:
            $ref: '#/definitions/Features'
          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>".
              type: string
        '304':
          $ref: '#/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - name: features
          in: body
          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
          schema:
            $ref: '#/definitions/Features'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Features were successfully created.
          schema:
            $ref: '#/definitions/Features'
          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>".
              type: string
            Location:
              description: The location of the created Features resource
              type: string
        '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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying all features of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting all features of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/featureFieldsQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The Feature was successfully retrieved.
          schema:
            $ref: '#/definitions/Feature'
          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>".
              type: string
        '304':
          $ref: '#/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
        - name: feature
          in: body
          description: >-
            JSON representation of the Feature to be created/modified. It can also be `null` or an empty object `{}`.
          required: true
          schema:
            $ref: '#/definitions/Feature'
      responses:
        '201':
          description: The Feature was successfully created.
          schema:
            $ref: '#/definitions/Feature'
          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>".
              type: string
            Location:
              description: The location of the created Feature resource
              type: string
        '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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a single feature of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting a single feature of an existing Thing `WRITE` permission is required.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The Definition was successfully retrieved.
          schema:
            $ref: '#/definitions/FeatureDefinition'
          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>".
              type: string
        '304':
          $ref: '#/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - name: definition
          in: body
          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
          schema:
            $ref: '#/definitions/FeatureDefinition'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Definition was successfully created.
          schema:
            $ref: '#/definitions/FeatureDefinition'
          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>".
              type: string
            Location:
              description: The location of the created Definition resource
              type: string
        '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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing or the Feature with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/propertiesFieldsQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
        '304':
          $ref: '#/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - name: properties
          in: body
          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
          schema:
            $ref: '#/definitions/FeatureProperties'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
        '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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying the Properties of an existing Feature `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing or the Feature with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting the Properties of an existing Feature `WRITE` permission is required.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/propertyPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              type: string
        '304':
          $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/propertyPathPathParam'
        - $ref: '#/parameters/attributeAndPropertyBodyParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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>".
              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>".
              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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                  For creating/updating a Property of an existing Feature `WRITE` permission is required.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Thing or the Feature with the given ID was not found.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    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: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/propertyPathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/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)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
###
### Messages
###
  '/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
      consumes:
        - application/json
        - application/octet-stream
        - text/plain
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/messageClaimTimeoutParam'
        - $ref: '#/parameters/messagePayloadParam'
      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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '429':
          description: >-
            The user has sent too many requests in a given amount of time ("rate limiting").
          schema:
            $ref: '#/definitions/AdvancedError'
  '/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
      consumes:
        - application/json
        - application/octet-stream
        - text/plain
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/messageSubjectPathParam'
        - $ref: '#/parameters/messageTimeoutParam'
        - $ref: '#/parameters/messagePayloadParam'
      responses:
        '202':
          description: >-
            The message was sent but not necessarily received by the Thing (fire and forget).
        '400':
          description: |-
            The request could not be completed. 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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller does not have `WRITE` permission on the resource message:/inbox/messages/`messageSubject`.
          schema:
            $ref: '#/definitions/AdvancedError'
  '/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
      consumes:
        - application/json
        - application/octet-stream
        - text/plain
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/messageSubjectPathParam'
        - $ref: '#/parameters/messageTimeoutParam'
        - $ref: '#/parameters/messagePayloadParam'
      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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller does not have `WRITE` permission on the resource message:/outbox/messages/`messageSubject`.
          schema:
            $ref: '#/definitions/AdvancedError'
  '/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
      consumes:
        - application/json
        - application/octet-stream
        - text/plain
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/messageSubjectPathParam'
        - $ref: '#/parameters/messageTimeoutParam'
        - $ref: '#/parameters/messagePayloadParam'
      responses:
        '202':
          description: >-
            The message was sent but not necessarily received by the Feature (fire and forget).
        '400':
          description: |-
            The request could not be completed. 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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller does not have `WRITE` permission on the resource message:/features/`featureId`/inbox/messages/`messageSubject`.
          schema:
            $ref: '#/definitions/AdvancedError'
  '/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
      consumes:
        - application/json
        - application/octet-stream
        - text/plain
      parameters:
        - $ref: '#/parameters/thingIdPathParam'
        - $ref: '#/parameters/featureIdPathPathParam'
        - $ref: '#/parameters/messageSubjectPathParam'
        - $ref: '#/parameters/messageTimeoutParam'
        - $ref: '#/parameters/messagePayloadParam'
      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.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller does not have `WRITE` permission on the resource message:/features/`featureId`/outbox/messages/`messageSubject`.
          schema:
            $ref: '#/definitions/AdvancedError'
###
### Policies
###
  '/policies/{policyId}':
    get:
      summary: Retrieve a specific Policy
      description: >-
        Returns the Policy identified by the `policyId` path parameter. The response contains the Policy as JSON
        object consisting of Policy
        Entries.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The request successfully returned completed and returned is the Policy.
          schema:
            $ref: '#/definitions/Policy'
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or update a Policy
      description: Modify the complete Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - name: policy
          in: body
          description: >-
            JSON representation of the Policy.


            Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
          required: true
          schema:
            $ref: '#/definitions/Policy'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Policy was successfully created.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
            Location:
              description: The location of the created Policy resource
              type: string
          schema:
            $ref: '#/definitions/Policy'
        '204':
          description: The Policy was successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Policy JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a complete Policy, `WRITE` permission on the resource `policy:/` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    delete:
      summary: Delete a specific Policy
      description: >-
        Deletes the Policy identified by the `policyId` path parameter. Deleting a Policy does not implicitly delete
        other entities (e.g. Things) which use this Policy. Those have to be deleted in advance of deleting the Policy.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Policy was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Policy JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting an existing Policy, `WRITE` permission on the resource `policy:/` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries':
    get:
      summary: Retrieve the entries of a specific Policy
      description: >-
        Returns the Policy entries of the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The request successfully returned completed and returned are the Policy entries.
          schema:
            $ref: '#/definitions/PolicyEntries'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Modify the entries of a specific Policy
      description: >-
        Modify the Policy entries of the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - name: policyEntries
          in: body
          description: >-
            JSON representation of the Policy entries.


            Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
          required: true
          schema:
            $ref: '#/definitions/PolicyEntries'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Policy entries were successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Policy entry JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying the Policy entries of an existing Policy, `WRITE` permission on the resource `policy:/entries` is required is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries/{label}':
    get:
      summary: Retrieve one Policy entry of a Policy for a specific label
      description: >-
        Returns one Policy entry of the Policy identified by the `policyId` path parameter and for the label
        identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The request successfully returned completed and returned is the Policy entry.
          schema:
            $ref: '#/definitions/PolicyEntry'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated
            user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or modify one Policy entry of a Policy for a specific label
      description: >-
        Create or modify the Policy entry of the Policy identified by the `policyId` path parameter and with the
        label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - name: policyEntry
          in: body
          description: >-
            JSON representation of the Policy entry.


            Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
          required: true
          schema:
            $ref: '#/definitions/PolicyEntry'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Policy entry was successfully created.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
            Location:
              description: The location of the created Policy entry
              type: string
          schema:
            $ref: '#/definitions/PolicyEntry'
        '204':
          description: The Policy entry was successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Policy entry JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a Policy entry of an existing Policy, `WRITE` permission on the resource `policy:/entries/{label}` is required is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    delete:
      summary: Delete one Policy entry of a Policy for a specific label
      description: >-
        Deletes the Policy entry of the Policy identified by the `policyId` path parameter and with the label
        identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Policy entry was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting a Policy entry of an existing Policy, `WRITE` permission on the resource `policy:/entries/{label}` is required is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries/{label}/subjects':
    get:
      summary: Retrieve all Subjects of a Policy entry
      description: >-
        Returns all Subjects of the Policy entry of the Policy identified by the `policyId` path parameter and for
        the label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned. The subjects are returned.
          schema:
            $ref: '#/definitions/Subjects'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or modify all Subjects of a Policy Entry
      description: >-
        Create or modify all Subjects of the Policy entry of the Policy identified by the `policyId` path parameter
        and with the label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - name: subjects
          in: body
          description: >-
            JSON representation of the Subjects.


            Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
          required: true
          schema:
            $ref: '#/definitions/Subjects'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Subjects were successfully created or updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Subjects JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying Subjects of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/subjects` is required is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID was not found in the context of the
            authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries/{label}/subjects/{subjectId}':
    get:
      summary: Retrieve one specific Subject of a Policy entry
      description: >-
        Returns the Subject with ID `subjectId` of the Policy entry identified by the `label` path parameter
        belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/subjectIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The request successfully returned completed and returned is the Subject.
          schema:
            $ref: '#/definitions/SubjectEntry'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID, the Policy entry or the Subject was not
             found in the context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or modify one specific Subject of a Policy entry
      description: >-
        Create or modify the Subject with ID `subjectId` of the Policy entry identified by the `label` path parameter
         belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/subjectIdPathParam'
        - name: subject
          in: body
          description: JSON representation of the Subject
          required: true
          schema:
            $ref: '#/definitions/SubjectEntry'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Subject was successfully created.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
            Location:
              description: The location of the created Subject
              type: string
          schema:
            $ref: '#/definitions/SubjectEntry'
        '204':
          description: The Subject was successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Subject JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a Subject of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/subjects/{subjectId}` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    delete:
      summary: Delete one specific Subject of a Policy entry
      description: >-
        Deletes the Subject with ID `subjectId` of the Policy entry identified by the `label` path parameter
        belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/subjectIdPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Subject was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting a Subject of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/subjects/{subjectId}` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID, the Policy entry or the Subject was not
             found in the context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries/{label}/resources':
    get:
      summary: Retrieve all Resources of a Policy entry
      description: >-
        Returns all Resources of the Policy entry of the Policy identified by the `policyId` path parameter and for
        the label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: The request successfully returned. The resources are returned.
          schema:
            $ref: '#/definitions/Resources'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or modify all Resources of a Policy Entry
      description: >-
        Create or modify all Resources of the Policy entry of the Policy identified by the `policyId` path parameter
        and with the label identified by the `label` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - name: resources
          in: body
          description: JSON representation of the Resources
          required: true
          schema:
            $ref: '#/definitions/Resources'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Resources were successfully created or updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Resources JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying Resources of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/resources` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
  '/policies/{policyId}/entries/{label}/resources/{resourcePath}':
    get:
      summary: Retrieve one specific Resource of a Policy entry
      description: >-
        Returns the Resource with path `resourcePath` of the Policy entry identified by the `label` path parameter
        belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/resourcePathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: >-
            The request successfully returned completed and returned is the Resource.
          schema:
            $ref: '#/definitions/ResourceEntry'
          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>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID, the Policy entry or the Resource was
            not found in the context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    put:
      summary: Create or modify one specific Resource of a Policy entry
      description: >-
        Create or modify the Resource with path `resourcePath` of the Policy entry identified by the `label` path
        parameter belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/resourcePathPathParam'
        - name: resource
          in: body
          description: JSON representation of the Resource
          required: true
          schema:
            $ref: '#/definitions/ResourceEntry'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '201':
          description: The Resource was successfully created.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
            Location:
              description: The location of the created Resource
              type: string
          schema:
            $ref: '#/definitions/ResourceEntry'
        '204':
          description: The Resource was successfully updated.
          headers:
            ETag:
              description: >-
                The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
                "rev:<revision>", for sub-resources it has the format "hash:<calculated-hash>".
              type: string
        '304':
          $ref: '#/responses/notModified'
        '400':
          description: |-
            The request could not be completed. The `policyId` 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 Resource JSON object.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For modifying a Resource of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/resources/{resourcePath}` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID or the Policy entry was not found in the
             context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
    delete:
      summary: Delete one Resource of a Policy entry
      description: >-
        Deletes the Resource with path `resourcePath` of the Policy entry identified by the `label` path parameter
        belonging to the Policy identified by the `policyId` path parameter.
      tags:
        - Policies
      parameters:
        - $ref: '#/parameters/policyIdPathParam'
        - $ref: '#/parameters/labelPathParam'
        - $ref: '#/parameters/resourcePathPathParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '204':
          description: The Resource was successfully deleted.
        '400':
          description: |-
            The request could not be completed. The `policyId` either

              * does not contain the mandatory namespace prefix (java package notation + `:` colon)
              * does not conform to RFC-2396 (URI)
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: |-
            The request could not be completed. Either
              * as the caller had insufficient permissions.
                For deleting a Resource of an existing Policy entry, `WRITE` permission on the resource `policy:/entries/{label}/resources/{resourcePath}` is required without having any revoke.
          schema:
            $ref: '#/definitions/AdvancedError'
        '404':
          description: >-
            The request could not be completed. The Policy with the given ID, the Policy entry or the Resource was
            not found in the context of the authenticated user.
          schema:
            $ref: '#/definitions/AdvancedError'
        '412':
          $ref: '#/responses/preconditionFailed'
###
### Search
###
  /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")```



        There can also be searched for feature properties using the following syntax:



        ``eq(features/*/properties/temperature,38)``


        The '*' indicates that there is searched on all available features for a property named 'temperature'.



        Attention, at the moment we do not support search on array fields.


        The search result can be limited to the Things within a namespace (or namespaces) given in the `namespaces`
        parameter.

      parameters:
        - $ref: '#/parameters/searchFilter'
        - $ref: '#/parameters/namespacesFilter'
        - name: option
          in: query
          description: >-

            ##### Sort operations:


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

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


            ##### Paging operations:


            * ```limit({offset},{count})```  default is ```limit(0,25)```,
            maximum allowed count is `200`


            Note: We recommend not to use high offsets (e. g., higher than 10,000) for paging because of potential
            performance degradations.


            ##### Examples:


            * ```sort(+thingId)```

            * ```sort(-attributes/manufacturer)```

            * ```sort(+thingId,-attributes/manufacturer)```

            * ```limit(0,10)``` return the first ten results

            * ```limit(10,10)```  return the next ten results


            ##### Combining options:


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


             ```limit(0,200),sort(+thingId)```
          required: false
          type: array
          items:
            type: string
        - $ref: '#/parameters/thingFieldsQueryParam'
      tags:
        - Search
      responses:
        '200':
          description: An array of the matching things.
          schema:
            $ref: '#/definitions/SearchResultThings'
        '400':
          description: >-
            The request could not be completed. A provided parameter was in a
            wrong format.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: The request could not be completed due to an invalid authentication.
          schema:
            $ref: '#/definitions/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")```



        There can also be searched for feature properties using the following syntax:



        ``eq(features/*/properties/temperature,38)``


        The '*' indicates that there is searched on all available features for a property named 'temperature'.



        Attention, at the moment we do not support search on array fields.


        The search result can be limited to the Things within a namespace (or namespaces) given in the `namespaces`
        parameter.

      parameters:
        - $ref: '#/parameters/searchFilter'
        - $ref: '#/parameters/namespacesFilter'
      tags:
        - Search
      responses:
        '200':
          description: A number indicating the amount of matched things
          schema:
            $ref: '#/definitions/SearchResultThingsCount'
        '400':
          description: >-
            The request could not be completed. A provided parameter was in a wrong format.
          schema:
            $ref: '#/definitions/AdvancedError'
        '401':
          description: The request could not be completed due to missing authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
        '403':
          description: The request could not be completed due to an invalid authentication.
          schema:
            $ref: '#/definitions/AdvancedError'
definitions:
  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
    minItems: 1
    uniqueItems: true
    items:
      type: string
      description: "A single fully qualified identifier of a Feature Definition in the form 'namespace:name:version'"
      pattern: (?<namespace>[_a-zA-Z0-9\-.]+):(?<name>[_a-zA-Z0-9\-.]+):(?<version>[_a-zA-Z0-9\-.]+)
  FeatureProperties:
    type: object
    description: An arbitrary JSON object.
  Feature:
    type: object
    properties:
      definition:
        $ref: '#/definitions/FeatureDefinition'
        description: The Definition of this Feature
      properties:
        $ref: '#/definitions/FeatureProperties'
        description: The Properties of this Feature
  SearchResultThings:
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/Thing'
      nextPageOffset:
        type: integer
  SearchResultThingsCount:
    type: integer
  NewThing:
    type: object
    properties:
      _policy:
        $ref: '#/definitions/Policy'
        description: >-
          The initial Policy to create for this Thing. This will create a separate Policy entity managed by resource `/policies/{thingId}`.


          Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
      policyId:
        type: string
        description: >-
          The Policy ID used for controlling access to this Thing. Managed by resource `/policies/{policyId}`.
      attributes:
        $ref: '#/definitions/Attributes'
        description: The attributes of this Thing
      features:
        $ref: '#/definitions/Features'
        description: The Features of this Thing
  Thing:
    type: object
    required:
      - thingId
      - policyId
      - attributes
      - features
    properties:
      thingId:
        type: string
        description: Unique identifier representing the thing
      policyId:
        type: string
        description: The policy ID used for controlling access to this thing, managed by resource `/policies/{policyId}`
      attributes:
        $ref: '#/definitions/Attributes'
        description: The attributes of this thing
      features:
        $ref: '#/definitions/Features'
        description: The features of this thing
  Policy:
    type: object
    description: Policy consisting of PolicyEntries
    properties:
      entries:
        $ref: '#/definitions/PolicyEntries'
  PolicyEntries:
    type: object
    description: PolicyEntries containing one PolicyEntry for each arbitrary `label` key
    properties:
      label1:
        $ref: '#/definitions/PolicyEntry'
      labelN:
        $ref: '#/definitions/PolicyEntry'
  PolicyEntry:
    type: object
    description: Single Policy entry containing Subjects and Resources.
    required:
      - subjects
      - resources
    properties:
      subjects:
        $ref: '#/definitions/Subjects'
      resources:
        $ref: '#/definitions/Resources'
  Subjects:
    type: object
    description: >-
      (Authorization) Subjects containing one SubjectEntry for each arbitrary `issuer:subjectId` key. `issuer` being
      one of the following `https://accounts.google.com`
    properties:
      'https://accounts.google.com:subjectId1':
        $ref: '#/definitions/SubjectEntry'
  SubjectEntry:
    type: object
    description: Single (Authorization) Subject entry holding its type.
    required:
      - type
    properties:
      type:
        type: string
        description: the type of the (Authorization) Subject
        enum:
          - jwt
  Resources:
    type: object
    description: >-
      (Authorization) Resources containing one ResourceEntry for each `type:path` key, `type` being one of the
      following `thing`, `policy`, `message`
    properties:
      'thing:/':
        $ref: '#/definitions/ResourceEntry'
      'thing:/attributes/some/path':
        $ref: '#/definitions/ResourceEntryRestricted'
      'policy:/':
        $ref: '#/definitions/ResourceEntry'
      'message:/':
        $ref: '#/definitions/ResourceEntry'
  ResourceEntry:
    type: object
    description: >-
      Single (Authorization) Resource entry defining permissions per effect. Allowed effects are `grant` and `revoke`.
    properties:
      grant:
        type: array
        items:
          $ref: '#/definitions/Permission'
      revoke:
        type: array
        items:
          $ref: '#/definitions/Permission'
  ResourceEntryRestricted:
    type: object
    description: >-
      Single (Authorization) Resource entry defining permissions per effect. Allowed effects are `grant` and `revoke`.
    properties:
      grant:
        type: array
        items:
          $ref: '#/definitions/Permission'
      revoke:
        type: array
        items:
          $ref: '#/definitions/Permission'
  Permission:
    type: string
    description: A Permission allows a certain action on an entity
    enum:
      - READ
      - WRITE
  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:
      featureId1:
        $ref: '#/definitions/Feature'
      featureIdN:
        $ref: '#/definitions/Feature'
responses:
  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>".
        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>".
        type: string
    schema:
      $ref: '#/definitions/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: *`
    type: string
    required: false
  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: *`.
    type: string
    required: false
  featureIdPathPathParam:
    name: featureId
    in: path
    description: The ID of the Feature - has to conform to RFC-2396 (URI)
    type: string
    required: true
  attributePathPathParam:
    name: attributePath
    in: path
    description: The path to the Attribute
    type: string
    required: true
  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)
    type: string
    required: true
  policyIdPathParam:
    name: policyId
    in: path
    description: |-
      The ID of the Policy - has to:

        * contain the mandatory namespace prefix (java package notation + `:` colon)
        * conform to RFC-2396 (URI)
    type: string
    required: true
  messageSubjectPathParam:
    name: messageSubject
    in: path
    description: The subject of the Message - has to conform to RFC-2396 (URI)
    type: string
    required: true
  messageClaimTimeoutParam:
    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): 60 seconds. Maximum value: 600 seconds.
      A value of 0 seconds applies fire and forget semantics for the message.
    required: false
    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
    type: integer
  messagePayloadParam:
    name: payload
    in: body
    description: >-
      Payload of the message with max size of 10MB. It can be any HTTP supported content, including binary content.
    required: false
    schema:
      type: string
  labelPathParam:
    name: label
    in: path
    description: The label of a Policy entry
    type: string
    required: true
  subjectIdPathParam:
    name: subjectId
    in: path
    description: The ID of an (Authorization) Subject
    type: string
    required: true
  resourcePathPathParam:
    name: resourcePath
    in: path
    description: The path of an (Authorization) Resource
    type: string
    required: true
  propertyPathPathParam:
    name: propertyPath
    in: path
    description: The path to the Property
    type: string
    required: true
  attributeAndPropertyBodyParam:
    name: value
    in: body
    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
    schema:
      type: object
  thingFieldsQueryParam:
    name: fields
    in: query
    description: >-
      Contains a comma separated list of fields to be included in the returned JSON. Attributes can be selected in
      the same manner.

      #### Selectable fields

      * `thingId`

      * `policyId`

      * `_policy`

       Specifically selects the policy of the Thing. (The policy is not contained in the returned JSON per default.)

      * `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
    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
    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
    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
    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
    type: string
  searchFilter:
    name: filter
    in: query
    description: >-

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


      ##### Logical operations:


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

      * ```or({query},{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
    type: string
  namespacesFilter:
    name: namespaces
    in: query
    type: string
    description: >-
      A comma separated list of namespaces. This list is used to limit the query reach to things in the given
      namespaces only. When this parameter is omitted, all namespaces will be selected.

      #### Examples:

      * `?namespaces=com.example.namespace`

      * `?namespaces=com.example.namespace1,com.example.namespace2`

    required: false