openapi: 3.0.3

info:
  title: KNX IoT 3rd Party API
  version: 2.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 timeseries 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.

    ## Versioning and Relations
    The here expressed API version (OAS element **openapi** )
    - is also included in the response of the node/server version information, for this see on details of EP /.well-known/knx 
    - corresponds to the KNX specification 3/10/4 with the version 2.2.x 
     
    Both versions mentioned above follows the Semantic Versioning Specification (major.minor.patch). The API version and/or 
    KNX specification 3/10/4 version may get independent minor or patch updates, hence the .minor/.patch versions will not be necessarily the same. 

    ## License
    The here provided electronic document follows the MIT license, see link __MIT License__ below. 
    The corresponding license text is defined as follows.
    ___
    **Copyright 2023, KNX Association, Brussels-Diegem, Belgium**
    
    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), 
    to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
    and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    ___
    
    ## Version History

    - `1.0.- | 05.07.2021 | initial version`  
    - `2.0.0 | 10.04.2022 | updated endpoint content, query filter and resource attributes`  
    - `2.1.0 | 13.07.2023 | approved standard, main changes are the update of value type "object" definition, additional node subscription possibilities, improved details for the link behavior` 
    - `2.1.0 | 31.07.2023 | detailed versioning description, added (optional) JSON member and OAS security scheme for linter check, added some add. HTTP response codes for WebSocket`


  termsOfService: https://www.knx.org/knx-en/privacy
  contact:
    name: KNX Association cvba
    email: support@knx.org
    x-compatible-knx-ontologies:
      - name: v2
        url: http://schema.knx.org/2020/ontology/v2
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT

servers:
  - url: "{protocol}://{authority}/{path}"
    variables:
      protocol:
        description: The protocol selection is always https.
          - in the public environment (WAN) with OAuth2 TLS is mandatory
          - in the local  environment (LAN) with Basic Authentication TLS is mandatory
        enum: [https]
        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 security /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.
  - name: timeseries
    description: Endpoints handling timeseries data.  

paths:
  /.well-known/knx/idevid:
    get: 
      tags:
        - authorization
      summary: Read manufacturer device certificate.
      description: |
        # General
        List the manufacturer device certificate, details see below.

        # Details
        The endpoint MUST be accessible without any defined scope from the resource endpoints (manage/read/write), 
        the authentication method/data depends on the chosen OAuth2 grant types. It is secured with OAuth2. 
        To access it the authorization request MAY contain no scope at all or it reuses known scopes such as __profile__ from 
        OpenID Connect, this is vendor specific. As a result an access token is issued that grants a general access from the user.
        Transport security is mandatory.

        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.

        ## Implementation Details
        LDevID > the operational certificate for the device
        IDevID > the manufacturer factory default setup certificate for the device

        This specification does not define how to configure the LDevID/IDevID certificate at the server. 

        ### Public Environment
        In a public environment the certificate is specified according to RFC 5280. 
                
        - The LDevID certificate MUST be supported.
        - The IDevID certificate is not applicable.
        
        The certificate MUST contain at least the basic certificate fields as specified in the written AN.  

        ### Local Environment
        In a local environment the certificate is specified according to IEEE 802.1AR-2018. 
        
        - The LDevID certificate MAY be supported.
        - The IDevID certificate MUST be supported. 

        LDevID certificates MUST NOT use of wildcards in the subject CN or SAN extension field, 
        moreover, the certificate SHALL not include more than one SAN extension field. 

        LDevID certificates MUST be dropped in case of a master reset of the KNX IoT 3rd Party API server.

        In case no (operational) LDevID certificate is configured, the KNX IoT 3rd Party API server 
        MUST use the IDevID certificate for the Secure Communication (TLS session).  
      operationId: readIDevID
      responses:
        "200":
          $ref: "#/components/responses/NodeCertificate"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: []

  /.well-known/knx/ldevid:
    get: 
      tags:
        - authorization
      summary: Read operational device certificate.
      description: |
        # General
        List the operational device certificate, details see below.

        # Details
        The endpoint MUST be accessible without any defined scope from the resource endpoints (manage/read/write), 
        the authentication method/data depends on the chosen OAuth2 grant types. It is secured with OAuth2. 
        To access it the authorization request MAY contain no scope at all or it reuses known scopes such as __profile__ from 
        OpenID Connect, this is vendor specific. As a result, an access token is issued that grants a general access from the user.
        Transport security is mandatory.
        
        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.   

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.

        ## Implementation Details
        LDevID > the operational certificate for the device
        IDevID > the manufacturer factory default setup certificate for the device

        This specification does not define how to configure the LDevID/IDevID certificate at the server. 

        ### Public Environment
        In a public environment the certificate is specified according to RFC 5280. 
                
        - The LDevID certificate MUST be supported.
        - The IDevID certificate is not applicable.
        
        The certificate MUST contain at least the basic certificate fields as specified in the written AN.  

        ### Local Environment
        In a local environment the certificate is specified according to IEEE 802.1AR-2018. 
        
        - The LDevID certificate MAY be supported.
        - The IDevID certificate MUST be supported. 

        LDevID certificates MUST NOT use of wildcards in the subject CN or SAN extension field, 
        moreover the certificate SHALL not include more than one SAN extension field. 

        LDevID certificates MUST be dropped in case of a master reset of the KNX IoT 3rd Party API server.

        In case no (operational) LDevID certificate is configured, the KNX IoT 3rd Party API server 
        MUST use the IDevID certificate for the Secure Communication (TLS session).          
      operationId: readLDevID
      responses:
        "200":
          $ref: "#/components/responses/NodeCertificate"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: []

  /.well-known/knx:
    get:
      summary: List API 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 be accessible without any defined scope from the resource endpoints (manage/read/write), 
        the authentication method/data depends on the chosen OAuth2 grant types. It is secured with OAuth2. 
        To access it the authorization request MAY contain no scope at all or it reuses known scopes such as __profile__ from 
        OpenID Connect, this is vendor specific. As a result, an access token is issued that grants a general access from the user.
        Transport security is mandatory.

        A client can discover API versions and the server entry endpoints.

        ## Implementation Details
        The URL for this endpoint MUST not contain any API base member (URL path element). 
      servers:
        - url: "{protocol}://{authority}"
          variables:
            protocol:
              description: The protocol selection is always https with a Basic Authentication.
              enum: [https]
              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/WellKnownKNX200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "403":
          $ref: "#/components/responses/httpStatusForbidden"  
        "404":
          $ref: "#/components/responses/httpStatusNotFound"  
        "406":
          $ref: "#/components/responses/httpStatusNotAcceptable"
        "409":
          $ref: "#/components/responses/httpStatusConflict"
        "414":
          $ref: "#/components/responses/httpStatusURITooLong"
        "415":
          $ref: "#/components/responses/httpStatusUnsupportedContentFormat"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: []

  /oauth/access:
    post:
      summary: Handles the authorization management.
      description: |
        # General
        Retrieve an access token to access a protected resource using OAuth2. 
        
        # Details
        The endpoint MUST be accessible without any defined scope from the resource endpoints (manage/read/write), 
        the authentication method/data depends on the chosen OAuth2 grant types. Transport security is mandatory.   

        An (beforehand) authenticated client/user obtains from this OAuth2 *token endpoint* - hosted on the 
        **authorization server** - an authorization grant in form of an access token (that can be refreshed by using 
        a refresh token). The endpoint URL is the same to initially get an access token or refresh an access token.
        
        ## Security Methods
        
        To ensure secured access to the (protected) resource endpoints the following security frameworks are used in a public 
        (WAN) and local (LAN) environment, where explicitly needed also defined with a corresponding security schema in this file.  
        - OAuth2 (RFC 6749) -> Scopes, Authorization Code Grant, Client Credentials Grant, ...
        - Bearer Token Usage (RFC 6750), clause 2.1  -> access to the protected resource endpoints
        - Basic Authentication Scheme (RFC 7617) -> access to the OAuth2 token endpoint + /.well-known/knx* endpoints 
        
        How a client/user obtains authorization from the resource owner (OAuth2 *authorization endpoint*) is out of scope 
        for this API (only the OAuth2 *authorization endpoint* URL is specified, see API security scheme definitions). 
              
        To access a **protected** resource at the **resource server** each endpoint has its security setting that defines the 
        intended (OAuth2) access scopes (scopes specified as part of the OAuth2 security scheme in this file). 
        
        - From this **token endpoint** retrieved access tokens are bound to the permission granted by the defined access scope.
        - The access token _type_ is specified as a `Bearer` token, format is string, no further explicit meaning such as on a JWT. 
        - The refresh token _type_ is specified as a string, no further explicit meaning.
        
        The Format UUID is not recommended for a token, this weakens the security because of predictable format and content. 
        As a note, not all endpoints requires an authentication respectively security schema, such as /.well-known and others, 
        for this look at the defined at the endpoints. 
               
        ## Workflow
        To access a protected resource at the resource server the clients perform the following steps. 

        - **STEP 1** : The client accesses the token endpoint (at the authorization server) to 
                       get initially an access token or refresh an existing one.  

        - **STEP 2** : Each time the client accesses a protected resource (at the resource server) it uses the above retrieved (OAuth2) 
                       access token with Bearer Authentication Scheme as `Bearer` token, included in the HTTP request Authorization header. 
                       
        ## Note
        The _Authorization_ header parameter and the Bearer Authentication Scheme is NOT explicitly specified per defined resource 
        server endpoint in this file. This must be added in addition to the request. 
        
        - The commonly used _Authorization_ header parameter belongs to HTTP, not specified further here. Only functionally required 
          header parameter described in this file.
        
        - To describe the involved security schemes (OAuth2 with corresponding scopes + Bearer Authentication Scheme) at once per 
          endpoint, it is not possible to express this in OpenAPI for the here intended purpose.   

      tags:
        - authorization
      operationId: getOauthToken
      requestBody:
        description: |
          As described in clause **Details** above the endpoint supports two scenarios.
          ### retrieve access token
          
          #### authorization grant
          It returns an access token, using the following input parameters:
          - grant_type (`authorization_code`)
          - code (retrieved from authorization server)
          - redirect_uri 
          - client_id
        
          As implementers note, according to RFC clause 4.1.3: 
          - the client MUST be authenticated with the authorization server
          - the _redirect_uri_ is mandatory, if it was included in the authorization request (to compare it) 
          - the _client_id_ is mandatory, if the client is not authenticating with the authorization server
            
            Depending on the OAuth2 (confidential, public) client type the _client_id_ may needed as be part of
            the request. Moreover, the _Authorization_ header parameter is not used in case of a public client.  

          The intended (access) scope is reflected via the parameter **code**, 
          the actual scope as such was part of the request to the authorization endpoint (handling of this EP is out of scope). 

          #### client credentials grant
          It returns an access token, using the following input parameters:
          - grant_type (`client_credentials`)
          - scope
        
          As implementers note, according to RFC clause 4.4.2: 
          - the client MUST be authenticated with the authorization server
            
          The intended (access) scope is reflected via the parameter **scope**, part of the request to this endpoint. 
          The scope can be a list, also defining vendor specific scopes (see examples).  
          
          ### refresh access token 
          It returns an new (refreshed) access token using the following input parameters:
          - grant_type (`refresh_token`)
          - refresh_token
          
          As implementers note, according to RFC clause 5: 
          - the client MUST be authenticated with the authorization server
          
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/oAuth2AccessTokenAuthorizationGrant.json"
                - $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/oAuth2AccessTokenClientCredentialsGrant.json"
                - $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/oAuth2RefreshToken.json"
            examples:
              Runtime1:
                summary: Runtime (get access token, authorization code grant)
                description: Retrieve an access token with a **Authorization Code Grant**. 
                  The client_id is not used in this example; the client is authenticated. 
                value:
                  grant_type: authorization_code
                  code: IamAnArbitraryAuthorizationCodeString
                  redirect_uri: http://localhost:8080/client_app/cb  
              Runtime2:
                summary: Runtime (get access token, client credentials grant)
                description: Retrieve an access token with a **Client Credentials Grant**. 
                value:
                  grant_type: client_credentials
                  scope: read
              Runtime3:
                summary: Runtime (refresh access token)
                description: Refresh an access token.   
                value:
                  grant_type: refresh_token
                  refresh_token: IamAnArbitraryRefreshTokenString
              Runtime4:
                summary: Runtime (get access token, client credentials grant, vendor scope)
                description: Retrieve an access token with a **Client Credentials Grant**. A vendor defined scope is included that 
                             was explicitly defined from the vendor to limit the lifetime (1h) of the returned access token.
                value:
                  grant_type: client_credentials
                  scope: write time_3600         
      responses:
        "200":
          $ref: "#/components/responses/Access200"
        "400":
          $ref: "#/components/responses/httpStatusBadRequestOAuth2"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: 
        - BasicAuthentication: []   
        - {}  
  
  /node:
    get:
      summary: List node information.
      description: |
        # General
        List all available information of this (server) node.

        # Notes
        The node exits only with one instance.       

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        The server MUST ignore page-based pagination query parameters, if part of the client request.

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: getNode
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          
 
  /devices:
    get:
      summary: List devices.
      description: |
        # General
        List all available devices of the installation.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.   
      tags:
        - device
      operationId: listDevices
      parameters:
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize" 
        - $ref: "#/components/parameters/typeFilter"    
        - $ref: "#/components/parameters/tagFilter" 
        - $ref: "#/components/parameters/attributeFilter"  
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.    
        The server MUST ignore page-based pagination query parameters, if part of the client request.    

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
        
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model. 
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - device
      operationId: getDevice
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          
      
  /locations/{locationId}/devices:
    get:
      summary: List the devices of a location.
      description: |
        # General
        List all available devices of a specific location.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
    
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - device
      operationId: listDevicesOfLocation
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize" 
        - $ref: "#/components/parameters/typeFilter"  
        - $ref: "#/components/parameters/tagFilter" 
        - $ref: "#/components/parameters/attributeFilter"        
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          
 
  /installations:
    get:
      summary: List installations.
      description: |
        # General
        List all available installations.
     
        # Notes
        All in this API specified endpoints returning data that comprises all installations, contained in the node. 
        As an example, the endpoint /datapoints returns all datapoints from all installations of the node at once. 
        There is no possibility to differentiate between datapoints from one or the other installation. 
        This reflects the client perspective of one big (merged) installation, 
        with the possibility to use the below described endpoints to fetch at least the originating installations. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
        
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: listInstallations
      parameters: 
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"    
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.   
        The server MUST ignore page-based pagination query parameters, if part of the client request.     

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          

  /sites:
    get:
      summary: List the 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 superordinate site(s), but subordinated floor, rooms, ...)

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: listSites
      parameters:
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize" 
        - $ref: "#/components/parameters/typeFilter"     
        - $ref: "#/components/parameters/tagFilter"
        - $ref: "#/components/parameters/attributeFilter"          
      responses:
        "200":
          $ref: "#/components/responses/SiteCollection200"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: listLocations
      parameters:
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"
        - $ref: "#/components/parameters/typeFilter"     
        - $ref: "#/components/parameters/tagFilter"
        - $ref: "#/components/parameters/attributeFilter"               
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.     
        The server MUST ignore page-based pagination query parameters, if part of the client request.  

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
             
       
  /devices/{deviceId}/location:
    get:
      summary: List the location of a device.
      description: |
        # General
        List the location information where a specific device is hosted.
        
        # Note
        An individual device is typically only hosted in one single location.        

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.      

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.

        This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
        if the device has no assembly location at all.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: getDeviceLocation
      parameters:
        - $ref: "#/components/parameters/deviceId"
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
             

  /functions/{functionId}/location:
    get:
      summary: List the location of a function.
      description: |
        # General
        List the location information that is hosting a specific function.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.   
        The server MUST ignore page-based pagination query parameters, if part of the client request.      

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.

        This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
        if the function is not related to a location all (such as when the location may be deleted by other means). 
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: getFunctionLocation
      parameters:
        - $ref: "#/components/parameters/functionId"
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
             
  
  /locations/{locationId}/parentlocation:
    get:
      summary: List the parent location of a location.
      description: |
        # General
        List the parent location of a specific location. 

        # Notes
        It may be the case that no parent locations is present.
        
        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.     
        The server MUST ignore page-based pagination query parameters, if part of the client request.   

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.  

        This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
        if the location has no parent location at all.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: getParentLocation
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
             
  
  /locations/{locationId}/childlocations:
    get:
      summary: List the child locations of a location.
      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).

        # Notes
        It may be the case that no child locations are present. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - location
      operationId: listChildLocations
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"
        - $ref: "#/components/parameters/typeFilter"     
        - $ref: "#/components/parameters/tagFilter"     
        - $ref: "#/components/parameters/attributeFilter"     
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.       

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: listFunctions
      parameters:
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/tagFilter"    
        - $ref: "#/components/parameters/attributeFilter"            
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.   

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          
  
  /timeseries/{timeseriesId}:
    get:
      summary: List a single time series entry.
      description: |
        # General
        List all available information of a specific timeseries entry.
        
        # Notes
        The endpoint as such represents a pool of individual timeseries values of all datapoints.  
        A single time series entry is defined as a point in time where a successful write access to a datapoint occurred
        (don't care of the value). The response carries (one) datapoint value and the corresponding timestamp 
        (including a relation to the corresponding datapoint). 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.   

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - timeseries
      operationId: getTimeseries
      parameters:
        - $ref:  "#/components/parameters/timeseriesId"         
      responses:
        "200":
          $ref:  "#/components/responses/Timeseries200"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
             
          
  /timeseries/{timeseriesId}/datapoint:
    get:
      summary: List a single datapoint.
      description: |
        # General
        List the datapoint that is related to a timeseries entry. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.

        This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
        when the timeseries is not related to a datapoint (such as when the corresponding datapoint may be deleted by other means). 
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: getTimeseriesDatapoint
      parameters:
        - $ref: "#/components/parameters/timeseriesId"
    
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
                  
  
  /locations/{locationId}/functions:
    get:
      summary: List the functions of a location.
      description: |
        # General
        List all available functions of a specific location.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.        

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: listFunctionsOfLocation
      parameters:
        - $ref: "#/components/parameters/locationId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"  
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/tagFilter"  
        - $ref: "#/components/parameters/attributeFilter"            
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          
       
  /datapoints/{datapointId}/functions:
    get:
      summary: List the functions of a datapoint.
      description: |
        # General
        List all functions where a specific datapoint is contributing to. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.       

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - function
      operationId: listFunctionsOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/tagFilter"

        - $ref: "#/components/parameters/attributeFilter"    
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]

  /datapoints/{datapointId}/datafields:
    get:
      summary: List the datafields of a datapoint.
      description: |
        # General
        List all datafields as part of the type definition for a datapoint. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.       

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - information
      operationId: listDatafieldsOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"  
      responses:
        "200":
          $ref: "#/components/responses/DatafieldCollection200"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]       

  /datapoints/{datapointId}/proxies:
    get:
      summary: List the proxies of a datapoint.
      description: |
        # General
        List all (device) proxies where a specific datapoint is proxied. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200. 
      tags:
        - device
      operationId: listProxiesOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"  
        - $ref: "#/components/parameters/tagFilter"   
        - $ref: "#/components/parameters/attributeFilter"    
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          
  
  /datapoints/{datapointId}/device:
    get:
      summary: List a single device.
      description: |
        # General
        List the device where a specific datapoint is hosted in.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.        
        The server MUST ignore page-based pagination query parameters, if part of the client request.

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.

        This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
        if the datapoint is not related to a device at all (such as when the datapoint is related to a function). 
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - device
      operationId: getDatapointDevice
      parameters:
        - $ref: "#/components/parameters/datapointId"
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          
  
  /datapoints:
    get:
      summary: List datapoints.
      description: |
        # General
        List all available datapoints of the installation.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.        

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships  (relative links from primary data to other resources)   )
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapoints
      parameters:        
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"
        - $ref: "#/components/parameters/typeFilter"  
        - $ref: "#/components/parameters/tagFilter"  
        - $ref: "#/components/parameters/attributeFilter" 
        - $ref: "#/components/parameters/timeFilter"           
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "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: [read]
          
  
  /datapoints/{datapointId}/timeseries:      
    get:
      summary: List the timeseries of a datapoint.
      description: |
        # General
        List the timeseries of a datapoint, with all values written over time (each as a value/time pair). 
        To filter a range it is possible to specify a time series or a point in time (from/to). 

        # Notes
        If a IoT Datapoint was never written no timeseries value exists, this results in an response 
        with no time series objects (and no `attributes` member, provided no other properties are expressed).   

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.    
        The server MUST ignore page-based pagination query parameters, if part of the client request.    

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics(resource object properties) 
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - timeseries
      operationId: listDatapointValues
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"  
        - $ref: "#/components/parameters/timeFilter" 
      responses:
        "200":
          $ref: "#/components/responses/TimeseriesCollection200"
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.  
        The server MUST ignore page-based pagination query parameters, if part of the client request.      

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [read]
          

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

        # Details
        Datapoint may have a numbered or an enumeration 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 (value 320 as 8-bit)
        - a text type value is not representable in its range ("ax" to a text of len 1)
        - an enumeration type value (or ist corresponding number) is not part 
          of the servers list of enumeration/number values ("put on" for a type with "on" and "off" only)   
      tags:
        - datapoint
      operationId: updateDatapoints
      requestBody:
        $ref: "#/components/requestBodies/datapointValuesPut"
      responses:
        "202":
          description: Accepted, but not processed yet.
        "204":
          description: No Content. 
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfFunction
      parameters:
        - $ref: "#/components/parameters/functionId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"    
        - $ref: "#/components/parameters/typeFilter" 
        - $ref: "#/components/parameters/tagFilter"    
        - $ref: "#/components/parameters/attributeFilter"    
        - $ref: "#/components/parameters/timeFilter"   
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
          

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfDevice
      parameters:
        - $ref: "#/components/parameters/deviceId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"    
        - $ref: "#/components/parameters/typeFilter"  
        - $ref: "#/components/parameters/tagFilter"     
        - $ref: "#/components/parameters/attributeFilter" 
        - $ref: "#/components/parameters/timeFilter"     
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]
   
  /datafields/{datafieldId}/datapoints:
    get:
      summary: List the datapoints using a specific datafield.
      description: |
        # General
        List all available datapoints using a specific datafield as part of the type definition.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.         

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfDatafield
      parameters:
        - $ref: "#/components/parameters/datafieldId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"    
        - $ref: "#/components/parameters/typeFilter"  
        - $ref: "#/components/parameters/tagFilter"     
        - $ref: "#/components/parameters/attributeFilter" 
        - $ref: "#/components/parameters/timeFilter"     
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [read]      

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

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.     
        The server MUST ignore page-based pagination query parameters, if part of the client request.  
       
        ## JSON API Member
        The following member are used as part of the request.

        ### Top Level
        
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
        
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.

        ## Implementation Details
        With this access method you cannot retrieve a full list of all  - to a subscription belonging/ upon subscribed - datapoints. 
        This is resolvable via the endpoint subscriptions/{id}/datapoints.

        Examples, see **Runtime** example on status code 200.
      tags:
        - subscription
      operationId: listSubscriptionsOfDatapoint
      parameters:
        - $ref: "#/components/parameters/datapointId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"   
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [manage]
          

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

        # Details
        As specified in JSON API at least one of the members `meta`, `data` or `error`must be present. 
        The server MUST ignore page-based pagination query parameters, if part of the client request.       
        
        ### JSON API Member
        The following member are used as part of the response:
        
        -  `meta` > as top level member > if expressed it contains a reason in case no subscription item is available 
        -  `data` > as top level member > contains the individual items; as general member > currently not explicitly used 
        -  `attributes` > as general member > contains item characteristics (resource object properties)) 
        -  `relationships` > as general member > contains item relationships (relative links from primary data to other resources) 
         
        1. If used, the JSON API **top** level member `data` MUST be always expressed, even on not present items (see JSON API).
        2. If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
           the member MUST NOT be expressed. 

        ### Attributes / Relationships
        For this item type the `attributes` and `relationships` section cannot be empty,  
        at least one mandatory relationship or attribute is present for an item.
        This is reflected with the **_required_** definition in the scheme, see also response examples.

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

        ## Implementation Details
        With this access method you cannot retrieve a full list of all  - to a subscription belonging/ upon subscribed - datapoints. 
        This is resolvable via the endpoint subscriptions/{id}/datapoints.
        
        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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [manage]
          
     
    delete:
      summary: Deletes a (HTTP callback) subscription.
      description: |
        # General
        An individual HTTP callback 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: No Content. 
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [manage]
          

    patch:
      summary: Updates a (HTTP callback) subscription.
      description: |
        # General
        Some **parts** of an individual (existing) HTTP callback subscription will be updated 
        on the server (therefore PATCH, see also https://jsonapi.org/faq/#wheres-put ). 

        # Details
        As specified in JSON API at least one of the members `meta`, `data` or `error`must be present. 
        The server MUST ignore page-based pagination query parameters, if part of the client request.       
        
        ### JSON API Member
        The following member are used as part of the response:
        
        -  `meta` > as top level member > if expressed it contains a reason in case no subscription item is available 
        -  `data` > as top level member > contains the individual items; as general member > currently not explicitly used 
        -  `attributes` > as general member > contains item characteristics (resource object properties)) 
        -  `relationships` > as general member > contains item relationships (relative links from primary data to other resources) 
         
        1. If used, the JSON API **top** level member `data` MUST be always expressed, even on not present items (see JSON API).
        2. If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
           the member MUST NOT be expressed. 

        ### Attributes / Relationships
        For this item type the `attributes` and `relationships` section cannot be empty,  
        at least one mandatory relationship or attribute is present for an item.
        This is reflected with the **_required_** definition in the scheme, see also response examples.

        - KNX vendor specific attributes/ relationships MUST be expressed with its (predefined) corresponding namespace identifier.  
        - Not in this API specified attributes/ relationships from the KNX information model SHOULD be expressed 
          with its corresponding data property name from the KNX information model.
        
        ## Implementation Details
        It must be ensured that updated/overwritten (not touched) properties do not impact the current operational state.
        - url (may need to change)
        - secret (may need to change) 
        - caCert (a subscription may expire and needs to be refreshed) 
        - lifetime (may need to change) 
        
        With this access method it is not possible to perform the following tasks:
        - add new (to be subscribed upon) items to the existing subscription
        - overwrite the current _subscription notification characteristics_

        A full reconfiguration of an (individual) subscription is only possible with 
        the deletion of the current subscription and a re-creation of a new subscription.

        Examples, see **Runtime** example on request body.
      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
            - `attributes` member > expressing subscription callback data
              - url
              - secret
              - caCert
              - lifetime

          ### Notes 
          For the handling of not present elements in the request body, 
          see <https://jsonapi.org/format/#crud-updating-resource-attributes>.
 
          The *content type* is as specified, but **application/json** is also allowed. 
          It is used as a fallback in case a client requests a similar format that the server can understand. To signal an error is not intended in such a case.     
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/SubscriptionUpdate.json"
            examples:
              Runtime1:
                $ref: "#/components/examples/SubscriptionPatchExample1"
              Runtime2:
                $ref: "#/components/examples/SubscriptionPatchExample2"  

      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"   
        "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: [manage]
          
        
  /subscriptions/{subscriptionId}/datapoints:
    get:
      summary: List the datapoints of a HTTP callback subscription.
      description: |
        # General
        List the datapoints included in a specific HTTP callback subscription.

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data. 
        A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.      

        ## JSON API Member
        The following member are used as part of the response.

        ### Top Level
        
        -  `meta` > contains information on the collection or on a single item 
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
        For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
      
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.
        
        Examples, see **Runtime** example on status code 200.
      tags:
        - datapoint
      operationId: listDatapointsOfSubscription
      parameters:
        - $ref: "#/components/parameters/subscriptionId"
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize" 
        - $ref: "#/components/parameters/typeFilter"   
        - $ref: "#/components/parameters/tagFilter"    
        - $ref: "#/components/parameters/attributeFilter"  
        - $ref: "#/components/parameters/timeFilter"            
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [manage]

  /subscriptions/{subscriptionId}/installations:
      get:
        summary: List the installations of a HTTP callback subscription.
        description: |
          # General
          List the installations included in a specific HTTP callback subscription.

          # Details
          As specified in JSON API some members must be present on root level of primary (request/ response) data. 
          A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.      

          ## JSON API Member
          The following member are used as part of the response.

          ### Top Level
          
          -  `meta` > contains information on the collection or on a single item 
          -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
          
          For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
          For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.
        
          ### General Member
    
          -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
          -  `attributes` > contains item characteristics (resource object properties)
          -  `relationships` > contains item relationships (relative links from primary data to other resources)
          -  `meta` > contains additional item information (type information and links) 
          
          If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
          the member MUST NOT be expressed. 

          ### Member Properties
          The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
          In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

          Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

          - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
            
          - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
            with the corresponding namespace identifier from the KNX information model.
          
          In case the member value is originated from a project, the namespace identifier is MaC specific. 
          Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
          Properties may also cover complex data structures involving JSON objects, 
          here the content MUST follow the definitions from above.  
          
          Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
          does not allow links or relationships member. In situations where this is needed to express, the general member 
          `meta` SHOULD be used in addition.
          
          Examples, see **Runtime** example on status code 200.
        tags:
          - information
        operationId: listInstallationsOfSubscription
        parameters:
          - $ref: "#/components/parameters/subscriptionId"
          - $ref: "#/components/parameters/collectionPage"
          - $ref: "#/components/parameters/collectionSize" 
        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"
          "422":
            $ref: "#/components/responses/UnprocessableEntity"  
          "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: [manage]
  
  /subscriptions/{subscriptionId}/node:
      get:
        summary: List the node of a HTTP callback subscription.
        description: |
          # General
          List the node included in a specific HTTP callback subscription.

          # Details
          As specified in JSON API some members must be present on root level of primary (request/ response) data. 
          A page-based pagination strategy allows to limit the number of returned items per response or to skip items before reading.      

          ## JSON API Member
          The following member are used as part of the response.

          ### Top Level
          
          -  `meta` > contains information on the collection or on a single item 
          -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
          
          For an collection the **top** level member `meta` MUST be always expressed with its members, even on empty collections.
          For an single item the **top** level member `meta` MAY be used, such as to add information why it is not present.

          This endpoint addresses a single item, hence the **top** level member `data` MAY be null, 
          if the subscription is not related to a node at all. 
        
          ### General Member
    
          -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
          -  `attributes` > contains item characteristics (resource object properties)
          -  `relationships` > contains item relationships (relative links from primary data to other resources)
          -  `meta` > contains additional item information (type information and links) 
          
          If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
          the member MUST NOT be expressed. 

          ### Member Properties
          The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
          In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

          Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

          - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
            
          - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
            with the corresponding namespace identifier from the KNX information model.
          
          In case the member value is originated from a project, the namespace identifier is MaC specific. 
          Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
          Properties may also cover complex data structures involving JSON objects, 
          here the content MUST follow the definitions from above.  
          
          Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
          does not allow links or relationships member. In situations where this is needed to express, the general member 
          `meta` SHOULD be used in addition.
          
          Examples, see **Runtime** example on status code 200.
        tags:
          - information
        operationId: listNodeOfSubscription
        parameters:
          - $ref: "#/components/parameters/subscriptionId"
        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"
          "422":
            $ref: "#/components/responses/UnprocessableEntity"  
          "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: [manage]

  /subscriptions:
    get:
      summary: List (HTTP callback) subscriptions.
      description: |
        # General
        List all available HTTP callback subscriptions of the node.          

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.     
        The server MUST ignore page-based pagination query parameters, if part of the client request.  
       
        ## JSON API Member
        The following member are used as part of the request.

        ### Top Level
        
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.

        ## Implementation Details
        
        
        With this access method you cannot retrieve a full list of all  - to a subscription belonging/ upon subscribed - datapoints. 
        This is resolvable via the endpoint subscriptions/{id}/datapoints.

        Examples, see **Runtime** example on status code 200.
      tags:
        - subscription
      operationId: listSubscriptions
      parameters:
        - $ref: "#/components/parameters/collectionPage"
        - $ref: "#/components/parameters/collectionSize"   
      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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "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: [manage]
          
    post:
      summary: Creates a (HTTP callback) subscription.
      description: |
        # General
        An individual HTTP callback subscription will be created at the server, as a result a subscription **id** is generated
        that belongs to all to this subscription involved datapoints. 

        # Details
        As specified in JSON API some members must be present on root level of primary (request/ response) data.     
        The server MUST ignore page-based pagination query parameters if part of the client request.  
       
        ## JSON API Member
        The following member are used as part of the request.

        ### Top Level
        
        -  `data` > contains the individual items, each MUST include < type > and - except when generate an item - also an < id >
        
        ### General Member
  
        -  `data` > to express one or more items to be subscribed upon (used for subscriptions)
        -  `attributes` > contains item characteristics (resource object properties)
        -  `relationships` > contains item relationships (relative links from primary data to other resources)
        -  `meta` > contains additional item information (type information and links) 
         
        If no specific information will be available for an item as part of a JSON API **general** member (such as `attributes`), 
        the member MUST NOT be expressed. 

        ### Member Properties
        The general member as described above MAY be empty, otherwise at least one mandatory property is present for an item.
        In this case this is reflected with the **_required_** definition in the scheme, see also response examples.

        Underneath defined rules to use namespace identifiers ensures the unambiguity of properties and its values. 

        - The member name and value of KNX vendor specific properties SHOULD be expressed with the corresponding namespace identifier. 
          
        - The member name and value of not in this API specified properties from the KNX information model MUST be expressed 
          with the corresponding namespace identifier from the KNX information model.
        
        In case the member value is originated from a project, the namespace identifier is MaC specific. 
        Member values MAY be expressed as a full IRI, for the member names this is NOT RECOMMENDED.  
        Properties may also cover complex data structures involving JSON objects, 
        here the content MUST follow the definitions from above.  
        
        Both property types from above placed in the general member `attributes`, JSON API `attributes` section 
        does not allow links or relationships member. In situations where this is needed to express, the general member 
        `meta` SHOULD be used in addition.

        ## Implementation Details
        The subscription **request** contains:
        
        1. at least one item to be subscribed upon, this can be:
          - a datapoint (one ore more), either addressed directly or items that contain datapoints
          - a node (one)
          - an installation (one ore more)
        
        2. the callback URL, shared secret, optional certificate and optional lifetime

        ### request body
        An array to bundle the to be upon subscribed items from above, each item with its individual type (such as location, datapoint, 
        node device or installation). 

        ### subscription notification characteristics
        
        #### datapoints
        The boolean `meta` member `expand` may be used to define the notification behavior **per** resource item:
          
        - true:  a notification comprises an occurred datapoint write access for all subordinated resources and its assigned datapoints
        - false: a notification comprises an occurred datapoint write access only for directly to the resources assigned datapoints, 
                 this is also the server default behavior for all subscriptions and its including items.
                
        The default behavior is applied if the member `expand` is missing. The value true will only affect items of resource type
        **location**, on all other resource types the server behaves with the default behavior. 
        Moreover, it is not possible to return this information when reading a subscription. 

        #### node
        The boolean `meta` member `expand` may be used to define the notification behavior of the node resource item:
          
        - true:  a notification comprises changes to the node and all installations hosted at this node
        - false: a notification comprises changes to the node, 
                 this is also the server default behavior for all subscriptions and its including items.
                
        The default behavior is applied if the member `expand` is missing. The value true will affect items of resource type 
        **device** or **service** (the two node variants). 
        Moreover, it is not possible to return this information when reading a subscription.   

        ### Notes
        As a note, the expanded behavior (true) results in individual notification messages for the *node* and *installation*. 
        An notification message may combine changes for both in one message. 
        
        Examples, see on status code 200.
      tags:
        - subscription
      operationId: createSubscription
      requestBody:
        description: |
          Subscription message data, containing of (JSON API) member:
          - `data` member > includes a relation to the collection of (to be upon subscribed) items
            - type
            - id is not present, it will be generated at the server
    
          - `attributes` member > expressing subscription callback data
            - url
            - secret
            - caCert
            - lifetime

          - `relationships` member > with at least one item to be subscribed upon
            - subscriptionDatapoints/data (data is a non-top level `data` member as an array of items containing datapoints) 
            - subscriptionNode/data (data is a non-top level `data` member as an object with a single node item)
            - subscriptionInstallations/data (data is a non-top level `data` member as an array of installations items)
            
            At least one of the relationships must be present in a request. 
            
          ### Notes
          The *content type* is as specified, but **application/json** is also allowed. 
          It is used as a fallback in case a client requests a similar format that the server can understand. To signal an error is not intended in such a case. 
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/SubscribeRequest.json"
            examples:
              Datapoints:
                $ref: "#/components/examples/SubscribeUponDatapointsExample"
              Node:
                $ref: "#/components/examples/SubscribeUponNodeDefaultExample"  
              NodeExtended:
                $ref: "#/components/examples/SubscribeUponNodeExtendedExample"
              Installations:
                $ref: "#/components/examples/SubscribeUponInstallationsExample"  
              DatapointNode:
                $ref: "#/components/examples/SubscribeUponDatapointsNodeExample" 
      callbacks:
        datapoint_CoV_event:
          $ref: "#/components/callbacks/eventNotification"
      responses:
        "201":
          description: |
            The generated subscription id is returned, 
            depending on the used resource types from the subscription request one or more links to the subscription hosting: 
            - all included datapoints (member `subscriptionDatapoints`)
            - all included installations (member `subscriptionInstallations`)
            - the included node (member `subscriptionInstallations`)
          content:
            application/vnd.api+json:
              schema:
                $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/SubscribeResponse.json" 
              examples:
                Datapoints:
                  summary: Subscribe to datapoints
                  description: |
                    The example shows a subscription response in a local environment.  
                    The subscription callback data (normally part of **general** JSON API members `attributes`) 
                    are NOT returned at all. 
                  value:
                    data:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      type: subscription
                      relationships:
                         subscriptionDatapoints:
                           links:
                              related: /subscriptions/123e4567-e89b-12d3-a456-426614174000/datapoints     
                DatapointsNode:
                  summary: Subscribe to datapoints and node
                  description: |
                    The example shows a subscription response in a local environment.  
                    The subscription callback data (normally part of **general** JSON API members `attributes`) 
                    are NOT returned at all. 
                  value:
                    data:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      type: subscription
                      relationships:
                         subscriptionDatapoints:
                           links:
                              related: /subscriptions/123e4567-e89b-12d3-a456-426614174000/datapoints   
                         subscriptionNode:
                           links:
                              related: /subscriptions/123e4567-e89b-12d3-a456-426614174000/node    
          links: 
            getSubscriptionById:
              operationId: getSubscription 
              parameters: 
                subscriptionId: $response.body#/data/id
              description: "the in response returned **id** can be used as an input {subscriptionID} to get an individual subscription"  
        "202":
          description: Accepted, but not processed yet. 
        "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"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"  
        "429":
          $ref: "#/components/responses/httpStatusTooManyRequests"
        "500":
          $ref: "#/components/responses/httpStatusDefaultError"
        "501":
          $ref: "#/components/responses/httpStatusNotImplemented" 
        "503":
          $ref: "#/components/responses/httpServiceUnavailable"   
        "504":
          $ref: "#/components/responses/httpStatusRequestTimeout"
        "505":
          $ref: "#/components/responses/httpStatusVersion"
      security:
        - OAuth2: [manage]
          

  /messaging/ws:
    get:
      summary: Creates a (WebSocket) subscription.
      description: |
        # General
        Enables a bidirectional communication to establish subscriptions and notifications.

        # Notes
        The WebSocket communication pattern and data format is not expressed as API definition in this OAS (YAML) file.
        Major HTTP handshake response codes are defined below, the RFC 6455 defines some error handling with codes such as 400 (clause 4.2.1)
        , 401 ... 404. Other codes are possible, but not detailed in this file.

        # Details
        The endpoint allows to:
        - subscribe to CoV of datapoints 
        - read/write datapoint values
           
      tags:
        - subscription
      operationId: createWebsocket
      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. 
        "400":
          $ref: "#/components/responses/httpStatusBadRequest"
        "401":
          $ref: "#/components/responses/httpStatusUnauthorized"  
        "404":
          $ref: "#/components/responses/httpStatusNotFound"  
        "500":
          $ref: "#/components/responses/httpStatusInternalServerError"
        default:
          $ref: "#/components/responses/httpStatusDefaultError"
      security:  
        - OAuth2: [manage]
          

components:
  callbacks:
    eventNotification:
      "{$request.body#/attributes/url}":
        post:
          summary: Callback notification event
          description: |
            Invokes a callback of the subscribed items for the following changes:
            - a successful update of a datapoint; a write access with don't care if the value was changed
            - node property changes, including vendor specific properties; it is subject to a vendor to decide on which properties a notification is requested
            - installation property changes, including any other change of an installation; it is subject to a vendor to decide on which properties a notification is requested
            
            It uses the URL specified on the subscription call, defined as `attributes/url`member. Following headers are required:
              1. Host
              2. X-Callback-Signature
              3. Content-Length 
              4. Date
            
            Notes
            - Only #2 - as a non standardized HTTP header - is explicitly expressed as a header parameter in this file.   
            - Except from #2 there are no further security requirements defined for the callback as such, hence the below defined 
              security scheme for the callback is empty (#2 is not a specified OAS security scheme). The obligatory transport security (HTTPS) including 
              to handle certificates are common requirements of the KNX specification 3/10/4.
          operationId: callSubscriptionEvent
          parameters:
            - name: X-Callback-Signature
              in: header
              required: true
              description:
                A base64 encoded HMAC-SHA256 signature as a concatenation of the entire message request-line (including the CRLF), 
                HTTP header values of Host, Date, Content-Length, and the entire message body. 
                The secrecy key to generate the HMAC is part of the subscription request (secret member).
              schema:
                type: string
                format: PEM
          requestBody:
            description: |
              Event message data, containing of (JSON API) `data` member, specifying a a collection items, each with 
              - id
              - type (datapoint,node,installation)
              - self reference (as part of `links` member)
              - attributes members
                
                - For an datapoint the value/ time stamp members (at this point a write access happened), therefore the properties 
                  must be present/ available. There is no information of the datapoint type included in the event. 
                - For an installation some defined installation members, including vendor specific things. 
                - For an node some defined node members, including vendor specific things.   
              
              ### Notes      
              The *content type* is as specified, but **application/json** is also allowed.  
              It is used as a fallback in case a client requests a similar format that the server can understand. To signal an error is not intended in such a case.
            required: true
            content:
              application/vnd.api+json:
                schema:
                  $ref:  "https://schema.knx.org/2020/api/2.1.0/schemas/UpdateEvent.json"
                examples:
                  Datapoints:
                    $ref: "#/components/examples/UpdateEventDatapointsExample"
                  DatapointsNode:
                    $ref: "#/components/examples/UpdateEventDatapointsNodeExample"  
          responses:
            "200":
              description: The callback request was successfully communicated.
            "401":
              $ref: "#/components/responses/httpStatusUnauthorized"
            "405":
              $ref: "#/components/responses/httpStatusMethodNotAllowed"  
            "500":
              $ref: "#/components/responses/httpStatusDefaultError"
            "501":
              $ref: "#/components/responses/httpStatusNotImplemented"
            "505":
              $ref: "#/components/responses/httpStatusVersion"  
          security: []

  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 (mandatory)
        - token type (mandatory, here _Bearer_)
        - expiration (in RFC recommended, here mandatory)
        - refresh token (optional)
        - scope (optional, if identical to the scope requested by the client; otherwise required)
        
        According to RFC 6749, clause 5.1 the response payload must be conform with application/json.  
      content:
        application/json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Access.json"
          examples:
            Runtime1:
              summary: Runtime (Standard Token)
              description: | 
                A standard access token with a lifetime of 24 minutes. Additionally a refresh token. 
                The with this access token granted scope is **write**. 
              value:
                access_token: AccessTokenExample
                token_type: Bearer
                refresh_token: RefreshTokenExample
                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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"
    
    UnprocessableEntity:
      description: server understands the content type of the request entity, 
       and the syntax of the request entity is correct, but it was unable to process the contained instructions.
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Unprocessable Entity
                links: https://schema.knx.org/2020/api
                status: "422"
                detail: Syntax error. Unable to process the contained instructions.
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"        

    NodeCertificate:
      description: Node device X.509 certificate
      content:
        application/pkcs7-mime:
          schema:
            type: string
          example: <x.509v3 certificate>

    DataPoint200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > datapoint item, including:
          - id/ type
          - `attributes` member > expressing specific datapoint characteristics 
            
            The value is formatted as follows:
              
            - JSON string, containing: 
                1. enumerations (strings containing an individual enumeration value)
                2. numbers (strings containing a number value)
                3. strings (UTF-8 strings)
                4. strings (ISO8601 encoded strings)

            - JSON array, containing elements of #1 .. #4 from above

          - `meta` member > expressing additional meta information of the datapoint
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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
            - an endpoint providing all subscriptions where this datapoint is included in    
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Datapoint.json" 
          examples:
            Runtime0:
              $ref: "#/components/examples/DatapointItemEnumExample0"
            Runtime1:
              $ref: "#/components/examples/DatapointItemNumberExample1"  
            Runtime2:
              $ref: "#/components/examples/DatapointItemNumberExample2"  
            Runtime3:
              $ref: "#/components/examples/DatapointItemArrayExample3"   
            Runtime4:
              $ref: "#/components/examples/DatapointItemStringExample4"   
            

    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
          - `attributes` member > expressing specific datapoint characteristics
          
            The value is formatted as a JSON string, containing  types of: 
            1. enumerations, as strings containing an individual enumeration value
            2. numbers, as strings containing a number value
            3. strings, as UTF-8 strings
            4. strings, as ISO8601 encoded strings
            5. array of elements from #1 .. #4 above
            
          - `meta` member > expressing additional meta information of the datapoint
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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   
            - an endpoint providing the subscriptions where this datapoint is included in  
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/DatapointCollection.json"
          examples:
            Runtime:
              $ref: "#/components/examples/DataPointCollectionExample"

    Timeseries200: 
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of time series items, each including:
          - id/ type
          - `attributes` member > expressing specific time series characteristics
            - value/ timestamp
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the datapoint is related to this time series
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Timeseries.json" 
          examples:
            Runtime0:
              $ref: "#/components/examples/TimeseriesItemExample"
            Runtime1:
              $ref: "#/components/examples/TimeseriesArrayExample"  

    TimeseriesCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of time series items, each including:
          - id/ type
          - `attributes` member > expressing specific time series characteristics
            - value/ timestamp
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the datapoint is related to this time series 
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/TimeseriesCollection.json"
          examples:
            Runtime:
              $ref: "#/components/examples/TimeseriesCollectionExample"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    Device200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > device item, including:
          - id/ type
          - `attributes` member > expressing specific device characteristics
          - `meta` member > expressing additional meta information of the device
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the (assembly) location hosting this device
            - an endpoint providing the datapoints included in this device
      
        The content for a single device item is defined to be nullable, meaning the returned `data` member may be null. 
        This may occur on specific (relationships) endpoints, for this please consult the corresponding endpoints (or below example).   
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Device.json"
          examples:
            Runtime1:
              $ref: "#/components/examples/DeviceItemExample1" 
            Runtime2:
              $ref: "#/components/examples/DeviceItemExample2" 
            Runtime3:
              $ref: "#/components/examples/DeviceItemExample3"

    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
          - `attributes` member > expressing specific device characteristics
          - `meta` member > expressing additional meta information of the device
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the (assembly) location where this device is included
            - an endpoint providing the datapoints included in this device          
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/DeviceCollection.json"
          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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    Function200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > function item, including:
          - id/ type
          - `attributes` member > expressing specific function characteristics
          - `meta` member > expressing additional meta information of the function
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the location where this function is included
            - an endpoint providing all datapoints included in this function    
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Function.json"
          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
          - `attributes` member > expressing specific function characteristics
          - `meta` member > expressing additional meta information of the function
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the location where this function is included
            - an endpoint providing all datapoints included in this function
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/FunctionCollection.json"
          examples:
            Runtime:
              $ref: "#/components/examples/FunctionCollectionExample"

    DatafieldCollection200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > collection information
        - `data` member > collection of datafield items, each including:
          - id/ type
          - specific datafield characteristics for numbered/enumeration/date/time/text types
            - description/ title, to explain the datafield  
            - value of the datafield, if available 
            - min/max ranges, resolution, float/integer classification for numbered types
            - array of key/value pairs, to map several enumeration values with its corresponding number values
            - charset scheme and length for text types
          - `relationships` member > a relationships section with links to:
            - an endpoint providing all datapoints using as specific datafield
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/DatafieldCollection.json"
          examples:
            Runtime0:
              $ref: "#/components/examples/DatafieldCollectionExample0"
    
    
    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    Installation200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > installation item, including:
          - id/ type
          - `attributes` member > expressing specific installation characteristics
          - `meta` member > expressing additional meta information of the installation
            - `typedescription` > an URL to additional information that hosts potentially human readable data
          - `relationships` member > a relationships section with links to: 
            - an endpoint providing all subscriptions where this installation is included in    
            
            As a note: 
            - with no typedescription relation expressed, the meta section is not present 
            - with no relation expressed, the relationships section is not present
      content:
        application/vnd.api+json:
          schema:
            $ref:  "https://schema.knx.org/2020/api/2.1.0/schemas/Installation.json"
          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
          - `attributes` member > expressing specific installation characteristics  
          - `meta` member > expressing additional meta information of the installation
            - `typedescription` > an URL to additional information that hosts potentially human readable data
          - `relationships` member > a relationships section with links to: 
            - an endpoint providing all subscriptions where this installation is included in    
            
            As a note: 
            - with no typedescription relation expressed, the meta section is not present 
            - with no relation expressed, the relationships section is not present 
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/InstallationCollection.json"
          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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    Location200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > location item, including:
          - id/ type
          - `attributes` member > expressing specific location characteristics 
          - `meta` member > expressing additional meta information of the location
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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     
            - an endpoint providing all devices included in this location    
         
        The content for a single location item is defined to be nullable, meaning the returned `data` member may be null. 
        This may occur on specific (relationships) endpoints, for this please consult the corresponding endpoints (or below example). 
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Location.json"
          examples:
            Runtime1:
              $ref: "#/components/examples/LocationItemExample1"
            Runtime2:
              $ref: "#/components/examples/LocationItemExample2"  
            Runtime3:
              $ref: "#/components/examples/LocationItemExample3"   

    LocationCollection200: # individual schema for the collection, the example differs compared to a child collection
      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
          - `attributes` member > expressing specific location characteristics 
          - `meta` member > expressing additional type information of the location
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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: "https://schema.knx.org/2020/api/2.1.0/schemas/LocationCollection.json"
          examples:
            Runtime:
              $ref: "#/components/examples/LocationCollectionExample"

    SiteCollection200: # individual schema for the collection, the example differs compared to a child collection
      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
          - `attributes` member > expressing specific location characteristics 
          - `meta` member > expressing additional type information of the location
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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: "https://schema.knx.org/2020/api/2.1.0/schemas/LocationCollection.json"
          examples:
            Runtime:
              $ref: "#/components/examples/SiteCollectionExample"  

    ChildLocationCollection200: # individual schema for the collection, the example differs compared to a location collection
      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
          - `attributes` member > expressing specific location characteristics
          - `meta` member > expressing additional type information of the location
            - `typedescription` > an URL to additional information that hosts potentially human readable data
            - `@type` > additional type information
          - `relationships` member > a relationships section with 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: "https://schema.knx.org/2020/api/2.1.0/schemas/LocationCollection.json"
          examples:
            Runtime1:
              $ref: "#/components/examples/ChildLocationCollectionExample1"
            Runtime2:
              $ref: "#/components/examples/ChildLocationCollectionExample2"  

    Subscription200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > subscription item, including:
          - id/ type        
          - `attributes` member > expressing specific subscription characteristics (url, secret, caCert, lifetime)
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the datapoints included in this subscription
            - an endpoint providing the installations included in this subscription
            - an endpoint providing the node included in this subscription
        
        As a note, the _subscription notification characteristics_ cannot read back, see details on POST service. 

        - For security reasons it is **strongly** recommended to NOT include the (here optional) subscription callback data 
          (part of **general** JSON API members `attributes`) 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).
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Subscription.json"
          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
          - `attributes` member > expressing specific subscription attributes (url, secret, caCert, lifetime)
          - `relationships` member > a relationships section with links to:
            - an endpoint providing the datapoints included in this subscription
            - an endpoint providing the installations included in this subscription
            - an endpoint providing the node included in this subscription
        
        As a note, the _subscription notification characteristics_ cannot read back, see details on POST service. 
      
        - For security reasons it is **strongly** recommended to NOT include the (here optional) subscription callback data 
          (part of **general** JSON API members `attributes`) 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).
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/SubscriptionCollection.json"
          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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    Node200:
      description: |
        The response with message data containing of (JSON API) member:
        - `meta` member > additional info (in case no item is available)
        - `data` member > node item, including:
          - id/ type > the type depends on the environment where the server is located (WAN/LAN)
          - `attributes` member > expressing specific node characteristics 
            - currentSubscriptions (value is related to maxSubscriptions below)  
            - maxSubscriptions  (maximal number of total subscriptions a node supports at a time)  
            - deviceOrServiceName
            - vendorOrProvider 
            - server
            - last modification time stamp
            - currentDateTime time stamp
          - `meta` member > expressing additional meta information of the node
            - `typedescription` > an URL to additional information that hosts potentially human readable data
          - `relationships` member > a relationships section with links to: 
            - an endpoint providing all subscriptions where this node is included in  
            
            As a note: 
            - with no typedescription relation expressed, the meta section is not present 
            - with no relation expressed, the relationships section is not present
        
        The content for a single node item is defined to be nullable, meaning the returned `data` member may be null. 
        This may occur on specific (relationships) endpoints, for this please consult the corresponding endpoints. 
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Node.json"
          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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    httpStatusNotFound:
      description: Not found
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Not Found
                links: https://schema.knx.org/2020/api
                status: "404"
                detail: Some elements of the path where not found.
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/ErrorsOAuth2.json"      
          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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    httpServiceUnavailable:
      description: Unable to handle the request.
      content:
        application/vnd.api+json:
          example:
            errors:
              - title: Service Unavailable 
                links: https://schema.knx.org/2020/api 
                status: "503"
                detail: Unable to handle the request.
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"
    
    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    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: "https://schema.knx.org/2020/api/2.1.0/schemas/Errors.json"

    WellKnownKNX200:
      description: |
        The response with message data containing of (JSON) member:
        - `api` member > most recent supported API version item, including: 
          - version identifier
          - base path
          - templates > hosting URI template placeholders and its values, additionally a relation identifier 
        - `supportedversions` member > additionally supported (older) API version items, including: 
          - version
          - base
        - `links` member > collection of Endpoints from the KNX IoT 3rd Party API, 
           additionally, from a KNX manufacturer, each item including:
          - relative link
          - templates > hosting URI template placeholders and its values
          - add. type description
          - content type format 
          - relation identifier 
        - `context` member > in the API used IRIs and its namespace prefix definitions
          - prefix
          - iri

        ### DETAILS
        #### api/version 
        
        The _version_ member contains the most recent API version the server supports, it SHALL contain of a major.minor.patch 
        numbering scheme, represented as a string. The major number with value 0 SHALL NOT be used, 
        for the minor/patch number it is RECOMMENDED to start with value 0.
        
        #### api/supportedversions 
        
        The _supportedversions_ member contains the from the server supported older API versions (in addition to the most 
        recent API version from above). Depending on a performed API change the major, minor or patch number SHALL be incremented. 
        
        - APIs with a different major version are incompatible, in case a server supports such older (incompatible) API versions 
          on purpose this information needs to be part of the 'supportedversions' member.
        
        - APIs with the same major version are upward compatible, usually a client ignores the minor or patch number. Hence this 
          only the latest major version is needed as part of the 'supportedversions' member. To allow a client checking for a specific
          version the client relies on, all available versions can be expressed, this is for client convenience/check reasons 
          (see also example below).

        #### api/base 

        - The _base_ member from above SHALL express the versioning part of the URL. It MAY also address further requested 
          resources such as a user installation as part of a cloud database. Since the _base_ member is part of the URL, 
          it is NOT RECOMMENDED to leave it empty. 

          The _base_ member as such is not specified with a trailing “/” at the end. As defined in the  
          specification the {path} is composed from the base member together with the individual resource path 
          definitions, all of them starts with a heading “/”.  This needs to be considered when calculating 
          the {paths} from its individual parts, nevertheless, the result for the {path} needs to be the same
          as formally described in the specification.

        - The _base_ member may use an URI-Template from RFC 6570, In such a case the actual URL must be resolved/expanded 
          before using it. This specification does not define a specific URI-Template as described in the RFC section 2.2. 
          
          A URI-Template expression with a variable-list containing of (varspec) variables requires for each variable a 
          corresponding reference to a list of the actual values. The RFC does not specify how to resolve this in detail 
          (see RFC, template processor), this is subject to a vendor such as per individual logged in user. 
          In this specification a framework how to define the placeholder data is specified, for this the following 
          definitions MUST apply:
            
            - A corresponding _templates_ member MUST be defined, for each used *varspec* variable a corresponding member with 
              the same (varspec) name MUST be defined as part of the _templates_ member.
            - The *varspec* member:
              -  MUST contain a _values_  member, expressed as an array (that can be also empty).
              -  MAY contain a _description_ member.
              -  MAY contain a _rel_ member, used to express a machine-readable relation from 
                 a specific *varspec* member to a present _links_ member. To do this both members need to specify 
                 the same rel member value (for this see links member).
  
        #### links
        
        The _links_ member from above contains an array of resource objects, expressing Endpoints from the KNX IoT 3rd Party API, 
        additionally from a KNX manufacturer. 

        - The _type_ is expressing the Content-Type of the endpoint.
        - The _typedescription_ is expressing an URL that hosts potentially human readable data.
        - The _href_  is expressing a relative URL, the absolute URL MUST be constructed 
          together with the _base_ member value of the intended API version. The _href_ member may use an URI-Template, 
          for this see at _base_.
        - The _rel_ is expressing a similar meaning as the rel attribute on HTML. It is used to express a machine-
          readable meaning/type of the (href) link. To define a standardized meaning the API resource path definitions 
          define some values that can be used together with the rel member. 
          - datapoints
          - devices
          - functions
          - node
          - installations
          - sites
          - locations
          - subscriptions  
          
          Other rel member values are vendor specific. 

        #### context 

        The _context_ member contains an array of resource objects, expressing the in the API used IRIs and its corresponding 
        namespace prefixes from the KIM, additionally also from a KNX manufacturer. They are mainly used on filtering with 
        query parameters and as part of responded resource items. If expressed, each _context_ member MUST contain 
        a _prefix_ and _iri_ member.

        - The _prefix_ defines the namespace prefix as it used in the API (excluding the ":").
        - The _iri_ defines the IRI/URL of the namespace prefix.

        #### additional content 
        
        KNX manufacturer specific members are optional, they MUST be added as an individual member representing a single 
        resource object in addition to the (top-level) members defined above (embedding any vendor content as part of one 
        of the defined members is not allowed).

        ### NOTES
        The _version_ member does not relate to the JSON API (specification) version as such, which is a optional 
        part of the response with the member _jsonapi:{version:1.0}_.   
      content:
        application/json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/WellKnownKNX.json"
          examples:
            Runtime 1:
              summary: Common Members
              description: |
                The example shows:
                - the most recent API version with its corresponding URL part 
                - the older supported API versions (1.1.0./1.0.5) 
                - some API entry points (links); from this API and vendor specific entry points, expressed as relative IRI 
                  (final URL needs to be concatenated with the URL __base__), additionally one predefined relation identifier 
                - some (but not all) of the in the API used namespace prefixes 
                - one vendor specific member 
              value:
                api:
                  version: 2.1.0
                  base: /api/v2
                
                supportedversions:
                  - version: 1.1.0
                    base: /api/v1
                  - version: 1.0.5
                    base: /api/v1
                
                links:
                  - href: /installations 
                    contenttype: application/vnd.api+json   
                  
                  - href: /node
                    contenttype: application/vnd.api+json 
                    rel: node
                    typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/information/getNode
                    # EXAMPLE URL with version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
                  
                  - href: /vendor
                    contenttype: application/vnd.api+json  
                
                context:
                  - prefix: knx
                    iri: http://schema.knx.org/2020/ontology/knx#
                  - prefix: loc
                    iri: http://schema.knx.org/2020/ontology/loc#
                
                projects:
                  projectLink: /sites/7de4cf57-69dc-4dc7-90d7-164f5fc7e7dd
                  user: John Deere
                  premiseURL: https://node.vimar.cloud/1234567    
            
            Runtime 2:
              summary: Installation Path
              description: |
                The example shows:
                - the most recent API version with its corresponding URL part, including a project reference (as UUID)
                - no older supported API versions  
                - no API entry points (links) 
                - no context entries
              value:
                api:
                  version: 2.1.0
                  base: /api/v2/cloud/7de4cf57-69dc-4dc7-90d7-164f5fc7e7fa   
            
            Runtime 3:
              summary: Templated Path
              description: |
                The example shows:
                - the most recent API version with its corresponding URL part including some URI-Template from RFC 6570 
                  (one as empty array), additionally an relation between a base path placeholder and a vendor defined 
                  link/href URL
                - no older supported API versions  
                - no API entry points (links)
                - no context entries
                
                It is subject to a vendor how the URI templated part is resolved, such as per individual logged in user. 
                The example shows possible site values, while the subsequent location id is not yet defined at this step. 
              value:
                api:
                  version: 2.1.0
                  base: /api/v2/cloud/{siteId}/else/{locationId}
                  templates:
                    siteId:  
                      description: Site definitions.
                      values: [rome,berlin,brusseles,tokio]
                      rel: node 
                    locationId: 
                      description: Location definitions, needs to be filled in by the client/user.
                      values: []   
                links:       
                  - href: /node
                    contenttype: application/vnd.api+json  
                    rel: node   
                  - href: /opc/{providerId}
                    contenttype: application/vnd.api+json  
                    templates:
                      providerId: 
                        description: Dynamic part.
                        values: [one,two,three]
  examples:
       
    DatapointItemEnumExample0:
      summary: Enumeration Value
      description: |
        The example shows a received enumeration value, the format of the value is a (JSON) string.
        Possible values are "on" and "off".
        
        The type is of _datapoint_, it includes: 
          
        an `attributes` member expressing that the datapoint contains of: 
        -  **writable**, **readable** (the datapoint can be read / written from the API)
        -  **enum** (the possible datapoint values)
        -  **datapointType** (an additional datapoint type information as URN and IRI, the latter with namespace identifier)
        -  **knx:groupAddress** property, additional KNX information model (data) property, with mandatory namespace identifier, 
           the member value origin is a MaC project (requires also a namespace identifier)
        -  **tag:QualityKind** and **tag:OperationKind** JSON objects, including some properties (tags) from the KNX Information Model, 
           with mandatory namespace identifiers 
        
        a `meta` member expressing that the datapoint is of type: 
          - **knx:dpa.417.61** (a KNX Information Model (KIM) class name, including its namespace identifier) 
          - **urn:knx:dpa.417.61** (the URN definition, belonging to the KIM class type directly above) 
          
      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" # quotes added additionally to prevent UI renderer problems
            enum: [on,off]  
            datapointType: [urn:knx:dpt.switch,knx:switch]
            knx:groupAddress: 1234 
            knx:measuresEquipmentType:
              "@type": tag:QualityKind
              tag:hasEquipmentType: tag:luminaire
              tag:hasQuantityKind: tag:DimmLevel
              tag:hasLocality: tag:room
            knx:hasOperationKind:
              "@type": tag:OperationKind
              tag:hasPointOperation: tag:enumeration
              tag:hasPointFunctionType: tag:pv
              tag:hasStateType: [tag:on, tag:off]
          meta:
            "@type": [knx:dpa.417.61, urn:knx:dpa.417.61]
            typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/getDatapoint 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/functions
            datapointDevice:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/device
            datapointProxy:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/proxies
            datapointSubscriptions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/subscriptions    
            
    DatapointItemNumberExample1:
      summary: Numbered Value 1
      description: |
        The example shows a received number value, the format of the value is a (JSON) string.
        
        The type is of _datapoint_, it includes: 
  
        an `attributes` member expressing that the datapoint contains of: 
        -  **writable**, **readable** (the datapoint can be read or written from the API)
        -  **minimum**, **maximum** (the datapoint has some min/max applicative - value - limitations, including a value resolution)
        -  **unit** (the datapoint has a % unit, expressed with the QUDT individual)
        
        As a note, the returned value **32** is respecting the resolution of **2**, for sure also the min/max range. 
        
        a `meta` member expressing that the datapoint type is of: 
        - **knx:dpa.418.52** (a KNX Information Model (KIM) class name, including its namespace identifier) 
        
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a463
          type: datapoint
          attributes:
            title: Brightness
            description: Brightness of the light in the bathroom
            readable: true
            value: "32"
            valueType: string
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            unit: unit:PERCENT
            datapointType: [knx:scaling]
            minimum: 30.5
            maximum: 50
            resolution: 2
          meta:
            "@type": [knx:dpa.418.52]
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/getDatapoint 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/functions
            datapointDevice:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/device
            datapointProxy:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/proxies
            datapointSubscriptions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/subscriptions  
            
    DatapointItemNumberExample2:
      summary: Numbered Value 2
      description: |
        The example shows a received number value, the format of the value is a (JSON) string.
        
        The type is of _datapoint_, it includes: 
  
        an `attributes` member expressing that datapoint contains of: 
        -  **writable**, **readable** (the datapoint can only be read from the API)
        -  **minimum**, **maximum** (the datapoint has some min/max applicative - value - limitations)
        -  **unit** (the datapoint has a % unit, expressed with the QUDT individual)
        - **datapointType** (an additional datapoint type information as IRI with namespace identifier)
        
        a `meta` member expressing that the datapoint type is of: 
        - **knx:FunctionPoint** point type (a KNX Information Model class name, including its namespace identifier) 
  
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a464
          type: datapoint
          attributes:
            title: Brightness status
            description: Brightness status of the light in the bathroom
            readable: true
            writable: false
            value: "25"
            valueType: string
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
            unit: unit:PERCENT
            minimum: 20
            maximum: 80
            datapointType: [knx:scaling] 
          meta:
            "@type": [knx:FunctionPoint]   
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/getDatapoint 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id       
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a464/functions
            datapointSubscriptions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a464/subscriptions 
    
    DatapointItemArrayExample3:
      summary: Array Value 
      description: |
        The example shows shows a received array with values, the format of the value is a (JSON) array. 
        
        The array values are JSON strings.
        The current value is "de-DE" as 4x a char (a char is a string of len 1), 
        formatted  from received octet stream "100 101 68 69" (whitespaces only inserted for readability) with code page 8859-1 
        (see datapointType), interpreted as “de-DE”.
        
        The type is of _datapoint_, it includes: 
  
        an `attributes` member expressing that datapoint contains of: 
        -  **datapointType** (an additional datapoint type information as IRI with namespace identifier)
        
        a `meta` member expressing that the datapoint type is of: 
        - **knx:FunctionPoint** point type (a KNX Information Model class name, including its namespace identifier) 
  
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a465
          type: datapoint
          attributes:
            title: Language/ region identifier
            description: The language/ region id of a specific ASCII text
            readable: true
            writable: false
            value: ['d','e','D','E']
            valueType: object
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
            datapointType: [knx:localeASCII] 
          meta:
            "@type": [knx:FunctionPoint]   
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/getDatapoint 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id       
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a465/functions
            datapointSubscriptions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a465/subscriptions 

    DatapointItemStringExample4:
      summary: String Value 
      description: |
        The example shows a received string value, the format of the value is a (JSON) string, 
        
        The value is "KNX is OK" as string, formatted from received octet stream '75 76 88 32 105 115 32 79 75 00' 
        (with trailer 00, whitespaces only inserted for readability) with code page 8859-1 (see datapointType). 
        
        The type is of _datapoint_, it includes:
  
        an `attributes` member expressing that datapoint contains of: 
        -  **datapointType** (an additional datapoint type information as IRI with namespace identifier)
        
        a `meta` member expressing that the datapoint type is of: 
        - **knx:FunctionPoint** point type (a KNX Information Model class name, including its namespace identifier) 
  
      value:
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860a466
          type: datapoint
          attributes:
            title: Welcome text
            description: My favorite slogan for the entrance display 
            readable: true
            writable: false
            unit: unit:UNITLESS
            value: "KNX is OK"
            valueType: string
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
            datapointType: [knx:varString88591] 
          meta:
            "@type": [knx:FunctionPoint]   
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/getDatapoint 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id       
          relationships:
            datapointFunctions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a466/functions
            datapointSubscriptions:
              links:
                related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a466/subscriptions

    DataPointCollectionExample:
      summary: Datapoints
      description: |
        The example shows two datapoints returned in the collection (out of 5).  
        
        - The top-level `meta` member expressing collection information, for the individual datapoint `data` member
          please refer to the examples of reading a single datapoint item. 
      value:
        meta:
          collection:
            number: 0
            size: 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" # quotes added additionally to prevent UI renderer problems
              enum: [on,off]
              datapointType: [urn:knx:dpt.switch , knx:switch]
              knx:groupAddress: 1234 
              gira:globalReferenceId: 100-17021920 # this is a attribute from a KNX manufacturer 
            meta:
              "@type": [knx:dpa.417.61] 
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/datapoint/listDatapoints 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id 
            relationships:
              datapointFunctions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/functions
              datapointDevice:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/device
              datapointProxy:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/proxies
              datapointSubscriptions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a462/subscriptions 
              
          - id: 1f48bf82-acee-45a1-9038-e2748860a463
            type: datapoint
            attributes:
              title: Brightness
              description: Brightness of the light in the bathroom
              value: "63"
              valueType: string
              timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
              unit: unit:PERCENT
              datapointType: [knx:scaling]
              minimum: 0
              maximum: 100
              abb:electricIconId: 327 # this is a attribute from a KNX manufacturer
            meta:
              "@type": [abb:specialScalingType]
            relationships:
              datapointFunctions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/functions
              datapointSubscriptions:
                links:
                  related: /datapoints/1f48bf82-acee-45a1-9038-e2748860a463/subscriptions     

    DeviceCollectionExample:
      summary: Devices
      description: |
        The example shows a single device returned in the collection. 
        The top-level `meta` member expressing collection information, for the individual device `data` member
        please refer to the examples of reading a single device item.
      value:
        meta:
          collection:
            number: 0
            size: 1
            total: 1
        data:
          - id: be43a294-3098-42ac-a165-1b5c5a4c0e64
            type: device
            attributes:
              title: 4-fold actuator
              comment: left channel nb. 1 is still not configured 
              description: a verbose description for the f-fold actuator
              orderNumber: 5WG100-200-AB
              manufacturer: Siemens
              lastModified: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
              lastDownloaded: "2021-02-17T17:20:17Z" # quotes added additionally to prevent UI renderer problems
              currentDateTime: "2023-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
              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
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/device/listDevices 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id  
            relationships:
              deviceLocation:
                links:
                  related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/location
              deviceDatapoints:
                links:
                  related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/datapoints

    DeviceItemExample1:
      summary: Device
      description: |
        The example shows a returned device (in this example as a common device) 
        
        The type is of _device_, it includes: 
          
        an `attributes` member expressing that the device contains of: 
        -  **orderNumber** (the vendor specific order number)
        -  **lastModified** (the last date of modification in the MaC project)
        -  **lastDownloaded** (the last date of download of all device modifications to the device)
        -  **currentDateTime** (the current system time the device is using)
        -  **assignedTrade** property, additional KNX information model (data) property, no namespace identifier used, 
           the member value origin is a MaC project
        -  **hasProxy** property, additional KNX information model (data) property, namespace identifier used, 
           the member value origin is a MaC project (another device)  
        
        a `meta` member expressing that the device is of type: 
          - **td:Thing** (a Thing Description class name, including its namespace identifier) 
          - **oms:dt.WaterMeter** (the URN definition, belonging to the open metering system class type definition) 
      value:
        data:
          id: be43a294-3098-42ac-a165-1b5c5a4c0e64
          type: device
          attributes:
            title: 4-fold actuator
            comment: left channel nb. 1 is still not configured 
            description: a verbose description for the 4-fold actuator
            orderNumber: 5WG100-200-AB
            manufacturer: Siemens
            lastModified: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
            lastDownloaded: "2021-02-17T17:20:17Z" # quotes added additionally to prevent UI renderer problems
            currentDateTime: "2023-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            serialNumber: 1AB234
            individualAddress: "9.12.18"
            version:
              firmware: 20.2.0
            assignedTrade: Alerting # this is a attribute from the KNX information model (data property)
            core:hasProxy: be43a294-3098-42ac-a165-1b5c5a4c0e65 # this is a attribute from the KNX information model (object property)    
          meta:
            "@type":
              - td:Thing
              - oms:dt.WaterMeter
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/device/getDeviceData 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id 
          relationships: 
            deviceLocation:
              links:
                related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/location
            deviceDatapoints:
              links:
                related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e64/datapoints

    DeviceItemExample2:
      summary: Proxy
      description: |
        The example shows a returned device (in this example as a device that proxies some datapoints). 
        
        The type is of _device_ , it includes: 
          
        an `attributes` member expressing that the device contains of: 
        -  **orderNumber** (the vendor specific order number)
        -  **lastModified** (the last date of modification in the MaC project)
        -  **lastDownloaded** (the last date of download of all device modifications to the device)
        -  **currentDateTime** (the current system time the proxy is using)
        -  **isProxyFor** property, additional KNX information model (data) property, namespace identifier used, 
           the member value's origin is a MaC project (other device) 
        
        a `meta` member expressing that the device is of type: 
          - **td:Thing** (a Thing Description class name, including its namespace identifier) 
          - **core:Gateway** (a a KNX Information Model class name, including its namespace identifier) 
      value:
        data:
          id: be43a294-3098-42ac-a165-1b5c5a4c0e65
          type: device
          attributes:
            title: System Interface
            comment: min. TLS 1.3 must be configured  
            description: an verbose description for the system interface
            orderNumber: 5WG100-400-AC
            manufacturer: Siemens
            lastModified: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            lastDownloaded: "2021-02-17T17:20:17Z" # quotes added additionally to prevent UI renderer problems 
            currentDateTime: "2023-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            serialNumber: 1AB235
            individualAddress: "0.0.1"
            version:
              firmware: 12.2.0
            core:isProxyFor: 
             - be43a294-3098-42ac-a165-1b5c5a4c0e64 
             - be43a294-3098-42ac-a165-1b5c5a4c0e63      
          meta:
            "@type":
              - td:Thing
              - core:Gateway
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/device/getDeviceData 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id  
          relationships:     
            deviceLocation:
              links:
                related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e65/location
            deviceDatapoints:
              links:
                related: /devices/be43a294-3098-42ac-a165-1b5c5a4c0e65/datapoints
    
    DeviceItemExample3:
      summary: No Data
      description: |
        The example shows a non-existing device as part of the response. 
        
        The type is of _null_ for the `data`, the response includes: 
        
        - a `meta` member expressing the reason why, such as: 
          - datapoint is not assigned to any device
          - datapoint has no proxy (device) assigned          
      value: 
        meta: 
          nodata: There is no device for this datapoint, this type of datapoint does not support such an assignment.
        data: null

    FunctionCollectionExample:
      summary: Functions
      description: |
        The example shows two functions returned in the collection (out of 4).  
        The top-level `meta` member expressing collection information, for the individual function `data` member
        please refer to the examples of reading a single function item. 
      value:
        meta:
          collection:
            number: 0
            size: 2
            total: 4
        data:
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8300
            type: function
            attributes:
              title: Light switch control in the living room
              comment: Still to less brightness  
              description: a verbose description for the function
            meta:
              "@type":
                - knx:switching
                - urn:knx:fct.switching
                - urn:knx.mft.abb.switchingLight
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/function/listFunctions 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id 
            relationships:
              functionLocation:
                links:
                  related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/location
              functionDatapoints:
                links:
                  related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/datapoints
              
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8301
            type: function
            attributes:
              title: Light dimming control in the kitchen
              comment: Too much brightness  
              description: a verbose description for the function
            meta:
              "@type":
                - knx:dimming
                - urn:knx:fct.dimming
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/function/listFunctions 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id  
            relationships:
              functionLocation:
                links:
                  related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8301/location
              functionDatapoints:
                links:
                  related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8301/datapoints
                      
    FunctionItemExample:
      summary: Function
      description: |
        The example shows a returned function.  
        The type is of _function_ , it includes: : 
        
        an `attributes` member expressing that the datapoint contains of: 
        - **tag:operatesForTrade** (the trade)  
        - **tag:QualityKind** JSON objects, including some properties (tags) from the KNX Information Model, 
          with mandatory namespace identifiers 

        a `meta` member expressing that the function is of type:   
        - ** knx:fct.switchLight** (the IRI definition) 
        - **urn:knx:fct.switchLight** (the URN definition, belonging to the type above) 
        - **urn:knx.mft.abb.switchLightOwnDefinition** (example of the URN definition of a vendor, expresses the same type as above)  
      value:
        data:
          id: 2b2c281b-af58-4816-95d0-aaa2468f8300
          type: function
          attributes:
            title: Switch control in the living room
            comment: TLS 1.3 is configured  
            description: lighting in the rear part of the room
            tag:operatesForTrade: tag:lighting
            knx:hasQualityKind: 
              "@type": tag:QualityKind
              tag:hasPhenomenonType: tag:light
              tag:hasQuantityKind: quantitykind:Illuminance 
              tag:hasLocality: tag:room
          meta:
            "@type":
              - knx:switchLight
              - urn:knx:fct.switchLight  
              - urn:knx.mft.abb.switchLightOwnDefinition
            typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/function/getFunction 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id   
          relationships:
            functionLocation:
              links:
                related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/location
            functionDatapoints:
              links:
                related: /functions/2b2c281b-af58-4816-95d0-aaa2468f8300/datapoints
            

    InstallationCollectionExample:
      summary: Installation
      description: |
        The example shows one installation item returned in the collection (one: to simplify the example).  
        The top-level `meta` member expressing collection information, for the individual installation `data` member

        - The items include installation attributes/relationships, edited in a MaC.
        - The typedescription relation is expressed. 
        - The link to the subscription where this installation is included in is expressed.  
      value:
        meta:
          collection:
            number: 0
            size: 2
            total: 2
        data:
          - id: 99291d1e-68ef-4874-ad40-6b1c41188fbe
            type: installation
            attributes:
              title: Master Home
              comment: Must reduce the hour rate for installer services.
              contractNumber: 2021.August
              lastModified: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
              projectInstallationNumber: 3-200
              state: Tested
            meta:
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/information/listInstallations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id  
            relationships:
              installationSubscriptions:
                links:
                  related: /installations/99291d1e-68ef-4874-ad40-6b1c41188fbe/subscriptions    
          - 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
            meta:
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/information/listInstallations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id  
            relationships:
              installationSubscriptions:
                links:
                  related: /installations/99291d1e-68ef-4874-ad40-6b1c41188fbf/subscriptions         

    InstallationItemExample:
      summary: Installation
      description: |
        The example shows a returned installation. 
        
        - the id and type
        - some installation attributes with specific properties, originated from the MaC.
        - the optional meta + typedescription relation 
      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" # quotes added additionally to prevent UI renderer problems
            projectInstallationNumber: 3-200
            state: Tested
          meta:
            typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/information/getInstallation 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id 
            vimar:relatedInstallationLocation: /locations/7de4cf57-69dc-4dc7-90d7-334f5fc7e7ee
            # example of a relative URL reference to the root location element of this installation,
            # this allows to express any kind of location type such as a site or a building or room
          relationships:
            installationSubscriptions:
              links:
                related: /installations/99291d1e-68ef-4874-ad40-6b1c41188fbf/subscriptions  
  
    LocationCollectionExample:
      summary: Locations
      description: |
        The example shows four location items returned in the collection, 
        as a spatial structure of an single building (building/floor/ 2 x room). 
        
        - The parent/child/function location relations are expressed. 
        - The building is not the root location, therefore, a call of the parent location relation would return data.
        - The two rooms are siblings underneath the floor, one room has no additional (meta) type information expressed. 
          Here a call of the child location relation would return no data. 
      value:
        meta:
          collection:
            number: 0
            size: 4
            total: 4
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000002
            type: location #building
            attributes:
              title: My holiday home
              comment: Must install a spy cam  
              description: a verbose description for the location
            meta:
              "@type": [loc:Building, urn:knx:loc.building]
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id 
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000002/parentlocation
              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: location #floor
            attributes:
              title: Gadget floor
            meta:
              "@type": [loc:Floor, urn:knx:loc.floor]
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000003/parentlocation
              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: location #room
            attributes:
              title: Garden gadgets
            meta:
              "@type": [loc:Room, urn:knx:loc.room]
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/parentlocation
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000005
            type: location #room
            attributes:
              title: Pool gadgets
            meta:
              typedescription:  https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/parentlocation
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/functions

    ChildLocationCollectionExample1:
      summary: Locations
      description: |
        The example shows two location items returned in the collection, 
        as a set of child locations. 
        
        - The parent/child/function location relations are expressed. 
        - The rooms are the "last" spatial location elements, therefore, a call of the child location relation would return no data.
        - The two rooms are child locations underneath a parent location (floor), one room has no additional (meta) type information expressed. 
      value:
        meta:
          collection:
            number: 0
            size: 2
            total: 2
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000004
            type: location #room
            attributes:
              title: Garden gadgets
            meta:
              "@type": [loc:Room, urn:knx:loc.room]
              typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listChildLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/parentlocation
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions
          - id: ebe13789-1f1e-47d0-8f8a-000000000005
            type: location #room
            attributes:
              title: Pool gadgets
            meta:
              "@type": [loc:Room, urn:knx:loc.room]
              typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listChildLocations 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/parentlocation
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000005/functions
          
    ChildLocationCollectionExample2:
      summary: No Data
      description: |
        The example shows a collection of non-existing location as part of the response. 
        
        The type is of _[]_ for the `data`, the response includes: 
        
        - a `meta` member expressing the reason why, such as: 
          - there are no sub structured elements being a child location    
      value:
        meta:
          nodata: No child locations available.
          collection:
            number: 0
            size: 0
            total: 0
        data: []
    
    SiteCollectionExample:
      summary: Sites
      description: |
        The example shows an spatial structure of a single premises including two sites.  
        
        - The parent/child/function location relationships are expressed.
        - The sites are root locations, therefore, a call of the parent location relation would return no data.
        - The last site has no additional (meta) type information expressed. 
      value:
        meta:
          collection:
            number: 0
            size: 2
            total: 2
        data:
          - id: ebe13789-1f1e-47d0-8f8a-000000000000
            type: location #site
            attributes:
              title: My holiday premises, left part
              comment: The hunting area must be extended  
              description: a verbose description for the site
            meta:
              "@type": [loc:Site, urn:knx:loc.site]
              typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listSites 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000000/parentlocation
              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: location 
            attributes:
              title: My holiday premises, right part
            meta:
              typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/listSites 
              # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
            relationships:
              parentLocation:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000001/parentlocation
              childLocations:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000001/childLocations
              locationFunctions:
                links:
                  related: /locations/ebe13789-1f1e-47d0-8f8a-000000000001/functions

    LocationItemExample1:
      summary: Room
      description: |
        The example shows a returned location of type room.  
        
        - The parent/child/function location relations are expressed, regardless if a call would return no data.
        - The optional device location relation is expressed.
        - The room is not further sub-structured, therefore, a call of the child location relation would return no data.
      value:
        data:
          id: ebe13789-1f1e-47d0-8f8a-000000000004
          type: location # room
          attributes:
            title: Garden gadgets
            comment: Need more mouse traps  
            description: a verbose description for the location
            hasLocationUsage: garden
          meta:
            "@type": [loc:Room, urn:knx:loc.room]
            typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/getLocation 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
          relationships:
            parentLocation:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/parentlocation
            childLocations:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/childLocations
            locationFunctions:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/functions
            locationDevices:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000004/devices    

    LocationItemExample2:
      summary: Floor
      description: |
        The example shows a returned location of type floor.  
        
        - The parent/child/function location relations are expressed, regardless if a call would return no data.
        - The optional device location relation is NOT expressed.
        - The floor is the parent location of an subsequent ordinate room, 
          therefore, a call of the parent location relation would return data (such as a building item).
      value:
        data:
          id: ebe13789-1f1e-47d0-8f8a-000000000008
          type: location # floor
          attributes:
            title: My home 1st floor
            hasLocationUsage: hallway
          meta:
            "@type": [loc:Floor, urn:knx:loc.floor]
            typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/location/getLocation 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
          relationships:    
            parentLocation:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000008/parentlocation
            childLocations:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000008/childLocations
            locationFunctions:
              links:
                related: /locations/ebe13789-1f1e-47d0-8f8a-000000000008/functions

    LocationItemExample3:
      summary: No Data
      description: |
        The example shows a non-existing location as part of the response. 
        
        The type is of _null_ for the `data`, the response includes: 
        
        - a `meta` member expressing the reason why, such as: 
          - device is not assigned to any location
          - location has no parent (location) assigned      
      value: 
        meta: 
          nodata: There is no assembly location for this device.
        data: null
    
    UpdateEventDatapointsExample:
      summary: Datapoints
      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" # quotes added additionally to prevent UI renderer problems
          - id: 123e4567-e89b-12d3-a456-426614174001
            type: datapoint
            links:
              self: /datapoints/123e4567-e89b-12d3-a456-426614174001
            attributes:
              value: "25.0"
              timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems  
    
    UpdateEventDatapointsNodeExample:
      summary: Datapoint and node
      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" # quotes added additionally to prevent UI renderer problems
          - id: 123e4567-e89b-12d3-a456-426614174003
            type: service
            links:
              self: https://gateway.knx.local/node/
            attributes:
              description: "node owner is changed to …"
                        

    SubscriptionItemLanExample:
      summary: LAN Subscription
      description: |
        The 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-----
            lifetime: 3600
          relationships:
            subscriptionDatapoints:
              links:
                related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints
            subscriptionNode:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/node     
     
    SubscriptionItemWanExample: 
      summary: WAN Subscription
      description: |
        The 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
          relationships:
            subscriptionDatapoints:
              links:
                related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints 
            subscriptionNode:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/node            

    SubscriptionCollectionLanExample:
      summary: LAN Subscriptions
      description: |
        The example shows a subscription collection response in a local environment.  
        The security related properties are returned. 
      value:
        meta:
          collection:
            number: 0
            size: 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-----
            relationships:
              subscriptionDatapoints:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints  
              subscriptionNode:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/node    
              
    SubscriptionCollectionWanExample:
      summary: WAN Subscriptions
      description: |
        The example shows a subscription collection response in a public environment.  
        The security related properties are NOT returned. 
      value:
        meta:
          collection:
            number: 0
            size: 1
            total: 1
        data:
          - id: 123e4567-e89b-12d3-a456-4266141740aa
            type: subscription
            relationships:
              subscriptionDatapoints:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/datapoints    
              subscriptionNode:
                links:
                  related: /subscriptions/123e4567-e89b-12d3-a456-4266141740aa/node     

    SubscribeUponDatapointsExample:
      summary: Subscribe to datapoints
      description: |
        A subscription request that addresses two datapoints directly and datapoints
        that are hosted in a room (with a extended subscription characteristics).  
      value:
        data:
          type: subscription
          relationships:
            subscriptionDatapoints:
              data:
              - id: 123e4567-e89b-12d3-a456-426614174000
                type: location
                meta: 
                  expand: true
              - id: 123e4567-e89b-12d3-a456-426614174001
                type: datapoint
              - id: 123e4567-e89b-12d3-a456-426614174002
                type: datapoint
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            lifetime: 60
    
    SubscribeUponDatapointsNodeExample:
      summary: Subscribe to datapoints and node
      description: |
        A subscription request that addresses one datapoint directly and a node.
      value:
        data:
          type: subscription
          relationships:
            subscriptionDatapoints: 
              data:
              - id: 123e4567-e89b-12d3-a456-426614174002
                type: datapoint
            subscriptionNode:
              data:
                id: 123e4567-e89b-12d3-a456-426614174003
                type: service    
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            lifetime: 60
    
    SubscribeUponNodeDefaultExample:
      summary: Subscribe to a node (default)
      description: |
        A subscription request that addresses a (single) node. 
        Event notifications for the node only will be raised individually. 
      value:
        data:
          type: subscription
          relationships:
            subscriptionNode:
              data:
                id: 123e4567-e89b-12d3-a456-426614174000 
                type: service
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            lifetime: 60
    
    SubscribeUponNodeExtendedExample:
      summary: Subscribe to a node (extended)
      description: |
        A subscription request that addresses a (single) node, including all installations hosted at this node. 
        Event notifications for the node and all installations will be raised individually (or combined in a message).  
      value:
        data:
          type: subscription
          relationships:
            subscriptionNode:
              data:
                id: 123e4567-e89b-12d3-a456-426614174000 
                type: service
                meta: 
                  expand: true
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            lifetime: 60
    
    SubscribeUponInstallationsExample:
      summary: Subscribe to several installations
      description: |
        A subscription request that addresses (several) installations.  
      value:
        data:
          type: subscription
          relationships:
            subscriptionInstallations: 
              data:
                - id: 123e4567-e89b-12d3-a456-426614174000
                  type: installation
                - id: 123e4567-e89b-12d3-a456-426614175000
                  type: installation   
          attributes:
            url: https://api.notserv.com/updates
            secret: TheBestPasswordEver
            caCert: -----BEGIN CERTIFICATE----- MIIEpQIBAAKCAQEA8...Oz+b3mZxGIPQ= -----END CERTIFICATE-----
            lifetime: 60    

    SubscriptionPatchExample1:
      summary: Patch all
      description: |
        The example shows the patch of a present subscription, updating ALL elements.  
      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-----
            lifetime: 3600
     
    SubscriptionPatchExample2:
      summary: Patch lifetime
      description: |
        The example shows the patch of a present subscription, extending only the lifetime.  
      value:
        data:
          id: 123e4567-e89b-12d3-a456-4266141740aa 
          type: subscription
          attributes:
            lifetime: 3600

    NodeItemExample:
      summary: Runtime
      description: |
        Specifies vendor specific and in this in this specification defined node properties as part of `attributes` and 
        `meta` member. It may also be used to express what kind of optional endpoints this server has implemented. 
        
        The `attributes` contain the following data:  
         - the deviceOrServiceName, vendorOrProvider 
         - the WebSocket and/or HTTP subscription is supported from the device 
         - the max. number of supported subscriptions (a static value)
         - the current (remaining) number of subscriptions (a dynamic value, it may change at every client read request)
         - the last modification of the node was ... 
         - the current system time the node is using is ...  
         
         The `meta` contain the following data:  
         - a vendor member describing what subscription interface is implemented  (the presence of the endpoints 
           may be also scanned to get this)

         The `relationships` contain the following data:  
         - a link to the subscription where this node. is included 
      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: 9.0.0
            maxSubscriptions: 512
            currentSubscriptions: 200
            lastModified: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            currentDateTime: "2023-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
          meta:
            gira:serverProfile: [http_callback, websocket] 
            typedescription: https://schema.knx.org/2020/api/work_in_progress?visualisation=swagger#/information/getNode 
            # URL uses version identifier of schema.knx.org (not GIT branch name) + swagger tag + endpoint operation id
          relationships:
            nodeSubscriptions:
              links:
                related: /node/subscriptions     

    TimeseriesCollectionExample:
      summary: Two Datapoint Value Changes
      description: |
        The example shows two value changes for a datapoint returned in the collection (out of 2).  
        
        The type is of _timeseries_, it includes: 
  
        an `attributes` member expressing that the datapoint contains of: 
        -  **value**, **timestamp** (the occurrence)
      value:
        meta:
          collection:
            number: 0
            size: 2
            total: 2
        data:
          - id: 1f48bf82-acee-45a1-9038-e2748860b000
            type: timeseries
            attributes:
              value: on
              timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
            relationships:
              timeseriesDatapoint: 
                links:
                  related: /timeseries/1f48bf82-acee-45a1-9038-e2748860b000/datapoint 
              
          - id: 1f48bf82-acee-45a1-9038-e2748860b001
            type: timeseries
            attributes:
              value: "off"
              timestamp: "2021-02-17T17:17:13Z" # quotes added additionally to prevent UI renderer problems
            relationships:
              timeseriesDatapoint: 
                links:
                  related: /timeseries/1f48bf82-acee-45a1-9038-e2748860b001/datapoint   
    
    TimeseriesItemExample:
      summary: Timeseries entry, value type string
      description: |
        The example shows a timeseries entry with a value change for a datapoint.  
        
        The type is of _timeseries_, it includes: 
  
        an `attributes` member, containing of: 
        -  **value**  (the datapoint value, value type string)
        -  **timestamp** (the last write access occurrence)    
      value:  
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860b000
          type: timeseries
          attributes:
            value: "on"
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
          relationships:
            timeseriesDatapoint: 
              links:
                related: /timeseries/1f48bf82-acee-45a1-9038-e2748860b000/datapoint
    
    TimeseriesArrayExample:
      summary: Timeseries entry, value type array
      description: |
        The example shows a timeseries entry with a value change for a datapoint.  
        
        The type is of _timeseries_, it includes: 
  
        an `attributes` member, containing of: 
        -  **value**  (the datapoint value, value type object)
        -  **timestamp** (the last write access occurrence)    
      value:  
        data:
          id: 1f48bf82-acee-45a1-9038-e2748860b001
          type: timeseries
          attributes:
            value: ["3","4"]
            timestamp: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems
          relationships:
            timeseriesDatapoint: 
              links:
                related: /timeseries/1f48bf82-acee-45a1-9038-e2748860b001/datapoint
    
    DatafieldCollectionExample0:
      summary: Several Datafields
      description: |
        The example shows three datafields of an artificial datapoint type definition, returned in the collection.  
        The top-level `meta` member expressing collection information, for the individual datafield `data` member
        please see below or at the scheme definition.

        - title, description
        - value (if present)
        
        **enumeration** 
        - enumValueMap
        
        **numbered** 
        - unit, minimum, maximum, resolution, integer
        
        **text** 
        - charset, maxLength
        
        **date/time** 
        - unit 
        
      value:
        meta:
          collection:
            number: 0
            size: 3
            total: 3
        data:
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8300 
            type: datafield
            title: Control Dimming  
            description: Step Code
            value: "4"
            enumValueMap: 
              - "break": 0
              - "14%": 1
              - "28%": 2
              - "42%": 3
              - "56%": 4
              - "78%": 5
              - "84%": 6
              - "100%": 7  
            relationships:
              datafieldDatapoints:
                links:
                  related: /datafieds/2b2c281b-af58-4816-95d0-aaa2468f8300/datapoints

          - id: 2b2c281b-af58-4816-95d0-aaa2468f8301
            type: datafield
            title: Scaling
            description: Percent Value
            value: "128"
            unit: unit:PERCENT
            minimum: 0
            maximum: 255
            resolution: 0.3921566
            integer: true
            relationships:
              datafieldDatapoints:
                links:
                  related: /datafieds/2b2c281b-af58-4816-95d0-aaa2468f8301/datapoints
                  
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8302
            type: datafield
            title: String ASCII  
            description: ASCII string
            value: "MTAw"
            charset: us-ascii
            maxLength: 14
            relationships:
              datafieldDatapoints:
                links:
                  related: /datafieds/2b2c281b-af58-4816-95d0-aaa2468f8302/datapoints  
          
          - id: 2b2c281b-af58-4816-95d0-aaa2468f8303 
            type: datafield
            title: Date Time  
            description: ISO 8601 date/time, the unit expresses a QUDT date/time encoding scheme not an actual unit.
            value: "2021-02-17T17:17:17Z"
            unit: qudt:ISO8601-UTCDateTime-BasicFormat
            relationships:
              datafieldDatapoints:
                links:
                  related: /datafieds/2b2c281b-af58-4816-95d0-aaa2468f8303/datapoints  


  parameters:
    
    collectionSize:
      name: page[size]
      description: |
        Specifies the number of items (as size) to return in the response. 
        - The server default value for **size** is vendor specific. It MUST be larger than zero, 
          otherwise client requests without this query parameter return an empty list. 
        - The actual returned number of items may be less than **size** if the last page does not contain enough items.
        - The maximum value is suggested to be a signed 32 bit (to ease sw implementations/interoperability), hence this the (implicit) maximum is specified accordingly with the format definition. 
      in: query
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 65536

    collectionPage:
      name: page[number]
      description: |
        Specifies the number of pages to skip before starting to collect the result set of items. 
        - The server value for the **page size** is vendor specific. 
          To address a specific item (as a zero-based offset) in a collection > number = offset / page size 
        - The server default value for **number** MUST be zero, otherwise client requests without this query parameter cannot read all items. 
        - The maximum value is suggested to be a signed 32 bit (to ease sw implementations/interoperability), hence this the (implicit) maximum is specified accordingly with the format definition. 
      in: query
      schema:
        type: integer
        format: int32
        default: 0

    datapointId:
      name: datapointId
      description: The id from requested datapoint.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440000 

    timeseriesId:
      name: timeseriesId
      description: The id from requested time series.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440003 
      
    datafieldId:
      name: datafieldId
      description: The id from requested datafield.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440001  
    
    deviceId:
      name: deviceId
      description: The id from requested device.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440001  

    functionId:
      name: functionId
      description: The id from requested function.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440002  

    subscriptionId:
      name: subscriptionId
      description: The id from requested subscription.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440003

    installationId:
      name: installationId
      in: path
      description: The ID of the installation which is operated on
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-11d4-a716-446655440004

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

    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]

    typeFilter:
      name: filter[meta.@type][operator]
      description: |
        Specifies the type of resource to be filtered on, additionally with an optional 
        operator to perform logical/ comparison operations.  Example is to filter for a location that has a _type_  
        value of _Floor_ or filter for all locations being either a floor or space.

        - The parameter value is specified with a KNX Information Model class **name** or (if available) the - to this class - assigned URN. 
          
          The KIM classes can be devices, datapoints, locations or application functions and other. The individual name is 
          the remainder of the IRI when removing the corresponding namespace prefix, such as 
          - **loc:** from <http://schema.knx.org/2020/ontology/loc#Floor> -> Floor
          - **core:** from <http://schema.knx.org/2020/ontology/core#Device> -> Device
         
          In case of KNX Information Model content the name/ value namespace identifier can be omitted (if used, 
          also the ":" namespace delimiter must be % encoded). 

        - The parameter name is specified for the part **meta.@type** fix as it is defined.  
        
        - The parameter name is specified for the part **operator** with the logical 
          operators of eq, le, ge, lt, gt, and, or. The parameter name part **operator** is optional, if not expressed 
          it is used with the default eq (then the filter is a simple equal to filter).  

      in: query
      required: false
      schema:
        type: object
        additionalProperties:   
          type: string
      examples: 
        E0: 
          summary: filter for rooms, as class
          value: 
            filter[meta.@type]: Room 
        E1: 
          summary: filter for rooms or floors, as class
          value: 
            filter[meta.@type][or]: Room,Floor 
        E2: 
          summary: filter for rooms, as URN
          value: 
            filter[meta.@type]: urn:knx:loc.room   
        E3: 
          summary: filter for devices, as class
          value: 
            filter[meta.@type]: Device 
        E4: 
          summary: filter for devices, as class with namespace
          value: 
            filter[meta.@type]: core:Device  
        E5: 
          summary: filter for vendor tings (a device), as class with namespace
          value: 
            filter[meta.@type]: oms:dt.HeatMeter    
        E6: 
          summary: filter for (specific) datapoints, as class 
          value: 
            filter[meta.@type]: dpa.321.51     

    tagFilter:
      name: filter[tagKey][operator]    
      description: |
        Specifies a filter for resources that are assigned to specific tags, additionally with an optional 
        operator to perform logical/ comparison operations. 
        Examples are a point that acts on a related (tag) _temperature_, a building that is used as an (tagged) _airport_ 
        or a device that operates for the trade _HVAC_. 

        ### Parameter Value
       
        - The parameter value is specified with the **name** of a KNX Information Model individual of class tag:Tag. 
        
          The individual name is the remainder of the IRI when removing the corresponding namespace prefix, such as **tag**: 
          from <http://schema.knx.org/2020/ontology/tag#actuator> -> actuator
        
        ### Parameter Name

        - The parameter name is specified for the part **tagKey** with a structure of KIM object property 
          relationship predicates, as follows:  
            
          - hasTagSet.hasTag -> a combination of two parent OPs
          - hasTag -> a single parent OP
        
          The described parent OPs have a dedicated range to all possible tag individuals of KIM class :Tag, on using them all 
          tags will be filtered and included in the result. To limit the results related child OPs needs to be used, 
          mainly from hasTag, but also from hasTagSet (or in a combination). 
        
          - hasTagSet.hasTag (two parent OPs are used)
          - hasQualityKind.hasTag (a child property is used for the first part)
          - hasTagSet.hasOrigin (a child property is used for the second part)
          - ... 

          Present parent and child OPs are defined in the KNX Information Model. Not all available child OPs makes sense in every
          combination from above, usable child OPs (and ist possible combinations) are described in the written specification. 

        - The parameter name is specified for the part **operator** with the logical 
          operators of eq, le, ge, lt, gt, and, or. The parameter name part **operator** is optional, if not expressed 
          it is used with the default eq (then the filter is a simple equal to filter).  

        ### Notes
    
        If a chosen parameter name/ value combination does not match content wise or logically, a matching MAY be 
        not able to retrieve/ calculate from the server, for this an error must be returned. 

        In case of KNX Information Model content the name/ value namespace identifier can be omitted (if used, 
        also the ":" namespace delimiter must be % encoded). If two KIM properties have the same name and the namespace is 
        not used as part of the filtering the server behavior is unspecified. For other content it is recommended to add namespaces, 
        otherwise corresponding KIM properties with the same name are prioritized.
         
      in: query
      required: false
      schema:
        type: object
        additionalProperties:   
         type: string 
      examples:
          E1:
            summary: Filter for a specific location usage
            value: 
              filter[hasLocationUsage]: airport  
          E2:
            summary: Filter for a point with a specific combination of interface types
            value: 
              filter[hasPointInterface]: if.i,if.p
          E3:
            summary: Filter for a point that acts upon an equipment
            value: 
              filter[actsOnPhenomenonType.hasEquipmentType]: actuator     
          E4:
            summary: Filter for a point that has a specific tag assigned
            value: 
              filter[hasTag]: switch     
             
    attributeFilter:
      name: filter[attributeKey][operator]       
      description: |
        Specifies a filter for a resource item that matches a specific attribute, additionally with an optional 
        operator to perform logical/ comparison operations. Example is to filter for a device that has a _order number_  
        value of _5WG100-200-AB_ or filter for all datapoints with a temperature (attribute) value lower than 30°C.  
       
        - The parameter value is specified with arbitrary terms defined as: 
          - MaC project (strings) 
          - timestamp (time) values
          - Datapoint (string) values
          - KIM individual (IRI) names 

          Depending on the related resource item member the value needs to be interpreted in different ways.

          - **String** -> lexical order, also for "lower than" compare ops
          - **Number** -> Numbers are interpreted according to JSON, clause 6 
          - **Time** -> RFC 3339, clause 5.6
          - **IRI** -> same as String above, the KIM individual name is the remainder of the IRI when removing 
          the corresponding namespace identifier, such as unit: from <http://qudt.org/vocab/unit/DEG_C> -> DEG_C

        - The parameter name is specified for the part **attributeKey** with an `attributes` API reference member,
          vendor specific key or as an entire JSON Object.  

        - The parameter name is specified for the part **operator** with the logical 
          operators of eq, le, ge, lt, gt, and, or. The parameter name part **operator** is optional, if not expressed 
          it is used with the default eq (then the filter is a simple equal to filter).  

        In case of KNX Information Model content the name/ value namespace identifier can be omitted (in case it is used, 
        also the ":" namespace delimiter must be % encoded). If two KIM properties have the same name and the namespace is 
        not used as part of the filtering the server behavior is unspecified. For other content it is recommended to add namespaces, 
        otherwise corresponding KIM properties with the same name are prioritized.
               
      in: query
      required: false
      schema:
        type: object
        additionalProperties:   
          type: string
      examples:
          E1:
            summary: Filter for an order number
            value: 
              filter[orderNumber]: 5WG100-200-AB  
          E2:
            summary: Filter for a device (title) name
            value: 
              filter[title]: 16-fold Actuator  
          E3:
            summary: Filter for a function property
            value: 
              filter[state]: Tested 
          E4:
            summary: Filter for a vendor specific device property
            value: 
              filter[gira:deviceUpdateCycle]: immediately
          E5:
            summary: Filter for a value lower than ...
            value: 
              filter[value][le]: "30"  
          E6:
            summary: Filter for a device in a state
            value: 
              filter[state][eq]: Edited  
          E7:
            summary: Filter for a device in two states
            value:  
              filter[state][or]: Edited,Tested    

    timeFilter:
      name: filter[timestamp][operator]    
      description: |
        The parameter filters depending on a period or point in time, expressed with an optional 
        operator to perform time oriented logical/ comparison operations.  
       
        - The parameter value is specified with date-time with RFC 3339.  
   
        - The parameter name is specified for the part **timestamp** with an `attributes` member API reference name _timestamp_.
        
        - The parameter name is specified for the part **operator** with the logical 
          operators of <eq, le, ge, lt, gt, and, or>. The parameter name part **operator** is optional, if not expressed 
          it is used with the default eq (then the filter is a simple equal to filter, for the use case 
          to work with timestamps comparisons with less practical use). 

        The filter is specified to be used only with the datapoint `attributes` member  _value_, it can be applied more 
        than once per request (with different operators), such as when defining a period.
        
        ### Notes

        This filter definition is only a more specific form of the generic **filter[attributeKey][operator]** filter.
        It is used on endpoints to return:
            
          - datapoint value/ timestamp series per **individual** datapoint
          - datapoints where a value change was occurring
          
        Examples, all value/ timestamp series with an **value changes** of an individual datapoint _since_ yesterday 11AM or 
        all datapoints with a **value change** occurred _after_ yesterday 11AM.
      in: query
      required: false
      schema:
        type: object
        additionalProperties:
          type: string 
      examples:
          E1:
            summary: all 'value changes', occurred after ...
            value:  
              filter[timestamp][ge]: "2021-02-17T17:17:13Z" # quotes added additionally to prevent UI renderer problems  
          E2:
            summary: all 'value changes', occurred before ...
            value:  
              filter[timestamp][le]: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems    
          E3:
            summary: all 'value changes', occurred between ...
            value:  
              filter[timestamp][ge]: "2021-02-17T17:17:13Z" # quotes added additionally to prevent UI renderer problems
              filter[timestamp][le]: "2021-02-17T17:17:17Z" # quotes added additionally to prevent UI renderer problems 
  
  requestBodies:
    
    datapointValuesPut:
      description: |
        Datapoints message data, containing of (JSON API) member: 
          - `data` member -> collection of (to be written datapoint) items
        
        ### Notes 
        The *content type* is as specified, but **application/json** is also allowed. 
        It is used as a fallback in case a client requests a similar format that the server can understand. To signal an error is not intended in such a case.
      required: true
      content:
        application/vnd.api+json:
          schema:
            $ref: "https://schema.knx.org/2020/api/2.1.0/schemas/DatapointCollectionWithValues.json"
          examples:
            Runtime0:
              summary: String Values
              description: Several value type "string" values, as a boolean and (float) number.
              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"
            Runtime1: 
              summary: Array Value 
              description: A value type "object" value, as a date/time and boolean (both are part of an individual datapoint respectively its type).
              value:
                data:
                  - id: ebe13789-1f1e-47d0-8f8a-d00000000002
                    type: datapoint
                    attributes:
                      value: ["2021-02-17T17:17:17Z","1"] 
                   

  securitySchemes:
    OAuth2:
      type: oauth2
      description: | 
        Usage of standard oauth 2.0 **Authorization Code** and **Client Credentials** flow. 
        All URLs are relative to the server URL.
        1. The handling of user **authorization** endpoint is not specified in this API (authorizationUrl). 
        2. The corresponding **token** endpoint is specified (tokenUrl, refreshUrl), 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 (does not include other scopes, scopes can be combined together). 
            write: Allows to write resources (does not include other scopes, scopes can be combined together). 
            manage: Allows to manage extended functionality of the API, 
                    currently only subscription interfaces (does not include other scopes, scopes can be combined together).
        
        clientCredentials:
          tokenUrl: /oauth/access
          refreshUrl: /oauth/access
          scopes:
            read: Allows to read resources (does not include other scopes, scopes can be combined together). 
            write: Allows to write resources (does not include other scopes, scopes can be combined together). 
            manage: Allows to manage extended functionality of the API, 
                    currently only subscription interfaces (does not include other scopes, scopes can be combined together).          
      
    BasicAuthentication:
      type: http
      scheme: basic
      description: |
        Usage of Basic Authentication Scheme as authentication. 
        This security scheme is intended to be used when accessing the token endpoint from authorization server (and some other EPs).
        For this see workflow described on authorization section in this file. 