openapi: 3.0.3

info:
  title: KNX IoT 3rd Party API
  version: "1.0"
  description: |
    # Introduction
    This KNX IoT 3rd Party API offers an access at the level of the Installation 
    and supports more sophisticated queries to (history) values of installation state 
    data or specific elements of the installation, such as location, application function and datapoints.

    The motivation for the KNX IoT 3rd Party API is to offer 
    a non-KNX certified communication partner a way to integrate with a KNX Classic Installation.
  contact:
    name: KNX Association cvba
    email: support@knx.org
    x-compatible-knx-ontologies:
      - name: v1
        url: http://schema.knx.org/2020/ontology/v1

servers:
    
  - url: "{protocol}://{authority}/{path}"
    variables:
      protocol:
        description: protocol selection (may depend from WAN/LAN network environment)
        enum: [https,http]
        default: https
      authority:
        description: corresponds to the host or service name of the KNX IoT 3rd Party API interface
        default: gateway.knx.local
      path:
        description: corresponds to the URL base part of the KNX IoT 3rd Party API endpoints
        default: api/v1

tags:
  - name: authorization
    description: Endpoints involved in the authorization process.
  - name: datapoint
    description: Endpoints exposing datapoints to the clients.
  - name: device
    description: Endpoints exposing devices to the clients.
  - name: function
    description: Endpoints exposing functions to the clients.
  - name: information
    description: Endpoints containing information from the node (server) and hosted installation.
  - name: location
    description: Endpoints exposing the location structure to clients.
  - name: subscription
    description: Endpoints handling subscriptions.

paths:
  /.well-known/knx:
    get:
      summary: Get version and entry point information.
      description: |
        # General
        Get information on the supported API versions from this node. Additionally, how to access 
        the installation root entry points.

        # Details
        The endpoint MUST not secured with any authorization or token. It is used to discover the API server.   

        # Notes
        ## Implementation Details
        - The URL MUST not contain any API base path element. 
        - The version member value MUST contain only a major and minor number according 
          to the format major.minor, represented as a string. 
        - The major number starts from value 1, the minor number starts with value 0.
        - The version element does not follow the JSON API version element (version : {api:2.0})
      servers:
        - url: "{protocol}://{authority}"
          variables:
            protocol:
              description: protocol selection (may depend from WAN/LAN network environment)
              enum: [https,http]
              default: https
            authority:
              description: corresponds to the host or service name of the KNX IoT 3rd Party API interface
              default: gateway.knx.local
      tags:
        - information
      operationId: getWellKnownCore
      responses:
        "200":
          $ref: "#/components/responses/WellKnown200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security: []     

  /oauth/access:
    post:
      summary: Handles access token management.
      description: |
        # General
        An authenticated client/user can use this endpoint to manage an access token:
        1. to initially retrieve an access token 
        2. to refresh an (existing) access token

        # Details
        Two security schemes are specified in this OpenAPI file.
        - OAuth2 (RFC 6749)
        - bearer (RFC 6750)     
        
        Access to all endpoints except the below enumerated endpoints must be authorized. 
        - /oauth/access (this - OAuth2 - access token endpoint)
        - /.well-known/knx (node discovery) 
        
        This endpoint is used to negotiate an access token with the server. How a client/user gets authenticated (OAuth2 authorization) 
        is out of scope for this API (only the OAuth2 authorization URL is specified, see API security schemes).   
        
        ## Security Methods
        To access a (protected) resource at the resource server each endpoint has its security setting that defines the intended 
        (OAuth2) access scopes, specified as part of the OAuth2 security scheme. 
        
        - From this **token** endpoint retrieved access tokens are bound to the permission granted by the defined access scope.
        - The token _type_ is specified as a `bearer` token, format is string, no further explicit meaning such as on a JWT. 
               
        ## Workflow
        **STEP 1**
        
        A client gets an (OAuth2) access token from this endpoint. 
        
        **STEP 2**

        Each time the client accesses a resource (from the resource server) it uses the above retrieved (OAuth2) access token 
        as an `bearer` token, included in the HTTP request authorization header. 
        - _Bearer Token Usage_, RFC 6750, clause 2.1
        - MUST be used together with TLS/HTTPS 
        
        As an important note, the _Authorization_ header parameter is NOT explicitly specified per resource server endpoint in this API. 
        
        # Notes
        For the clarity of this OpenAPI specification, both above described security schemes are explicitly (AND) assigned
        to the (to be secured) resource server endpoints. 
        
        OpenAPI claims that in such a (AND'ed) case both security schemes must be used **simultaneously** in **one** request. 
        For the here chosen security schemes this is not possible (two separate EPs and a step 1/2 independent workflow).
      tags:
        - authorization
      operationId: getOauthToken
      requestBody:
        description: |
          As described in clause **General** above the endpoint supports two scenarios.
          ### retrieve access token
          It returns an access token, following parameters are mandatory:
          - grant_type (`authorization_code`)
          - code
          - redirect_uri   
        
          ### refresh access token 
          It returns an new (refreshed) access token and MAY return in addition an new refresh token, 
          following parameters are mandatory:
          - grant_type (`refresh_token`)
          - refresh_token
          
          According to RFC clause 6 the _scope_ is optional, even on vendor specific defined (additional) scopes 
          it SHOULD not be included here.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: "#/components/schemas/oAuth2AccessToken"
                - $ref: "#/components/schemas/oAuth2RefreshToken"
            examples:
              Runtime1:
                summary: Runtime (access token)
                description: An example to retrieve an access token.  
                value:
                  grant_type: authorization_code
                  code: IamAnArbitraryAuthorizationCodeString
                  redirect_uri: http://localhost:8080/client_app/cb  
              Runtime2:
                summary: Runtime (refresh token)
                description: An example to refresh an access token.  
                value:
                  grant_type: refresh_token
                  refresh_token: IamAnArbitraryRefreshTokenString    
      responses:
        "200":
          $ref: "#/components/responses/Access200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequestOAuth2"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security: []    

  /node:
    get:
      summary: Get information from node.
      description: |
        # General
        List all available information of this (server) node.

        # Details
        The node exits only with one instance.       

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: getNodeInformation
      responses:
        "200":
          $ref: "#/components/responses/Node200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:     
        - OAuth2: [read,write]
          BearerAuthentication: []
 
  /devices:
    get:
      summary: List all devices.
      description: |
        # General
        List all available devices of the installation.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.    
      tags:
        - device
      operationId: listDevices
      parameters:
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"   
      responses:
        "200":
          $ref: "#/components/responses/DeviceCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /devices/{deviceId}:
    get:
      summary: Get information from a device.
      description: |
        # General
        List all available information of a specific device.

        # Details
        NA.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - device
      operationId: getDeviceData
      parameters:
        - $ref: "#/components/parameters/deviceId"
      responses:
        "200":
          $ref: "#/components/responses/Device200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []
      
  /locations/{locationId}/devices:
    get:
      summary: List devices of a location.
      description: |
        # General
        List all available devices of a specific location.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - device
      operationId: listDevicesOfLocation
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"          
      responses:
        "200":
          $ref: "#/components/responses/DeviceCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []
 
  /installations:
    get:
      summary: List all installations.
      description: |
        # General
        List all available installations.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        All in this API specified endpoints returns data that comprises all installations contained 
        in the node. As an example, the endpoint /datapoints returns all datapoints from all installations at once.
        There is no differentiation between dp's from one or the other installation possible. 

        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: listInstallations
      parameters: 
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"       
      responses:
        "200":
          $ref: "#/components/responses/InstallationCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /installations/{installationId}:
    get:
      summary: Get information from an specific installation.
      description: |
        # General
        List all available information of a specific installation.

        # Details
        NA.        

        # Notes
        All in this API specified endpoints returns data that comprises all installations contained 
        in the node. As an example, the endpoint /datapoints returns all datapoints from all installations at once.
        There is no differentiation between dp's from one or the other installation possible. 
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: getInstallation
      parameters:
        - $ref: "#/components/parameters/installationId" 
      responses:
        "200":
          $ref: "#/components/responses/Installation200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /sites:
    get:
      summary: List root locations.
      description: |
        # General
        List all available root locations of an installation, to express an _geographical_ starting 
        point for the spatial location structure. This includes only the top level location elements.
        - starting from all available (sibling) sites (containing of subordinated buildings)
        - starting from all available (sibling) buildings (containing no superordinated site(s), but subordinated floor, rooms, ...)

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: listSites
      parameters:
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"          
      responses:
        "200":
          $ref: "#/components/responses/SiteCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /locations:
    get:
      summary: List all locations.
      description: |
        # General
        List all available locations of the installation, this includes also all root locations.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200. 
      tags:
        - location
      operationId: listLocations
      parameters:
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"                   
      responses:
        "200":
          $ref: "#/components/responses/LocationCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /locations/{locationId}:
    get:
      summary: Get information from a location.
      description: |
        # General
        List all available information of a specific location.

        # Details
        NA.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: getLocation
      parameters:
        - $ref: "#/components/parameters/locationId"
      responses:
        "200":
          $ref: "#/components/responses/Location200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []   

  /locations/{locationId}/childlocations:
    get:
      summary: List child locations.
      description: |
        # General
        List all available child locations of a specific location, including only the directly 
        subordinated sibling locations (and no further to this locations subordinated locations).

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: listChildLocations
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"         
      responses:
        "200":
          $ref: "#/components/responses/ChildLocationCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /functions:
    get:
      summary: List all functions.
      description: |
        # General
        List all available functions of the installation.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.  
      tags:
        - function
      operationId: listFunctions
      parameters:
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"           
      responses:
        "200":
          $ref: "#/components/responses/FunctionCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /functions/{functionId}:
    get:
      summary: Get information from a function.
      description: |
        # General
        List all available information of a specific function.

        # Details
        NA.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: getFunction
      parameters:
        - $ref: "#/components/parameters/functionId"         
      responses:
        "200":
          $ref: "#/components/responses/Function200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []
      
  /locations/{locationId}/functions:
    get:
      summary: List functions of a location.
      description: |
        # General
        List all available functions of a specific location.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: listFunctionsOfLocation
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"          
      responses:
        "200":
          $ref: "#/components/responses/FunctionCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []
       
  /datapoints/{datapointId}/functions:
    get:
      summary: List functions of a datapoint.
      description: |
        # General
        List all functions where a specific datapoint is included in. 

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: listFunctionsOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"  
      responses:
        "200":
          $ref: "#/components/responses/FunctionCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /datapoints:
    get:
      summary: List all datapoints.
      description: |
        # General
        List all available datapoints of the installation.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapoints
      parameters:        
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"
        
      responses:
        "200":
          $ref: "#/components/responses/DataPointCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []
        

  /datapoints/{datapointId}:
    get:
      summary: Get information from a datapoint.
      description: |
        # General
        List all available information of a specific datapoint.

        # Details
        NA.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.  

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: getDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
      responses:
        "200":
          $ref: "#/components/responses/DataPoint200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /datapoints/values:
    put:
      summary: Update datapoint values.
      description: |
        # General
        Update all in the request body specified datapoints with a new value.

        # Details
        NA.    

        # Notes
        ## Implementation Details
        Datapoint may have a numbered or an enumerated type. For both cases the server must 
        implement an error handling if 
        - a numbered type value is not representable in its range or its format
        - an enumerated type value is not part of the servers list of enumeration values   
      tags:
        - datapoint
      operationId: updateDatapoints
      requestBody:
        $ref: "#/components/requestBodies/datapointValuesPut"
      responses:
        "202":
          description: "Accepted"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "501":
          $ref: "#/components/responses/httpStatusNotImplemented"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [write]
          BearerAuthentication: []
       
  /functions/{functionId}/datapoints:
    get:
      summary: List datapoints of a function.
      description: |
        # General
        List all available datapoints of a specific function.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfFunction
      parameters:
        - $ref: "#/components/parameters/functionId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"      
      responses:
        "200":
          $ref: "#/components/responses/DataPointCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /devices/{deviceId}/datapoints:
    get:
      summary: List datapoints of a device.
      description: |
        # General
        List all available datapoints of a specific device.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.         

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfDevice
      parameters:
        - $ref: "#/components/parameters/deviceId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"       
      responses:
        "200":
          $ref: "#/components/responses/DataPointCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /datapoints/{datapointId}/subscriptions:
    get:
      summary: List subscriptions of a datapoint.
      description: |
        # General
        List all subscriptions where a specific datapoint is included in. 

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        With this access method you cannot:
        -  retrieve all to a subscription belonging (previously upon subscribed) resource items 

        A full list of the actual datapoints belonging to a subscription is resolvable via the endpoint
        subscription/{id}/datapoints.

        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships ar not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.
      tags:
        - subscription
      operationId: listSubscriptionsOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"   
      responses:
        "200":
          $ref: "#/components/responses/SubscriptionCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          BearerAuthentication: []

  /subscriptions/{subscriptionId}:
    get:
      summary: Read a HTTP callback subscription.
      description: |
        # General
        List all available information of a specific subscription.

        # Details
        NA.        

        # Notes
        With this access method you cannot:
        -  retrieve all to a subscription belonging (previously upon subscribed) resource items 

        A full list of the actual datapoints belonging to a subscription is resolvable via the endpoint
        subscription/{id}/datapoints.

        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.

        ### Relationships
        - Only for this API specified `relationships` member can be expressed. 
        - KNX vendor specific relationships or not in this API specified relationships 
          from the KNX information model MUST not be expressed and if any ignored.

        Examples, see **Runtime** example on status code 200.  
      tags:
        - subscription
      operationId: getSubscription
      parameters:
        - $ref: "#/components/parameters/subscriptionId"
      responses:
        "200":
          $ref: "#/components/responses/Subscription200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          BearerAuthentication: []
     
    delete:
      summary: Deletes a HTTP callback subscription.
      description: |
        # General
        An individual subscription will be deleted on the server. 
        # Details
        - All properties describing a subscription (url, secret, caCert, type) will be deleted. 
        - The server releases all datapoints from this subscription with **id**.
        - For this subscription **id** pending notification events will be deleted.
        - The subscription **id** is deleted. 
      operationId: deleteSubscription
      tags:
        - subscription
      parameters:
        - $ref: "#/components/parameters/subscriptionId"
      responses:
        "204":
          description: The subscription has been deleted successfully.
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          BearerAuthentication: []

    put:
      summary: Updates a HTTP callback subscription.
      description: |
        # General
        An individual subscription will be updated on the server. 
        # Details
        It must be ensured that updated/overwritten elements do not impact the current operational state.
        - url
        - secret  
        - caCert (may be expired) 
        
        # Notes
        With this access method you cannot:
        - add new (to be subscribed upon) resource items to the existing subscription
        - overwrite the current subscription type (the subscription characteristics)  

        A full reconfiguration of an (individual) subscription is only possible with 
        the deletion of the current subscription and re-creation of a new subscription.
      operationId: updateSubscription
      tags:
        - subscription
      parameters:
        - $ref: "#/components/parameters/subscriptionId"
      requestBody:
        description: |
          Subscription message data, containing of (JSON API) member:
          - `data` member -> subscription item, including: 
            - id/ type
            - an `attributes` member describing the subscription properties (url, secret, caCert)

          ### Notes 
          The current AN198 deviates from this payload definition, this will be updated in the next version of the AN. 
          In this YAML file it is specified as follows:
          
          - individual subscription items with its id/ subscription resource type (such as room, datapoint, ...) are 
            not included in the request payload (see Notes above)
          - meta member, describing the subscription type (the subscription characteristics) is not included 
               
          For the handling of not present elements in 
          the request body, see <https://jsonapi.org/format/#crud-updating-resource-attributes>
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/SubscriptionUpdate"
            examples:
              Runtime:
                $ref: "#/components/examples/SubscriptionPutExample"

      responses:
        "200":
          description: The subscription has been successfully updated.
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          BearerAuthentication: []
        
  /subscriptions/{subscriptionId}/datapoints:
    get:
      summary: List datapoints of a subscription.
      description: |
        # General
        List all available datapoints of a specific subscription.

        # Details
        It is possible to limit the number of returned items. 
        Additionally also to skip collection items before reading.        

        # Notes
        ## Implementation Details
        In case no specific information will be available as part of the JSON API `relationships`, 
        `meta` or `attributes` member, the member MUST NOT be expressed.
        ### Attributes
        - KNX vendor specific attributes MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified attributes from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        - In case a valid value is missing (such as after power up), attributes `value` and `timestamp` 
          member MUST NOT be expressed.

        ### Relations
        - KNX vendor specific relationships MUST be expressed with its (predefined) corresponding namespace.  
        - Not in this API specified relationships from the KNX information model SHOULD be expressed 
          with its corresponding object property name from the KNX information model.

        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfSubscription
      parameters:
        - $ref: "#/components/parameters/subscriptionId"
        - $ref: "#/components/parameters/collectionOffset"
        - $ref: "#/components/parameters/collectionLimit"          
      responses:
        "200":
          $ref: "#/components/responses/DataPointCollection200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [read,write]
          BearerAuthentication: []

  /subscribe:
    post:
      summary: Creates a HTTP callback subscription.
      description: |
        # General
        An individual subscription will be created at the server, as a result a subscription **id** is generated
        that belongs to all involved datapoints. 

        # Details
        The subscription **request** contains:
        1. the resource items to be subscribed upon (which is an datapoint directly or an resource that contains datapoints)
        2. the _subscription type_  (the characteristics of the subscription)
        3. the callback URL, shared secret and optional certificate

        # Notes
        The _subscription type_ from point 2 above supports two characteristics on a CoV for a datapoint.:
        1. include subordinated resources for a CoV
        2. include no subordinated resources for a CoV
         
        The request body allows to bundle an array of resource items with its possibly **different** 
        individual resource types (such as room, device or datapoint).

        A _subscription type_ specified with the subordinated characteristics (point 1) will only affect 
        resources of type location. On other resources this _subscription type_ will be handled from the 
        server as in point 2.
      tags:
        - subscription
      operationId: subscribeWithCallback
      requestBody:
        description: |
          Subscription message data, containing of (JSON API) member:
          - `data` member > collection of (to be upon subscribed) items
          - `meta` member > subscription callback data and subscription type
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/SubscribeRequest"
            examples:
              Runtime:
                $ref: "#/components/examples/SubscriptionPostExample"
      callbacks:
        datapoint_CoV_event:
          $ref: "#/components/callbacks/notificationData"
      responses:
        "200":
          description: |
            For each requested subscription resource the here affected datapoints 
            including the generated subscription id is returned. 
            The latter is part of the `datapointSubscription` member. 

            As a note, the subscription <id> MUST be unique for all resource items, 
            that need to be subscribed and are part of an individual subscription request.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/SubscribeResponse"
              examples:
                Runtime:
                  summary: Runtime
                  value:
                    data:
                      - id: 123e4567-e89b-12d3-a456-426614174000
                        type: datapoint
                        relationships:
                          datapointSubscription:
                            links:
                              related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa
                        attributes:
                          value: "-273.15"
                          timeStamp: "1920-02-17T00:17:17Z"
                      - id: 123e4567-e89b-12d3-a456-426614174001
                        type: datapoint
                        relationships:
                          datapointSubscription:
                            links:
                              related: /subscriptions/123e4567-e89b-12d3-a456-4266141740ab
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"
        "404":
          $ref: "#/components/responses/httpStatusNotFound"
        "405":
          $ref: "#/components/responses/httpStatusMethodNotAllowed"
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          BearerAuthentication: []

  /messaging/ws:
    get:
      summary: Provides a WebSocket callback subscription.
      description: |
        # General
        Enables an bidirectional communication to establish subscriptions and notifications .

        # Details
        The endpoint allows to:
        - subscribe to CoV of datapoints 
        - read/write datapoint values
           
        # Notes
        ## Implementation Details
        The websocket communication pattern and data format is not expressed as API 
        definition in this OpenAPI file.
      tags:
        - subscription
      operationId: getMessagingWebSocket
      parameters:
        - $ref: "#/components/parameters/WsUpgrade"
        - $ref: "#/components/parameters/WsConnection"
        - $ref: "#/components/parameters/WsKey"
        - $ref: "#/components/parameters/WsProtocol"
        - $ref: "#/components/parameters/WsVersion"
      responses:
        "101":
          description: Switching to Websocket protocol, continue to sending data envelopes.
          headers:
            Upgrade:
              schema:
                type: string
                enum: [websocket]
              description: Mandatory RFC 6455 header with fixed value `websocket`.
            Connection:
              schema:
                type: string
                enum: [Upgrade]
              description: Mandatory RFC 6455 header with fixed value `Upgrade`.
            Sec-Websocket-Accept:
              schema:
                type: string
              description: Mandatory RFC 6455 header with base64 encoded SHA1- value of... (see RFC).
            Sec-Websocket-Protocol:
              schema:
                type: string
                enum: [gw.knx.org]
              description: Optional RFC 6455 header, in this API mandatory with fixed value
                `gw.knx.org`.
        "200": 
          description: Client specific (error) handling, RFC 6455 does not specify an **explicit** 200 handling, see clause 4.1. 
        "500":
          $ref: "#/components/responses/httpStatusInternalServerError"
        default:
          $ref: "#/components/responses/httpStatusDefaultError"
      security:  
        - OAuth2: [manage]
          BearerAuthentication: []

components:
  callbacks:
    notificationData:
      "{$request.body#/meta/url}":
        post:
          description: |
            Invokes a callback on a datapoint value change.
            Uses the URL specified on the subscription call, defined as `meta/url`member.
          operationId: onEventCallback
          parameters:
            - name: X-Callback-Signature
              in: header
              required: true
              description:
                A HMAC-SHA256 of the concatenation of Header value Host,
                Path, Date and the request body. The shared secret is the secret specified by the client in the subscription request.
              schema:
                type: string
                format: PEM
          requestBody:
            description: |
              Event message data, containing of (JSON API) `data` member, specifying a a collection of datapoints, each with 
              - id/ type
              - links (self reference) 
              - value/ time stamp (as part of `attributes` member)
            required: true
            content:
              application/vnd.api+json:
                schema:
                  $ref:  "#/components/schemas/UpdateEvent"
                examples:
                  Runtime:
                    $ref: "#/components/examples/UpdateEventBodyExample"
          responses:
            "200":
              description: The callback was successfully executed
            "401":
              $ref: "#/components/responses/httpStatusUnauthorized"
            "500":
              $ref: "#/components/responses/httpStatusDefaultError"
            "501":
              $ref: "#/components/responses/httpStatusNotImplemented"

  responses:
    Access200:
      description: |
        The response (in both cases of retrieve/refresh an access token, RFC clause 5.1) with message data 
        containing of (JSON) member:
        - access token (in RFC + API mandatory)
        - token type (in RFC + API mandatory, here _bearer_)
        - refresh token (in RFC recommended, in API mandatory)
        - expiration (in RFC optional, in API mandatory)
        - scope (in RFC optional, in API mandatory)
        
        According to RFC 6749, clause 5.1 the response payload must be conform with application/json. 
        The current AN198 deviates from this payload definition, this will be updated in the next version of the AN. 
        In this YAML file it is specified as follows: 

        - application/json is specified as response payload format    
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Access"
          examples:
            Runtime:
              summary: Runtime
              value:
                access_token: bfa67489-e73d-44d6-a475-aa3265b19756
                token_type: bearer
                refresh_token: cd355573-b597-4cdf-9880-8251be6e0d2a
                expires_in: 1440
                scope: write

    httpStatusBadRequest:
      description: Bad request data.
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Bad Request
                links: https://schema.knx.org/2020/api
                status: 400
                detail: Bad request error.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusConflict:
      description: Serving the request leads to a conflict.
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Conflict
                links: https://schema.knx.org/2020/api
                status: 409
                detail: Conflict error. Serving the request leads to a conflict.
          schema:
            $ref: "#/components/schemas/Errors"

    DataPoint200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > datapoint item, including:
          - id/ type
          - some datapoint attributes including some meta information on the datapoint 
          - some relationships (links) to 
            - an endpoint providing all functions where this datapoint is included
            - an endpoint providing the device where this datapoint is included
            - an endpoint providing the proxy (device) where this datapoint is represented
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Datapoint"
          examples:
            Runtime1:
              $ref: "#/components/examples/DatapointItemEnumExample"
            Runtime2:
              $ref: "#/components/examples/DatapointItemValueExample"  

    DataPointCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of datapoint items, each including:
          - id/ type
          - some datapoint attributes including some meta information on the datapoint 
          - some relationships (links) to 
            - an endpoint providing all functions where this datapoint is included
            - an endpoint providing the device where this datapoint is included
            - an endpoint providing the proxy (device) where this datapoint is represented
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/DatapointCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/DataPointCollectionExample"

    httpStatusDefaultError:
      description: Unexpected error
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Internal Server Error
                links: https://schema.knx.org/2020/api
                status: 500
                detail: Unexpected error.
          schema:
            $ref: "#/components/schemas/Errors"

    Device200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > device item, including:
          - id/ type
          - some device attributes including some meta information on the device 
          - some relationships (links) to 
            - an endpoint providing the location where this device is included
            - an endpoint providing the datapoints included in this device
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Device"
          examples:
            Runtime:
              $ref: "#/components/examples/DeviceItemExample"

    DeviceCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of device items, each including:
          - id/ type
          - some device attributes including some meta information on the device 
          - some relationships (links) to 
            - an endpoint providing the location where this device is included
            - an endpoint providing the datapoints included in this device
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/DeviceCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/DeviceCollectionExample"

    httpStatusForbidden:
      description: Access is forbidden
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Forbidden
                links: https://schema.knx.org/2020/api   
                status: 403
                detail: Client could be authenticated but does not have the authorization to access this resource.
          schema:
            $ref: "#/components/schemas/Errors"

    Function200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > function item, including:
          - id/ type
          - some function attributes including some meta information on the function 
          - some relationships (links) to 
            - an endpoint providing the location where this function is included
            - an endpoint providing the datapoints included in this function
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Function"
          examples:
            Runtime:
              $ref: "#/components/examples/FunctionItemExample"

    FunctionCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of function items, each including:
          - id/ type
          - some function attributes including some meta information on the function 
          - some relationships (links) to 
            - an endpoint providing the location where this function is included
            - an endpoint providing the datapoints included in this function
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/FunctionCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/FunctionCollectionExample"

    httpStatusVersion:
      description: Unable to reach the target endpoint
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: HTTP Version Not Supported
                links: https://schema.knx.org/2020/api    
                status: 505
                detail: The HTTP version used in the request is not supported by the server.
          schema:
            $ref: "#/components/schemas/Errors"

    Installation200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > installation item, including:
          - id/ type
          - some installation attributes including some meta information on the installation 
          - some relationships (links) to 
            - a type description
      content:
        application/vnd.api+json:
          schema:
            $ref:  "#/components/schemas/Installation"
          examples:
            Runtime:
              $ref:  "#/components/examples/InstallationItemExample"

    InstallationCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of installation items, each including:
          - id/ type
          - some installation attributes including some meta information on the installation 
          - some relationships (links) to 
            - a type description
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/InstallationCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/InstallationCollectionExample"

    httpStatusInternalServerError:
      description: Internal server error
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Internal Server Error
                links: https://schema.knx.org/2020/api
                status: 500
                detail: Unable to upgrade to websocket connection.
          schema:
            $ref: "#/components/schemas/Errors"

    Location200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > location item, including:
          - id/ type
          - some location attributes including some meta information on the function 
          - some relationships (links) to 
            - an endpoint providing the parent location of this location
            - an endpoint providing all child locations of this location
            - an endpoint providing all functions included in this location
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Location"
          examples:
            Runtime:
              $ref: "#/components/examples/LocationItemExample"

    LocationCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of location items, each including:
          - id/ type
          - some location attributes including some meta information on the location 
          - some relationships (links) to 
            - an endpoint providing the parent location of this location
            - an endpoint providing all child locations of this location
            - an endpoint providing all functions included in this location
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/LocationCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/LocationCollectionExample"

    ChildLocationCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of location items, each including:
          - id/ type
          - some location attributes including some meta information on the location 
          - some relationships (links) to 
            - an endpoint providing the parent location of this location
            - an endpoint providing all child locations of this location
            - an endpoint providing all functions included in this location
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/LocationCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/ChildLocationCollectionExample"

    Subscription200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member -> subscription item, including:
          - id/ type
          - an `attributes` member describing the subscription properties (url, secret, caCert)
          - an `meta` member describing the _subscription type_
          - a (single) `relationships` member, describing a link to an endpoint providing all datapoints of this subscription
        
        For security reasons it is **strongly** recommended to NOT include the (optional) 
        subscription properties (part of `attributes` and `meta` members) in the response when you operate in public environments. 
        In a local environment the attributes may be included in the response (such as for debug reasons).

        ### Notes
        The current AN198 deviates from this payload definition, this will be updated in the next version of the AN. 
        In this YAML file it is specified as follows:
          
        - individual subscription items with its id/ subscription resource type (such as room, datapoint, ...) are 
          not included in the response payload (see Notes above)
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Subscription"
          examples:
            Runtime1:
              $ref: "#/components/examples/SubscriptionItemLanExample"
            Runtime2:
              $ref: "#/components/examples/SubscriptionItemWanExample"  

    SubscriptionCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member -> collection of subscription items, each including:
          - id/ type
          - an `attributes` member describing the subscription properties (url, secret, caCert)
          - an `meta` member describing the _subscription type_
          - a (single) `relationships` member, describing a link to an endpoint providing all datapoints of this subscription
      
        For security reasons it is **strongly** recommended to NOT include the (optional) 
        subscription properties (part of `attributes` and `meta` members) in the response when you operate in public environments. 
        In a local environment the properties may be included in the response (such as for debug reasons).

        ### Notes
        The current AN198 deviates from this payload definition, this will be updated in the next version of the AN. 
        In this YAML file it is specified as follows:
          
        - individual subscription items with its id/ subscription resource type (such as room, datapoint, ...) are 
          not included in the response payload (see Notes above)
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/SubscriptionCollection"
          examples:
            Runtime1:
              $ref: "#/components/examples/SubscriptionCollectionLanExample"
            Runtime2:
              $ref: "#/components/examples/SubscriptionCollectionWanExample"  

    httpStatusMethodNotAllowed:
      description: Wrong HTTP method used
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Method Not Allowed
                links: https://schema.knx.org/2020/api 
                status: 405
                detail: Method not allowed error.
          schema:
            $ref: "#/components/schemas/Errors"

    Node200:
      description: |
        The response with message data containing of (JSON API) member:
        - `data` member > ONE node item, including:
          - id/ type
          - some node attributes including some meta information on the node 
          - some relationships (links) to 
            - a type description of the node
      
        - as a remark, no `meta` member. 
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/Node"
          examples:
            Runtime:
              $ref: "#/components/examples/NodeItemExample"

    httpStatusNotAcceptable:
      description: Not acceptable
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Not acceptable error
                links:  https://schema.knx.org/2020/api     
                status: 406
                detail: Not acceptable error.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusNotFound:
      description: An entity with the given ID hasn't been found
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Not Found
                links: https://schema.knx.org/2020/api
                status: 404
                detail: Not found error. An entity with the given ID hasn't been found.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusNotImplemented:
      description: Not implemented
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Not Implemented
                links: https://schema.knx.org/2020/api   
                status: 501
                detail: Not implemented error.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusBadRequestOAuth2:
      description: |
        Bad Request

        The error is caused by an invalid request call for an failed or invalid authentication. 
        The basic http `400` error response is extended with specific OAuth2 error details 
        in JSON format (RFC, clause 5.2). 
        - error (mandatory, in RFC clause 5.2 specified error code, <https://tools.ietf.org/html/rfc6749#section-5.2>)
        - error_description
        - error_uri
      
        It may contain additional information such as a vendor specific information.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorsOAuth2"      
          example:
            title: Bad Request
            links: https://schema.knx.org/2020/api
            status: 400
            error: invalid_request
            error_description: missing required parameter or parameter is unsupported.
            error_uri: https://schema.knx.org/api
            
    httpStatusRequestTimeout:
      description: Unable to reach the target device
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Gateway Timeout 
                links: https://schema.knx.org/2020/api 
                status: 504
                detail: Unable to reach the target device.
          schema:
            $ref: "#/components/schemas/Errors"

    SiteCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of root location items, each including:
          - id/ type
          - some location attributes including some meta information on the function 
          - some relationships (links) to 
            - an endpoint providing all child locations of this location
            - an endpoint providing all functions included in this location
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/LocationCollection"
          examples:
            Runtime:
              $ref: "#/components/examples/SiteCollectionExample"

    httpStatusTooManyRequests:
      description: Too Many Requests
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Too Many Requests
                links: https://schema.knx.org/2020/api 
                status: 429
                detail: The client has sent too many requests in a given amount of time.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusUnauthorized:
      description: Unauthorized access
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Unauthorized
                links: https://schema.knx.org/2020/api
                status: 401
                detail: Unauthorized access error.
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusUnsupportedContentFormat:
      description: Unsupported Content-Format
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Unsupported Media Type 
                links: https://schema.knx.org/2020/api
                status: 415
                detail: The media format of the requested data is not supported by the server.          
          schema:
            $ref: "#/components/schemas/Errors"

    httpStatusURITooLong:
      description: URI is to long
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: URI Too Long
                links: https://schema.knx.org/2020/api 
                status: 414
                detail: The server will not accept the URI with this length.
          schema:
            $ref: "#/components/schemas/Errors"

    WellKnown200:
      description: |
        The response with message data containing of (JSON) member:
        - `api` member > most recent supported API version item, including version/ base path URL
        - `supportedversions` member > additionally supported (older) API version items, each including version/ base path URL
        - some `links`member, collection of useful (free to define) relations such as the /installations or /node endpoint,
          each item including
          - link
          - description
          - content type 
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WellKnown"
          examples:
            Runtime:
              summary: Runtime
              description: |
                The **Runtime** example shows:
                - the most recent API version 2.0
                - the API entry point
                - the older supported API versions 1.0/1.5
              value:
                api:
                  version: "2.0"
                  base: api/v2
                supportedversions:
                  - version: "1.5"
                    base: api/v15
                  - version: "1.0"
                    base: api/v1
                links:
                  - href: /installations
                    typedescription: https://schema.knx.org/2020/api
                    contenttype: application/vnd.api+json
                  - href: /node
                    typedescription: https://schema.knx.org/2020/api
                    contenttype: application/vnd.api+json  

  schemas:
    
    oAuth2AccessToken:
      type: object
      description: request body payload to retrieve an access token
      required:
        - grant_type
        - code
        - redirect_uri
      properties:
        grant_type: 
          description: OAuth 2.0 **grant_type** `authorization_code`, to generate an access token 
          type: string
          enum: [authorization_code]
        code: 
          description: same code as it was generated from the authorization server 
            as part of the authorization response call
          type: string
        redirect_uri:
          description: same URI as it was submitted to the authorization server
            as part of the authorization request call
          type: string
          format: uri
  
    oAuth2RefreshToken:
      type: object
      description: request body payload to refresh an access token
      required:
        - grant_type
        - refresh_token
      properties:
        grant_type: 
          description: OAuth 2.0 **grant_type** `refresh_token`, to refresh an access token
          type: string
          enum: [refresh_token]
        refresh_token: 
          description: same token as it was generated from the token endpoint
            as part of the last access token request call (as a note, in this API the `refresh_token` 
            is a mandatory response token, in RFC 6749 it is an optional response token) 
          type: string

    Access:
      type: object
      required:
        - access_token
        - token_type
        - refresh_token
        - expires_in
        - scope
      properties:
        access_token:
          type: string
          format: uuid
          description: The access token issued by the token endpoint.
        token_type:
          type: string
          enum: [bearer]
          description: The access token format, preferably an UUID.
          default: bearer
        refresh_token:
          type: string
          format: uuid
          description: The refresh token to get a new access token, preferably an UUID.
        expires_in:
          type: integer
          format: int64
          minimum: 1
          description: The expiration time of the access token in seconds.
            The behavior of zero seconds is not specified, the value MUST be excluded.
        scope:
          type: string
          description: |
            One of the below described scopes, predefined and specified in this API. Vendor defined scopes
            are possible, but not considered here. 
            - read 
            - write (which includes read) 
            - manage (which includes read and write)
          enum: [read, write, manage]
             
    EntityId:
      type: object
      required:
        - id
      properties:
        id:
          description: Locally unique resource identifier, preferably an UUID.
          type: string
          format: uuid

    DatapointTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [datapoint]

    SubscriptionTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [subscription]

    SubscriptionUpdate:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/SubscriptionUpdateItem"

    SubscriptionUpdateItem:
      allOf:
      - $ref: "#/components/schemas/SubscriptionTypeAndId"
      - type: object
        required:
          - attributes
        properties:
          attributes:
            $ref: "#/components/schemas/SubscriptionAttributes"

    SubscribeRequest:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SubscribeRequestItem"
        meta:
          type: object
          description: Expresses all to this subscription request related properties.  
          required:
            - url
            - secret
            - type
          properties:
            url:
              description: HTTPS based callback URL of the notification endpoint. 
              type: string
              format: url
            secret:
              description: Shared secret for secure callbacks (to trust the KNX IoT 3rd Party server).
              type: string
            caCert:
              description: Base64 representation of a PEM encoded certificate (to trust the notification endpoint).
              type: string
              format: bytes
            type:
              description: Subscription type, describing the characteristics of the subscription.
              type: string
              enum: [subscribe.datapoint, subscribe.datapoint.*]  

    SubscribeRequestItem:
      description: Expresses an array of to be upon subscribed resource items, each item 
        including of the resource id and the actual resource type.
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the to be subscribed item.
              type: string
              enum: [device, datapoint, function, site, room, floor, building]

    SubscribeResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SubscribeResponseItem"

    SubscribeResponseItem:
      allOf:
      - $ref: "#/components/schemas/DatapointTypeAndId"
      - type: object
        required:
          - relationships
        properties:
          relationships:
            $ref: "#/components/schemas/SubscribeResponseItemRelationships"
          attributes:
            $ref: "#/components/schemas/SubscribeResponseItemAttributes"
            
    SubscribeResponseItemAttributes:
      type: object
      description: The datapoint value and event time occurrence.
      properties:
        value:
          type: string
        timeStamp:
          type: string
          format: date-time

    SubscribeResponseItemRelationships:
      type: object
      description: Reference to a subscription, containing a specific datapoint.
      required:
        - datapointSubscription
      properties:
        datapointSubscription:
          $ref: "#/components/schemas/relatedLinksMember"

    FunctionTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [function]

    InstallationTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [installation]

    LocationTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [site, room, floor, building]

    DeviceTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [device]

    NodeTypeAndId:
      allOf:
        - $ref: "#/components/schemas/EntityId"
        - type: object
          required:
            - type
          properties:
            type:
              description: The resource type of the entity.
              type: string
              enum: [device, service]

    SubscriptionCharacteristics:
      type: object
      properties:
        type:
          description: The subscription type, describing the characteristics of the subscription.
          type: string
          enum: [subscribe.datapoint, subscribe.datapoint.*]

    SubscriptionItem:
      type: object
      description: |
        A definition for a subscription object including:
        - type/ id, mandatory
        - `attributes` member, describing subscription properties, optional 
        - `meta` member, describing the subscription (characteristics) type, optional
        - relationships to other relevant resources, mandatory
      allOf:
        - $ref: "#/components/schemas/SubscriptionTypeAndId"
        - type: object
          required:
            - relationships
          properties:
            attributes:
              $ref: "#/components/schemas/SubscriptionAttributes"
            meta:
              $ref: "#/components/schemas/SubscriptionCharacteristics"
            relationships:
              type: object
              description: |
                Some references expressing relations to 
                - `subscriptionDatapoints` member, a relative reference to to all datapoints, included in a specific subscription.
              required:
                - subscriptionDatapoints
              properties:
                subscriptionDatapoints:
                  $ref: "#/components/schemas/relatedLinksMember"

    Subscription:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/SubscriptionItem"

    SubscriptionCollection:
      type: object
      description: A collection of subscriptions including some specific information on the collection.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/SubscriptionItem"

    CollectionInformation:
      type: object
      properties:
        collection:
          type: object
          description: Information on the returned items and the total number of collection items at the server.
          required:
            - offset
            - items
            - total
          properties:
            offset:
              type: integer
              minimum: 0
              default: 1
              description: The number of items skipped in the response that may be limited with a request parameter.
            items:
              type: integer
              description: The actual number of items returned in the response.
            total:
              type: integer
              description: The total numbers of existing items in the whole collection at the server.

    Datapoint:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/DatapointItem"

    DatapointItem:
      type: object
      description: |
        A definition for a datapoint object including:
        - type/ id
        - attributes
        - meta information on the datapoint 
        - relationships to other relevant resources
      allOf:
        - $ref: "#/components/schemas/DatapointTypeAndId"
        - type: object
          required:
            - attributes
          properties:
            attributes:
              $ref: "#/components/schemas/DatapointItemAttributes"
            meta:
              $ref: "#/components/schemas/TypeMetaItem"
            relationships:
              $ref: "#/components/schemas/DatapointItemRelationships"
             
    DatapointItemAttributes:
      type: object
      description: The JSON API attribute member, expressing datapoint properties.
      allOf:
        - $ref: "#/components/schemas/Title"
        - type: object
          oneOf:
            - type: object
              required:
              - enum
              properties:
                enum:
                  type: array
                  items:
                    type: string
                    description: |
                      List of valid enumerations for the datapoint value.
                      If expressed, the datapoint has an enumerated type (alternative to numbered values), 
                      such as [a,b,c] or [true,false]. As a note, also the boolean type (true/false, up/down, ...) 
                      is an enumeration.  
            - type: object
              required:
              - unit
              properties:
                unit:
                  type: string
                  description: The datapoint unit, if expressed the datapoint value has a numbered type.
                minimum:
                  type: integer
                  description: Expresses an applicative minimal (numbered type) value.
                maximum:
                  type: integer
                  description: Expresses an applicative maximal (numbered type) value.
        - type: object 
          required:
          - valueType 
          properties:
            description:
              type: string
              description: Represents the description of a datapoint.
            readable:
              type: boolean
              description: Specifies if a datapoint can be read from a client.
              default: true
            writable:
              type: boolean
              description: Specifies if a datapoint can be written from a client.
              default: false
            value:
              type: string
              description: The value of this datapoint, covers numerical and string oriented values.
            valueType:
              type: string
              description: |
                The type of the value of this Datapoint.
                - numbered and enumerated value types must use *string*
                - *object* is not yet specified
              enum: [string, object]
            timestamp:
              type: string
              description: The time where this value was read or written at the server.
              format: date-time

    DatapointItemRelationships:
      type: object
      description: |
        The JSON API reference member, expressing relations to 
        - `typedescription` member, an absolute URL reference to an external description of this datapoint type.
        - `datapointFunctions` member, a relative reference to functions, hosting this datapoint.
        - `datapointDevice` member, a relative reference to a device, hosting this datapoint.
        - `datapointProxy` member, a relative reference to a proxy (device), acts as proxy for this datapoint
      anyOf:  # combine *from* all underneath objects (its content!), note > all objects properties are optional 
        - $ref: "#/components/schemas/TypeDescriptionRef"
        - type: object
          properties:
            datapointFunctions:
              $ref: "#/components/schemas/relatedLinksMember"
            datapointDevice:
              $ref: "#/components/schemas/relatedLinksMember"
            datapointProxy:
              $ref: "#/components/schemas/relatedLinksMember"
    
    TypeMetaItem:
      type: object
      description: |
        The JSON API meta member, expressing an array containing one ore more specific **type** definitions 
        for the entity (such as device, datapoint, function).
      properties:
        "@type":
          type: array
          items:
            type: string
            

    DatapointCollection:
      type: object
      description: A collection of datapoints including some specific information on the collection.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/DatapointItem"

    DatapointCollectionWithValues:
      type: object
      description: A collection of to be written datapoints.
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/DatapointCollectionWithValuesItem"

    DatapointCollectionWithValuesItem:
      allOf:
      - $ref: "#/components/schemas/DatapointTypeAndId"
      - type: object
        required:
          - attributes
        properties:
          attributes:
            type: object
            required:
              - value
            properties:
              value:
                type: string
                description: The to be written datapoint value.

    DeviceItem:
      type: object
      description: |
        A definition for a device object including:
        - type/ id
        - attributes
        - meta information on the device 
        - relationships to other relevant resources
      allOf:
        - $ref: "#/components/schemas/DeviceTypeAndId"
        - type: object
          required:
            - attributes
            - relationships
          properties:
            attributes:
              $ref: "#/components/schemas/DeviceItemAttributes"
            meta:
              $ref: "#/components/schemas/TypeMetaItem"
            relationships:
              $ref: "#/components/schemas/DeviceItemRelationships"

    DeviceItemRelationships:
      anyOf:
      - $ref: "#/components/schemas/TypeDescriptionRef"
      - type: object
        description: |
          Some references expressing relations to 
          - `typedescription` member, an absolute URL reference to an external description of this datapoint type.
          - `deviceLocation` member, a reference to the location, hosting this device.
          - `deviceDatapoints` member, Relative reference to the datapoints hosted in this device.
        properties:
          deviceLocation:
            $ref: "#/components/schemas/relatedLinksMember"
          deviceDatapoints:
            $ref: "#/components/schemas/relatedLinksMember"

    DeviceItemAttributes:
      allOf:
        - $ref: "#/components/schemas/Title"
        - type: object
          properties:
            orderNumber:
              type: string
              description: order number string of this device (derived from the product)
            manufacturer:
              type: string
              description: the producer/manufacturer of the device, string
            lastModified:
              type: string
              description:
                last device modification, date/ time in ISO 8601/ RFC 3339 format,
                <https://tools.ietf.org/html/rfc3339#section-5.6>
            lastDownloaded:
              type: string
              description:
                last device download, date/ time in ISO 8601/ RFC 3339 format,
                <https://tools.ietf.org/html/rfc3339#section-5.6>
            serialNumber:
              type: string
              description: serial number of device, set during manufacturing process
            individualAddress:
              type: string
              description: device address as part of the installation,
                set in MaC during configuration
            version:
              type: object
              properties:
                firmware:
                  type: string
                  description: device SW version
                hardware:
                  type: string
                  description: device HW version

    Device:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/DeviceItem"

    DeviceCollection:
      description: A collection of devices including some specific information on the collection.
      type: object
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/DeviceItem"

    relativeEntityReference:
      type: string
      format: path

    FunctionItem:
      type: object
      description: |
        A definition for a function object including:
        - type/ id
        - attributes
        - meta information on the function 
        - relationships to other relevant resources
      allOf:
        - $ref: "#/components/schemas/FunctionTypeAndId"
        - type: object
          required:
            - attributes
            - relationships
          properties:
            attributes:
              $ref: "#/components/schemas/Title"
            meta:
              $ref: "#/components/schemas/TypeMetaItem"
            relationships:
              $ref: "#/components/schemas/FunctionItemRelationships"

    FunctionItemRelationships:
      anyOf: # combine *from* all underneath objects (its content!), note > all objects properties are optional 
      - $ref: "#/components/schemas/TypeDescriptionRef"
      - type: object
        description: |
          Some references expressing relations to 
          - `typedescription` member, an absolute URL reference to an external description of this function type.
          - `functionLocations` member, a relative reference to the location hosting this function.
          - `functionDatapoints` member, a relative reference to the datapoints hosted in this function.
        required:
          - functionLocations
          - functionDatapoints
        properties:
          functionLocations:
            $ref: "#/components/schemas/relatedLinksMember"
          functionDatapoints:
            $ref: "#/components/schemas/relatedLinksMember"

    Function:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/FunctionItem"

    FunctionCollection:
      type: object
      description: A collection of functions including some specific information on the collection.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/FunctionItem"

    Installation:
      type: object
      required:
        - data
      properties:
        data: 
          $ref: "#/components/schemas/InstallationItem"

    InstallationCollection:
      type: object
      description: A collection of installations including some specific information on the collection.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/InstallationItem"

    InstallationItem:
      type: object
      description: |
        A definition for a installation object including:
        - type/ id
        - attributes
        - relationships to other relevant resources
      allOf:
        - $ref: "#/components/schemas/InstallationTypeAndId"
        - type: object
          required:
            - attributes
          properties:
            attributes:
              $ref: "#/components/schemas/InstallationItemAttributes"
            relationships:
              $ref: "#/components/schemas/TypeDescriptionRef"

    InstallationItemAttributes:
      allOf:
        - $ref: "#/components/schemas/Title"
        - type: object
          properties:
            comment:
              type: string
              description: A comment expressed in the MaC from the installer for this installation.
            contractNumber:
              type: string
              description: The contract number of the installation.
            mac:
              type: string
              description: The management client version exported the installation data.
            lastModified:
              type: string
              description: Last modification of the installation, date/ time in ISO 8601/ RFC 3339 format, <https://tools.ietf.org/html/rfc3339#section-5.6>
            projectInstallationNumber:
              type: string
              description: A number expressed in the MaC from the installer for this installation.
            state:
              type: string
              description: A generic state expressed in the MaC from the installer for this installation.


    Errors:
      description: |
        Array of error items, included in the JSON API `errors` member. 
        Each error item must be conform to RFC 7807. It may contain additional information such as: 
        - a JSON API `links` member, pointing to absolute/ relative URL with error details  
        - a vendor specific information
      type: object
      properties:
        errors:
          type: array
          items:
            required:
              - title
              - status
            properties:
              title:
                description: Error title or HTTP status phrase.
                type: string
              status:
                description: HTTP status code.
                type: integer
                format: int32
              detail:
                description: Detailed description of the error.
                type: string
              links:
                description: Absolute URL reference to a detailed description of the error.
                type: string
                format: uri

    ErrorsOAuth2:
      description: |
        A single error item, expressed as a JSON object, conform to RFC 7807.
        The general error description is extended with OAuth2 specific error details.
      type: object
      required:
        - title
        - status
        - error
      properties:
        title:
          description: HTTP status phrase/ error title.
          type: string
        status:
          description: HTTP status code.
          type: integer
          format: int32
        error:
            description: | 
              In OAuth2 RFC (clause 5.2) specified error types 
            type: string
            enum: [invalid_request,invalid_client,invalid_grant,unauthorized_client,
            unsupported_grant_type,invalid_scope]
        error_description:
            description: Readable OAuth2 error description, embedded in the error response, type string.
            type: string
        error_uri: 
            description: Absolute URL reference to to a detailed description of the OAuth2 error, type uri. 
            type: string
            format: uri
    
    relatedLinksMember:
      type: object
      description: A JSON API `links` member, expressing a `related` member as a relative link/reference to an entity.
      required:
        - links
      properties:
        links:
          type: object
          required:
            - related
          properties:
            related:
              $ref: "#/components/schemas/relativeEntityReference"

    LocationItem:
      type: object
      description: |
        A definition for a location object including:
        - type/ id
        - attributes
        - meta information on the location 
        - relationships to other relevant resources
      allOf:
        - $ref: "#/components/schemas/LocationTypeAndId"
        - type: object
          required:
            - attributes
            - relationships
          properties:
            attributes:
              $ref: "#/components/schemas/Title"
            relationships:
              $ref: "#/components/schemas/LocationItemRelationships"

    LocationItemRelationships:
      type: object
      description: |
            Some references expressing relations to 
            - `typedescription` member, an absolute URL reference to an external description of this function type.
            - `parentlocation` member, a relative reference to the parent location of this location.
            - `childlocations` member, a relative reference to all child locations of this location.
            - `locationFunctions` member, a relative reference to all functions included in this location.
      anyOf: # combine *from* all underneath objects (its content!), note > all objects properties are optional 
      - $ref: "#/components/schemas/TypeDescriptionRef"
      - type: object
        properties:
          parentLocation:
            $ref: "#/components/schemas/relatedLinksMember"
          childLocations:
            $ref: "#/components/schemas/relatedLinksMember"
          locationFunctions:
            $ref: "#/components/schemas/relatedLinksMember"

    Location:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/LocationItem"

    LocationCollection:
      type: object
      description: A collection of locations including some specific information on the collection.
      required:
        - meta
        - data
      properties:
        meta:
          $ref: "#/components/schemas/CollectionInformation"
        data:
          type: array
          items:
            $ref: "#/components/schemas/LocationItem"

    Node:
      type: object
      required:
        - data
      properties:
        data: 
          $ref: "#/components/schemas/NodeItem"

    NodeItem:
      type: object
      allOf:
        - $ref: "#/components/schemas/NodeTypeAndId"
        - type: object
          required:
            - attributes
          properties:
            attributes:
              type: object
              required:
                - title
                - deviceOrServiceName
                - vendorOrProvider
              properties:
                title:
                  type: string
                  description: node name
                deviceOrServiceName:
                  type: string
                  description: interface service type
                vendorOrProvider:
                  type: string
                  description: interface vendor or provider name,
                    should corresponds to name used as part of the **name space** used for KNX vendor attributes
                description:
                  type: string
                  description: verbose interface description
                version:
                  type: object
                  properties:
                    server:
                      type: string
                      description: interface API version (of device or service resp. node, not the API)
            relationships:
              $ref: "#/components/schemas/TypeDescriptionRef"

    SubscriptionAttributes:
      type: object
      properties:
        url:
          description: HTTPS based callback URL of the notification endpoint.
          type: string
          format: url
        secret:
          description: Shared secret for secure callbacks (to trust the KNX IoT 3rd Party server).
          type: string
        caCert:
          description: Base64 representation of a PEM encoded certificate (to trust the notification endpoint).
          type: string
          format: bytes

    Title:
      type: object
      description: Represents the name of an entity.
      required:
        - title
      properties:
        title:
          type: string

    TypeDescriptionRef:
      type: object
      description: An absolute URL reference to an external description of this object type.
      properties:
        typedescription:
          type: object
          properties:
            links:
              type: object
              required:
                - related
              properties:
                related:
                  type: string
                  format: uri

    UpdateEvent:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/UpdateEventItem"

    UpdateEventItem:
      allOf:
      - $ref: "#/components/schemas/DatapointTypeAndId"
      - type: object
        properties:
          links:
            $ref: "#/components/schemas/UpdateEventItemLinks"
          attributes:
            $ref: "#/components/schemas/UpdateEventItemAttributes"

    UpdateEventItemAttributes:
      type: object
      description: The datapoint value and event time occurrence.
      properties:
        value:
          type: string
          description: value as string, no datapoint format definition included
        timeStamp:
          type: string
          description: date/ time in ISO 8601/ RFC 3339 format, <https://tools.ietf.org/html/rfc3339#section-5.6>
          format: date-time

    UpdateEventItemLinks:
      type: object
      description: A JSON API `links` member, expressing a `self` member as a link/reference to an entity.
      required:
        - self
      properties:
        self:
          $ref: "#/components/schemas/relativeEntityReference"

    WellKnown:
      type: object
      required:
        - api
      properties:
        api:
          $ref: "#/components/schemas/VersionAndBasepath"
        supportedversions:
          type: array
          description: Additional supported (older) API versions if any.
          items:
            $ref: "#/components/schemas/VersionAndBasepath"
        links:
          type: array
          description: References to some useful API entry points.
          items:
            type: object
            properties:
              href:
                description: Relative resource path of an useful API entry point.
                type: string
                format: path
              typedescription:
                description: Absolute URL reference to a extended description for this API entry point.
                type: string
                format: uri
              contenttype:
                description: Content-Type of the - by _href_ - described API entry point.
                  For the current API only one is specified.
                type: string
                enum: [application/vnd.api+json]
                default: application/vnd.api+json

    VersionAndBasepath:
      type: object
      description: | 
        API version and base path information:
        - `version`  > major.minor, such as 2.0
        - `base` > relative URL base part (RFC 3986), corresponding to the API version  
      required:
        - version
        - base 
      properties:
        version:
          type: string
        base:
          $ref: "#/components/schemas/relativeEntityReference"

  examples:
    
    DatapointItemEnumExample:
      summary: Runtime (enum)
      description: The **Runtime** example shows an enumeration value.
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a462
          type: datapoint
          attributes:
            title: on and off switching
            description: Status of the light in the bathroom
            readable: true
            writable: true
            value: on
            valueType: string
            timestamp: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
            enum: [on,off]
            electricWiringReference: Socket 25B
          meta:
            "@type":
              - dic:switch
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/functions
            datapointDevice:
              links:
                related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8300
            datapointProxy:
              links:
                related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8322
            typedescription:
              links:
                related: https://schema.knx.org/2020/api

    DatapointItemValueExample:
      summary: Runtime (value)
      description: The **Runtime** example shows an numbered value.
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a462
          type: datapoint
          attributes:
            title: Brightness setting
            description: Brightness of the light in the bathroom
            readable: true
            writable: true
            value: "5"
            valueType: string
            timestamp: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
            unit: DEG_C
            minimum: 4
            maximum: 6
            electricWiringReference: Socket 25B
          meta:
            "@type":
              - dic:scaling
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/functions
            datapointDevice:
              links:
                related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8300
            datapointProxy:
              links:
                related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8322
            typedescription:
              links:
                related: https://schema.knx.org/2020/api

    DataPointCollectionExample:
      summary: Runtime
      value:
        meta:
          collection:
            offset: 0
            items: 2
            total: 5
        data:
          - id: 1f48bf82-acee-45a1-9038-e2748860a462
            type: datapoint
            attributes:
              title: on and off switching
              description: Status of the light in the bathroom
              readable: true
              writable: true
              value: on
              valueType: string
              timestamp: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
              enum: [on,off]
              gira:globalReferenceId: 100-17021920
              electricWiringReference: Socket 25B
            meta:
              "@type":
                - dic:switch
            relationships:
              datapointFunctions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/functions
              datapointDevice:
                links:
                  related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8300
              datapointProxy:
                links:
                  related: /devices/2b2c281b-af58-4816-95d0-aaa2468f8322
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
          - id: 1f48bf82-acee-45a1-9038-e2748860a463
            type: datapoint
            attributes:
              title: Brightness
              value: "63"
              valueType: string
              timestamp: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
              unit: percent
              minimum: 0
              maximum: 100
              abb:electricIconId: 327
            meta:
              "@type":
                - dic:scaling
                - abb:specialScalingType
            relationships:
              datapointFunctions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/functions

    DeviceCollectionExample:
      summary: Runtime
      description: |
        The **Runtime** example shows a single device. Moreover KNX vendor specific 
        attributes/relationships and additionally attributes/relationships from the KNX information model. 
        Also extra device type information, expressed with the `meta` member.
      value:
        meta:
          collection:
            offset: 0
            items: 1
            total: 1
        data:
          - id: be43a294-3098-42ac-a165-1b5c5a4c0e64
            type: device
            attributes:
              title: 4-fold actuator
              orderNumber: 5WG100-200-AB
              manufacturer: Siemens
              lastModified: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
              lastDownloaded: "2021-02-17T17:20:17Z" # must surround date-time examples with quotes
              serialNumber: "1AB234"
              individualAddress: "9.4.1"
              version:
                firmware: "2.0.1"
              assignedTrade": Alerting # this is a attribute from the KNX information model
            meta:
              "@type":
                - td:Thing
                - oms:dt.WaterMeter
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              deviceLocation:
                links:
                  related: /locations/3a19fee4-ba8a-4fd2-ba10-42b7f40f5acf
              deviceDatapoints:
                links:
                  related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/datapoints

    DeviceItemExample:
      summary: Runtime
      description: |
        The **Runtime** example shows a single device. Moreover KNX vendor specific 
        attributes/relationships and additionally attributes/relationships from the KNX information model. 
        Also extra device type information, expressed with the `meta` member.
      value:
        data:
          id: be43a294-3098-42ac-a165-1b5c5a4c0e64
          type: device
          attributes:
            title: 4-fold actuator
            orderNumber: 5WG100-200-AB
            manufacturer: Siemens
            lastModified: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
            lastDownloaded: "2021-02-17T17:20:17Z" # must surround date-time examples with quotes
            serialNumber: "1AB234"
            individualAddress: "9.12.18"
            version:
              firmware: "20.2.0"
            assignedTrade: Alerting # this is a attribute from the KNX information model
          meta:
            "@type":
              - td:Thing
              - oms:dt.WaterMeter
          relationships:
            typedescription:
              links:
                related: https://schema.knx.org/2020/api
            deviceLocation:
              links:
                related: /locations/3a19fee4-ba8a-4fd2-ba10-42b7f40f5acf
            deviceDatapoints:
              links:
                related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/datapoints

    FunctionCollectionExample:
      summary: Runtime
      value:
        meta:
          collection:
            offset: 0
            items: 1
            total: 1
        data:
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8300
            type: function
            attributes:
              title: Light control in the living room
            meta:
              "@type":
                - urn:knx:fct.switchingLight
                - urn:knx.mft.abb.sameAsKNXSwitchingLightAbove
            relationships:
              functionLocations:
                links:
                  related: /locations/3a19fee4-ba8a-4fd2-ba10-42b7f40f5acf
              functionDatapoints:
                links:
                  related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/datapoints
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api

    FunctionItemExample:
      summary: Runtime
      value:
        data:
          id: 2b2c281b-af58-4816-95d0-aaa2468f8300
          type: function
          attributes:
            title: Light control in the living room
          meta:
            "@type":
              - urn:knx:fct.switchingLight
              - urn:knx.mft.abb.sameAsKNXSwitchingLightAbove
          relationships:
            functionLocations:
              links:
                related: /locations/3a19fee4-ba8a-4fd2-ba10-42b7f40f5acf
            functionDatapoints:
              links:
                related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/datapoints
            typedescription:
              links:
                related: https://schema.knx.org/2020/api

    InstallationCollectionExample:
      summary: Runtime
      value:
        meta:
          collection:
            offset: 0
            items: 1
            total: 1
        data:
          - id: 99291d1e-68ef-4874-ad40-6b1c41188fbe
            type: installation
            attributes:
              title: Master Home
              comment: Must be increase the hour rate for engineering services.
              contractNumber: 2021.August
              mac: ETS 4.7.5.
              lastModified: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
              projectInstallationNumber: 3-200
              state: Tested
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
          - id: 99291d1e-68ef-4874-ad40-6b1c41188fbf
            type: installation
            attributes:
              title: Master Garden
              comment: The gardener does not cleanup my pool.
              contractNumber: 2020.August
              mac: ETS 4.7.4.
              lastModified: "2020-02-17T17:17:17Z" # must surround date-time examples with quotes
              projectInstallationNumber: 3-100
              state: Tested
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api        

    InstallationItemExample:
      summary: Runtime
      value:
        data:
          id: 99291d1e-68ef-4874-ad40-6b1c41188fbf
          type: installation
          attributes:
            title: Master Home
            comment: Must be increase the hour rate for engineering services.
            contractNumber: 2021.August
            mac: ETS 4.7.5.
            lastModified: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes
            projectInstallationNumber: 3-200
            state: Tested
          relationships:
            typedescription:
              links:
                related: https://schema.knx.org/2020/api

    LocationCollectionExample:
      summary: Runtime
      description: |
        The **Runtime** example shows an spatial structure of an single building (building/floor/ 2 x room). 
        The building is not a root location, therefore the relation to the parent location at the building is expressed. 
        The two rooms are siblings underneath the floor.
      value:
        meta:
          collection:
            offset: 0
            items: 4
            total: 4
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000002
            type: building
            attributes:
              title: My holiday home
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000000
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000002/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000002/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000003
            type: floor
            attributes:
              title: Gadget floor
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000002
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000004
            type: room
            attributes:
              title: Garden gadgets
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000005
            type: room
            attributes:
              title: Pool gadgets
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/functions

    ChildLocationCollectionExample:
      summary: Runtime
      description: |
        The **Runtime** example shows a set of child locations. 
        The two rooms are child locations underneath a parent location (floor). 
        The rooms are the "last" spatial location elements, therefore no further relation 
        to child locations at the rooms are expressed.
      value:
        meta:
          collection:
            offset: 0
            items: 2
            total: 2
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000004
            type: room
            attributes:
              title: Garden gadgets
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000005
            type: room
            attributes:
              title: Pool gadgets
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000004
            type: room
            attributes:
              title: Garden gadgets
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions

    SiteCollectionExample:
      summary: Runtime
      description: |
        The **Runtime** example shows an spatial structure of a single premises including two sites.  
        The sites are root locations, therefore relations to a parent location are not expressed.
      value:
        meta:
          collection:
            offset: 0
            items: 2
            total: 2
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000000
            type: site
            attributes:
              title: My holiday premises, main part
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000000/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000000/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000001
            type: site
            attributes:
              title: My holiday premises, second part
            relationships:
              typedescription:
                links:
                  related: https://schema.knx.org/2020/api
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000001/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000001/functions

    LocationItemExample:
      summary: Runtime
      description: |
        The **Runtime** example shows an location of type room.  
        The room is not further sub-structured, therefore a relation to child locations is not expressed.
      value:
        data:
          id: ebe13789-1f1e-47d0-8f8a-000000000004
          type: room
          attributes:
            title: Garden gadgets
          relationships:
            typedescription:
              links:
                related: https://schema.knx.org/2020/api
            parentLocation:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003
            locationFunctions:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions

    UpdateEventBodyExample:
      summary: Runtime
      value:
        data:
          - id: 123e4567-e89b-12d3-a456-426614174000
            type: datapoint
            links:
              self: /datapoints/123e4567-e89b-12d3-a456-426614174000
            attributes:
              value: off
              timestamp: "2021-02-17T17:17:17Z" # must surround date-time examples with quotes

    SubscriptionItemLanExample:
      summary: Runtime (LAN)
      description: |
        The **Runtime (LAN)** example shows a subscription response in a local environment.  
        The security related properties are returned. 
      value:
        data:
          id: 123e4567-e89b-12d3-a456-4266141740aa
          type: subscription
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
          meta:
            type: subscribe.datapoint
          relationships:
            subscriptionDatapoints:
              links:
                related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints
     
    SubscriptionItemWanExample: 
      summary: Runtime (WAN)
      description: |
        The **Runtime WAN** example shows a subscription response in a public environment.  
        The security related properties are NOT returned. 
      value:
        data:
          id: 123e4567-e89b-12d3-a456-4266141740aa
          type: subscription
          meta:
            type: subscribe.datapoint
          relationships:
            subscriptionDatapoints:
              links:
                related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints        

    SubscriptionCollectionLanExample:
      summary: Runtime (LAN)
      description: |
        The **Runtime (LAN)** example shows a subscription collection response in a local environment.  
        The security related properties are returned. 
      value:
        meta:
          collection:
            offset: 0
            items: 1
            total: 1
        data:
          - id: 123e4567-e89b-12d3-a456-4266141740aa
            type: subscription
            attributes:
              url: https://api.notserv.com/updates
              secret: TheBestPasswordEver
              caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            meta:
              type: subscribe.datapoint
            relationships:
              subscriptionDatapoints:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints

    SubscriptionCollectionWanExample:
      summary: Runtime (WAN)
      description: |
        The **Runtime (WAN)** example shows a subscription collection response in a public environment.  
        The security related properties are NOT returned. 
      value:
        meta:
          collection:
            offset: 0
            items: 1
            total: 1
        data:
          - id: 123e4567-e89b-12d3-a456-4266141740aa
            type: subscription
            meta:
              type: subscribe.datapoint
            relationships:
              subscriptionDatapoints:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints
    
    SubscriptionPostExample:
      summary: Runtime
      value:
        data:
          - id: 123e4567-e89b-12d3-a456-426614174000
            type: room
          - id: 123e4567-e89b-12d3-a456-426614174001
            type: floor
          - id: 123e4567-e89b-12d3-a456-426614174002
            type: datapoint
        meta:
          type: subscribe.datapoint
          url: https://api.notserv.com/updates
          secret: TheBestPasswordEver
          caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----

    SubscriptionPutExample:
      summary: Runtime
      value:
        data:
          id: 123e4567-e89b-12d3-a456-4266141740aa 
          type: subscription
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----

    NodeItemExample:
      summary: Runtime
      value:
        data:
          id: ebe13789-1f1e-47d0-8f8a-800000000000
          type: service
          attributes:
            title: KNX IoT 3rd Party Interface
            deviceOrServiceName: gira service for KNX installations
            vendorOrProvider: gira
            description: remote endpoint with support of Amazon Alexa
            version:
              server: 2.0.1
          relationships:
            typedescription:
              links:
                related: https://schema.knx.org/2020/api

  parameters:
    
    collectionLimit:
      name: page[limit]
      description: The number of items to return.
      in: query
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 65536

    collectionOffset:
      name: page[offset]
      description: The number of items to skip before starting to collect the result set.
      in: query
      schema:
        type: integer
        format: int64
        minimum: 0
        default: 0

    datapointId:
      name: datapointId
      description: The id from requested datapoint.
      in: path
      required: true
      schema:
        type: string
        format: uuid

    deviceId:
      name: deviceId
      description: The id from requested device.
      in: path
      required: true
      schema:
        type: string
        format: uuid

    functionId:
      name: functionId
      description: The id from requested device.
      in: path
      required: true
      schema:
        type: string
        format: uuid

    subscriptionId:
      name: subscriptionId
      description: The id from requested subscription.
      in: path
      required: true
      schema:
        type: string
        format: uuid

    

    installationId:
      name: installationId
      in: path
      description: The ID of the installation which is operated on
      required: true
      schema:
        type: string

    locationId:
      name: locationId
      in: path
      description: The ID of the location we are operating on
      required: true
      schema:
        type: string

    WsKey:
      name: Sec-WebSocket-Key
      description: Mandatory RFC 6455 header, base64 encoded 16 byte _nonce_ value.
      in: header
      required: true
      style: simple
      schema:
        type: string
      examples:
        Runtime1:
          summary: Runtime (key 1)
          value: AQIDBAUGBwgJCgsMDQ4PEC==
        Runtime2:
          summary: Runtime (key 2)
          value: S05YQUZvckV2ZXIuLi4uLg==

    WsProtocol:
      name: Sec-WebSocket-Protocol
      description: Optional RFC 6455 header, in this API mandatory with fixed value.
      in: header
      required: true
      style: simple
      schema:
        type: string
        enum: [gw.knx.org]

    WsVersion:
      name: Sec-WebSocket-Version
      description: Mandatory RFC 6455 header with fixed value.
      in: header
      required: true
      style: simple
      schema:
        type: number
        format: int32
        enum: [13]

    WsUpgrade:
      name: Upgrade
      description: Mandatory RFC 6455 header with fixed value.
      in: header
      required: true
      style: simple
      schema:
        type: string
        enum: [websocket]

    WsConnection:
      name: Connection
      description: Mandatory RFC 6455 header with fixed value.
      in: header
      required: true
      style: simple
      schema:
        type: string
        enum: [Upgrade]

  requestBodies:
    
    datapointValuesPut:
      description: |
        Datapoints message data, containing of (JSON API) member:
          - `data` member -> collection of (to be written datapoint) items
      required: true
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/DatapointCollectionWithValues"
          examples:
            Runtime:
              summary: Runtime
              value:
                data:
                  - id: ebe13789-1f1e-47d0-8f8a-d00000000000
                    type: datapoint
                    attributes:
                      value: off
                  - id: ebe13789-1f1e-47d0-8f8a-d00000000001
                    type: datapoint
                    attributes:
                      value: "77.25"

  securitySchemes:
    OAuth2:
      type: oauth2
      description: | 
        Usage of standard oauth 2.0 Authorization code flow. All URLs are relative.
        1. The handling of user authentication is not specified. 
        2. The corresponding **token** endpoint is specified, it allows to initially get an access token or refresh it.  
      
      flows:
        authorizationCode:
          authorizationUrl: /oauth
          tokenUrl: /oauth/access
          refreshUrl: /oauth/access
          scopes:
            read: Allows to read resources.
            write: Allows to write resources (includes read scope).
            manage: Allows to manage extended functionality of the API, 
             currently only subscription interfaces (includes read/write scope). 
    
    BearerAuthentication:
      type: http
      scheme: bearer
      bearerFormat: string
      description: |
        Usage of standard bearer authentication. 
        This security scheme is intended to be used when an access token (from the token endpoint) 
        is available to the client. For this see workflow described on clause authorization (/oauth/access token endpoint) 
        in this documentation. 
      
    BasicAuthentication:
      type: http
      scheme: basic
      description: |
        This security scheme uses the standard HTTP Basic Auth authorization flow.
        Use this one in local environments!
