service.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "plgd client application - API",
    "version": "1.0",
    "contact": {
      "name": "plgd.dev",
      "url": "https://github.com/plgd-dev/device",
      "email": "info@plgd.dev"
    },
    "license": {
      "name": "Apache License 2.0",
      "url": "https://github.com/plgd-dev/device/blob/v2/LICENSE"
    }
  },
  "tags": [
    {
      "name": "ClientApplication"
    }
  ],
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json",
    "application/protojson"
  ],
  "produces": [
    "application/json",
    "application/protojson"
  ],
  "paths": {
    "/.well-known/configuration": {
      "get": {
        "summary": "Provides configuration for clients of client application.",
        "operationId": "ClientApplication_GetConfiguration",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbGetConfigurationResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "tags": [
          "client-application"
        ]
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "summary": "Get jwks.json.",
        "description": "Available only when GetConfigurationResponse.device_authentication_mode == X509 and GetConfigurationResponse.remote_provisioning.mode == USER_AGENT.",
        "operationId": "ClientApplication_GetJSONWebKeys",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "tags": [
          "client-application"
        ]
      }
    },
    "/api/v1/devices": {
      "get": {
        "summary": "Discover devices by client application.",
        "description": "This operation fills cache of mappings deviceId to endpoints and this cache is used by other calls.",
        "operationId": "ClientApplication_GetDevices",
        "responses": {
          "200": {
            "description": "A successful response.(streaming responses)",
            "schema": {
              "type": "object",
              "properties": {
                "result": {
                  "$ref": "#/definitions/pbDevice"
                },
                "error": {
                  "$ref": "#/definitions/googlerpcStatus"
                }
              },
              "title": "Stream result of pbDevice"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "useCache",
            "description": "Devices are taken from the cache. Default: false.",
            "in": "query",
            "required": false,
            "type": "boolean"
          },
          {
            "name": "useMulticast",
            "description": "Filter by multicast IP address version. Default: [] - multicast is disabled. If it is set, the new devices will be added to cache.",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "IPV4",
                "IPV6"
              ]
            },
            "collectionFormat": "multi"
          },
          {
            "name": "useEndpoints",
            "description": "Returns devices via endpoints. Default: [] - filter is disabled. New devices will be added to cache. Not reachable devices will be not in response.\nEndpoint can be in format:\n- \u003chost\u003e:\u003cport\u003e is interpreted as coap://\u003chost\u003e:\u003cport\u003e\n- \u003chost\u003e is interpreted as coap://\u003chost\u003e:5683",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          },
          {
            "name": "timeout",
            "description": "How long to wait for the devices responses for responses in nanoseconds. Default: 0 - means 2sec.",
            "in": "query",
            "required": false,
            "type": "string",
            "format": "int64"
          },
          {
            "name": "ownershipStatusFilter",
            "description": "Filter by ownership status. Default: [UNOWNED,OWNED].\n\n - UNOWNED: get only unowned devices\n - OWNED: get only owned devices",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "UNOWNED",
                "OWNED"
              ]
            },
            "collectionFormat": "multi"
          },
          {
            "name": "typeFilter",
            "description": "Filter by device resource type of oic/d. Default: [] - filter is disabled.",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          }
        ],
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      },
      "delete": {
        "summary": "Deletes all devices from the cache.",
        "description": "To fill the cache again, call GetDevices.",
        "operationId": "ClientApplication_ClearCache",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbClearCacheResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "tags": [
          "Devices"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}": {
      "get": {
        "summary": "Get device information from the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_GetDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbDevice"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/disown": {
      "post": {
        "summary": "Disown the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_DisownDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbDisownDeviceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/offboard": {
      "post": {
        "summary": "Offboard the device.",
        "description": "Disconnects device from the plgd hub.",
        "operationId": "ClientApplication_OffboardDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbOffboardDeviceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/onboard": {
      "post": {
        "summary": "Onboard the device.",
        "description": "Provisions device to the plgd hub.",
        "operationId": "ClientApplication_OnboardDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbOnboardDeviceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "coapGatewayAddress": {
                  "type": "string",
                  "title": "endpoint in format \u003cscheme\u003e://\u003chost\u003e:\u003cport\u003e"
                },
                "authorizationCode": {
                  "type": "string",
                  "title": "authorization code from the hub"
                },
                "authorizationProviderName": {
                  "type": "string",
                  "title": "authorization provider from the hub"
                },
                "hubId": {
                  "type": "string",
                  "title": "hub id in uuid format to allow hub access to device"
                },
                "certificateAuthorities": {
                  "type": "string",
                  "title": "list of hub certificate authorities in PEM format to verify the hub certificate"
                }
              }
            }
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/own": {
      "post": {
        "summary": "Own the device.",
        "description": "When GetConfigurationResponse.device_authentication_mode == X509 and GetConfigurationResponse.remote_provisioning.mode == USER_AGENT the finish own need to be called:\n - own returns identity CSR of the device which need to be signed by certificate authority\n - in own/{state} call provides signed identity certificate to the device.option\nLook to https://raw.githubusercontent.com/plgd-dev/client-application/main/ownDevice.plantuml for flows.",
        "operationId": "ClientApplication_OwnDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbOwnDeviceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "timeout": {
                  "type": "string",
                  "format": "int64",
                  "description": "Defines how long own process will wait for the OwnDeviceRequest with set_identity_certificate in nanoseconds. Default value is 15secs."
                }
              }
            }
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/own/{state}": {
      "post": {
        "summary": "Finishing own the device for remote provisioning via USER_AGENT.",
        "description": "Available only when GetConfigurationResponse.device_authentication_mode == X509 and GetConfigurationResponse.remote_provisioning.mode == USER_AGENT.",
        "operationId": "ClientApplication_FinishOwnDevice",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbFinishOwnDeviceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "state",
            "description": "Use value form OwnDeviceResponse.get_identity_csr.state",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "certificate": {
                  "type": "string",
                  "format": "byte",
                  "title": "Certificate chain in PEM format"
                }
              }
            }
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{deviceId}/resource-links": {
      "get": {
        "summary": "Get resource links of the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_GetDeviceResourceLinks",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbResourceLinksPublished"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "Device"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{resourceId.deviceId}/resource-links/{resourceId.href}": {
      "delete": {
        "summary": "Delete a resource at the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_DeleteResource",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbDeleteResourceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "resourceId.deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "resourceId.href",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": ".+"
          }
        ],
        "tags": [
          "Resource"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      },
      "post": {
        "summary": "Create a resource at the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_CreateResource",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbCreateResourceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "resourceId.deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "resourceId.href",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": ".+"
          },
          {
            "name": "content",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbContent"
            }
          }
        ],
        "tags": [
          "Resource"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/devices/{resourceId.deviceId}/resources/{resourceId.href}": {
      "get": {
        "summary": "Get a resource from the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_GetResource",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbResource"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "resourceId.deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "resourceId.href",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": ".+"
          },
          {
            "name": "resourceInterface",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "Resource"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      },
      "put": {
        "summary": "Update a resource at the device.",
        "description": "Device needs to be stored in cache otherwise it returns not found.",
        "operationId": "ClientApplication_UpdateResource",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbUpdateResourceResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "resourceId.deviceId",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "resourceId.href",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": ".+"
          },
          {
            "name": "content",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/grpcgatewaypbContent"
            }
          },
          {
            "name": "resourceInterface",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "Resource"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/identity/certificate": {
      "get": {
        "summary": "Get identity certificate of the client application.",
        "description": "Available only when GetConfigurationResponse.device_authentication_mode == X509 and GetConfigurationResponse.remote_provisioning.mode == USER_AGENT.",
        "operationId": "ClientApplication_GetIdentityCertificate",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbGetIdentityCertificateResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "tags": [
          "client-application"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/initialize": {
      "post": {
        "summary": "Initialize application when GetConfiguration.is_initialized is set to false.",
        "description": "Look to https://raw.githubusercontent.com/plgd-dev/client-application/main/initialize.plantuml for flows.",
        "operationId": "ClientApplication_Initialize",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbInitializeResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/pbInitializeRequest"
            }
          }
        ],
        "tags": [
          "client-application"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/initialize/{state}": {
      "post": {
        "summary": "Finishing initialization for remote provisioning via USER_AGENT.",
        "description": "Available only when GetConfigurationResponse.device_authentication_mode == X509 and GetConfigurationResponse.remote_provisioning.mode == USER_AGENT.",
        "operationId": "ClientApplication_FinishInitialize",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbFinishInitializeResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "state",
            "description": "Use value for pairing otherwise finish will be refused.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "certificate": {
                  "type": "string",
                  "format": "byte",
                  "title": "Certificate chain in PEM format"
                }
              }
            }
          }
        ],
        "tags": [
          "client-application"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    },
    "/api/v1/reset": {
      "post": {
        "summary": "Flushes identity certificate, private key, device cache and jwks.json.",
        "operationId": "ClientApplication_Reset",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/pbResetResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/googlerpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/pbResetRequest"
            }
          }
        ],
        "tags": [
          "client-application"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    }
  },
  "definitions": {
    "ConnectionProtocol": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "COAP",
        "COAPS",
        "COAP_TCP",
        "COAPS_TCP",
        "C2C"
      ],
      "default": "UNKNOWN"
    },
    "DeviceMetadata": {
      "type": "object",
      "properties": {
        "connection": {
          "$ref": "#/definitions/pbConnection"
        },
        "twinSynchronization": {
          "$ref": "#/definitions/pbTwinSynchronization"
        },
        "twinEnabled": {
          "type": "boolean"
        }
      }
    },
    "DeviceOwnershipStatus": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "UNOWNED",
        "OWNED",
        "UNSUPPORTED"
      ],
      "default": "UNKNOWN",
      "title": "- UNKNOWN: cannot determine ownership status\n - UNOWNED: device is ready to be owned the user\n - OWNED: device is owned by the user. to determine who own the device you need to get ownership resource /oic/sec/doxm\n - UNSUPPORTED: set when device is not secured. (iotivity-lite was built without security)"
    },
    "GetConfigurationResponseDeviceAuthenticationMode": {
      "type": "string",
      "enum": [
        "PRE_SHARED_KEY",
        "X509",
        "UNINITIALIZED"
      ],
      "default": "PRE_SHARED_KEY"
    },
    "GetDevicesRequestOwnershipStatusFilter": {
      "type": "string",
      "enum": [
        "UNOWNED",
        "OWNED"
      ],
      "default": "UNOWNED",
      "title": "- UNOWNED: get only unowned devices\n - OWNED: get only owned devices"
    },
    "GetDevicesRequestUseMulticast": {
      "type": "string",
      "enum": [
        "IPV4",
        "IPV6"
      ],
      "default": "IPV4"
    },
    "RemoteProvisioningMode": {
      "type": "string",
      "enum": [
        "MODE_NONE",
        "USER_AGENT"
      ],
      "default": "MODE_NONE"
    },
    "TwinSynchronizationState": {
      "type": "string",
      "enum": [
        "OUT_OF_SYNC",
        "DISABLED",
        "SYNCING",
        "IN_SYNC"
      ],
      "default": "OUT_OF_SYNC",
      "description": " - OUT_OF_SYNC: As soon as it connects after it was offline or when it goes errorless offline or when twin enabled has been changed to true.\n - DISABLED: As soon as twin enabled is set to false.\n - SYNCING: As soon as device connects, successfully signs in and batch observe is called on device from the cloud.\n - IN_SYNC: As soon as current device resources values are received and applied to twin database. Twin was successfully reconciled after device reconnect and is kept up to date using an active subscription to device resource changes."
    },
    "googlerpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "grpcgatewaypbContent": {
      "type": "object",
      "properties": {
        "contentType": {
          "type": "string"
        },
        "data": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "grpcgatewaypbCreateResourceResponse": {
      "type": "object",
      "properties": {
        "data": {
          "$ref": "#/definitions/pbResourceCreated"
        }
      }
    },
    "grpcgatewaypbDeleteResourceResponse": {
      "type": "object",
      "properties": {
        "data": {
          "$ref": "#/definitions/pbResourceDeleted"
        }
      }
    },
    "grpcgatewaypbResource": {
      "type": "object",
      "properties": {
        "types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "data": {
          "$ref": "#/definitions/pbResourceChanged"
        }
      }
    },
    "grpcgatewaypbUpdateResourceResponse": {
      "type": "object",
      "properties": {
        "data": {
          "$ref": "#/definitions/pbResourceUpdated"
        }
      }
    },
    "pbClearCacheResponse": {
      "type": "object"
    },
    "pbCommandMetadata": {
      "type": "object",
      "properties": {
        "connectionId": {
          "type": "string"
        },
        "sequence": {
          "type": "string",
          "format": "uint64"
        }
      }
    },
    "pbConnection": {
      "type": "object",
      "properties": {
        "status": {
          "$ref": "#/definitions/pbConnectionStatus"
        },
        "id": {
          "type": "string",
          "description": "when status is ONLINE, this field contains the connection id. To update state offline, this field must be same as the one in the previous message."
        },
        "connectedAt": {
          "type": "string",
          "format": "int64",
          "title": "timestamp when the device was connected"
        },
        "protocol": {
          "$ref": "#/definitions/ConnectionProtocol",
          "description": "application protocol. It need to be set when the status is ONLINE."
        },
        "serviceId": {
          "type": "string",
          "description": "The service.ID, which identify the device being served, must be set when the status is ONLINE. However, during an OFFLINE event, they will be sed to empty values."
        }
      }
    },
    "pbConnectionStatus": {
      "type": "string",
      "enum": [
        "OFFLINE",
        "ONLINE"
      ],
      "default": "OFFLINE"
    },
    "pbDevice": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "name": {
          "type": "string"
        },
        "metadata": {
          "$ref": "#/definitions/DeviceMetadata"
        },
        "manufacturerName": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/pbLocalizedString"
          }
        },
        "modelNumber": {
          "type": "string"
        },
        "interfaces": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "protocolIndependentId": {
          "type": "string"
        },
        "data": {
          "$ref": "#/definitions/pbResourceChanged"
        },
        "ownershipStatus": {
          "$ref": "#/definitions/DeviceOwnershipStatus",
          "title": "ownership status of the device"
        },
        "endpoints": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "endpoints with schemas which are hosted by the device"
        }
      }
    },
    "pbDeviceOAuthClient": {
      "type": "object",
      "properties": {
        "clientId": {
          "type": "string",
          "title": "@gotags: yaml:\"clientID\""
        },
        "audience": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "providerName": {
          "type": "string",
          "title": "@gotags: yaml:\"providerName\""
        }
      }
    },
    "pbDisownDeviceResponse": {
      "type": "object"
    },
    "pbEndpointInformation": {
      "type": "object",
      "properties": {
        "endpoint": {
          "type": "string"
        },
        "priority": {
          "type": "string",
          "format": "int64"
        }
      }
    },
    "pbFinishInitializeResponse": {
      "type": "object"
    },
    "pbFinishOwnDeviceResponse": {
      "type": "object"
    },
    "pbGetConfigurationResponse": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "title": "deprecated, use build_info.version"
        },
        "buildDate": {
          "type": "string",
          "title": "deprecated, use build_info.build_date"
        },
        "commitHash": {
          "type": "string",
          "title": "deprecated, use build_info.commit_hash"
        },
        "commitDate": {
          "type": "string",
          "title": "deprecated, use build_info.commit_date"
        },
        "releaseUrl": {
          "type": "string",
          "title": "deprecated, use build_info.release_url"
        },
        "isInitialized": {
          "type": "boolean",
          "title": "user don't need to call initialize endpoint"
        },
        "deviceAuthenticationMode": {
          "$ref": "#/definitions/GetConfigurationResponseDeviceAuthenticationMode"
        },
        "remoteProvisioning": {
          "$ref": "#/definitions/pbRemoteProvisioning"
        },
        "owner": {
          "type": "string"
        },
        "buildInfo": {
          "$ref": "#/definitions/servicepbBuildInfo"
        },
        "ui": {
          "$ref": "#/definitions/pbUIConfiguration"
        }
      }
    },
    "pbGetIdentityCertificateResponse": {
      "type": "object",
      "properties": {
        "certificate": {
          "type": "string",
          "format": "byte",
          "title": "PEM format"
        }
      }
    },
    "pbIdentityCertificateChallenge": {
      "type": "object",
      "properties": {
        "certificateSigningRequest": {
          "type": "string",
          "format": "byte",
          "title": "in PEM format"
        },
        "state": {
          "type": "string",
          "title": "for pairing calls"
        }
      }
    },
    "pbInitializePreSharedKey": {
      "type": "object",
      "properties": {
        "subjectId": {
          "type": "string",
          "description": "ID of the client application that is used to identify the client application by the device."
        },
        "key": {
          "type": "string",
          "description": "Associated secret to the client application ID. Only first 16bytes is used."
        },
        "save": {
          "type": "boolean",
          "description": "If true, the client application will be save subject_id and key to the persistent storage."
        }
      }
    },
    "pbInitializeRequest": {
      "type": "object",
      "properties": {
        "preSharedKey": {
          "$ref": "#/definitions/pbInitializePreSharedKey"
        },
        "jwks": {
          "type": "object"
        }
      },
      "title": "The client application must be initialized when GetConfigurationResponse.is_initialized is set to false.\nThe initialization depends on the GetConfigurationResponse.device_authentication_mode.\nFor:\n - PRE_SHARED_KEY - pre_shared_key values need to be set.\n - X509 - jwks need to be set only if GetConfigurationResponse.remote_provisioning.mode is set to USER_AGENT"
    },
    "pbInitializeResponse": {
      "type": "object",
      "properties": {
        "identityCertificateChallenge": {
          "$ref": "#/definitions/pbIdentityCertificateChallenge",
          "description": "If is set, the initialization process will be paused.\nFor the next call FinishInitialize, request must contain provided identity_certificate_challenge.state."
        }
      }
    },
    "pbLocalizedString": {
      "type": "object",
      "properties": {
        "language": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "pbOffboardDeviceResponse": {
      "type": "object"
    },
    "pbOnboardDeviceResponse": {
      "type": "object"
    },
    "pbOwnDeviceResponse": {
      "type": "object",
      "properties": {
        "identityCertificateChallenge": {
          "$ref": "#/definitions/pbIdentityCertificateChallenge",
          "title": "Filled when OwnDeviceRequest.get_identity_csr is true"
        }
      }
    },
    "pbPolicy": {
      "type": "object",
      "properties": {
        "bitFlags": {
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "pbRemoteProvisioning": {
      "type": "object",
      "properties": {
        "currentTime": {
          "type": "string",
          "format": "int64",
          "title": "@gotags: yaml:\"-\""
        },
        "jwtOwnerClaim": {
          "type": "string",
          "title": "@gotags: yaml:\"ownerClaim\""
        },
        "id": {
          "type": "string",
          "description": "@gotags: yaml:\"hubID\"",
          "title": "Hub ID"
        },
        "coapGateway": {
          "type": "string",
          "description": "@gotags: yaml:\"coapGateway\"",
          "title": "coap-gateway in format coaps+tcp://host:port"
        },
        "certificateAuthorities": {
          "type": "string",
          "description": "@gotags: yaml:\"-\"",
          "title": "certificate_authorities in format PEM - can contain multiple certificates"
        },
        "authority": {
          "type": "string",
          "description": "@gotags: yaml:\"authority\"",
          "title": "authority in format https://host:port"
        },
        "certificateAuthority": {
          "type": "string",
          "description": "@gotags: yaml:\"certificateAuthority\"",
          "title": "certificate_authority in format https://host:port"
        },
        "webOauthClient": {
          "$ref": "#/definitions/pbWebOAuthClient",
          "description": "@gotags: yaml:\"webOAuthClient\"",
          "title": "http-gateway in format https://host:port\nstring http_gateway_address = 10; // @gotags: yaml:\"-\""
        },
        "deviceOauthClient": {
          "$ref": "#/definitions/pbDeviceOAuthClient",
          "title": "@gotags: yaml:\"deviceOAuthClient\""
        },
        "mode": {
          "$ref": "#/definitions/RemoteProvisioningMode",
          "title": "@gotags: yaml:\"mode\""
        },
        "userAgent": {
          "$ref": "#/definitions/pbUserAgent",
          "title": "@gotags: yaml:\"userAgent\""
        },
        "caPool": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "@gotags: yaml:\"caPool\""
        }
      }
    },
    "pbResetRequest": {
      "type": "object"
    },
    "pbResetResponse": {
      "type": "object"
    },
    "pbResourceChanged": {
      "type": "object",
      "properties": {
        "resourceId": {
          "$ref": "#/definitions/pbResourceId"
        },
        "content": {
          "$ref": "#/definitions/resourceaggregatepbContent"
        },
        "status": {
          "$ref": "#/definitions/resourceaggregatepbStatus"
        },
        "auditContext": {
          "$ref": "#/definitions/resourceaggregatepbAuditContext"
        },
        "eventMetadata": {
          "$ref": "#/definitions/resourceaggregatepbEventMetadata"
        },
        "etag": {
          "type": "string",
          "format": "byte",
          "title": "etag of the resource used by twin synchronization"
        },
        "openTelemetryCarrier": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "Open telemetry data propagated to asynchronous events"
        }
      }
    },
    "pbResourceCreated": {
      "type": "object",
      "properties": {
        "resourceId": {
          "$ref": "#/definitions/pbResourceId"
        },
        "status": {
          "$ref": "#/definitions/resourceaggregatepbStatus"
        },
        "content": {
          "$ref": "#/definitions/resourceaggregatepbContent"
        },
        "auditContext": {
          "$ref": "#/definitions/resourceaggregatepbAuditContext"
        },
        "eventMetadata": {
          "$ref": "#/definitions/resourceaggregatepbEventMetadata"
        },
        "openTelemetryCarrier": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "Open telemetry data propagated to asynchronous events"
        }
      }
    },
    "pbResourceDeleted": {
      "type": "object",
      "properties": {
        "resourceId": {
          "$ref": "#/definitions/pbResourceId"
        },
        "status": {
          "$ref": "#/definitions/resourceaggregatepbStatus"
        },
        "content": {
          "$ref": "#/definitions/resourceaggregatepbContent"
        },
        "auditContext": {
          "$ref": "#/definitions/resourceaggregatepbAuditContext"
        },
        "eventMetadata": {
          "$ref": "#/definitions/resourceaggregatepbEventMetadata"
        },
        "openTelemetryCarrier": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "Open telemetry data propagated to asynchronous events"
        }
      }
    },
    "pbResourceId": {
      "type": "object",
      "properties": {
        "deviceId": {
          "type": "string"
        },
        "href": {
          "type": "string"
        }
      }
    },
    "pbResourceLinksPublished": {
      "type": "object",
      "properties": {
        "deviceId": {
          "type": "string"
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/resourceaggregatepbResource"
          }
        },
        "auditContext": {
          "$ref": "#/definitions/resourceaggregatepbAuditContext"
        },
        "eventMetadata": {
          "$ref": "#/definitions/resourceaggregatepbEventMetadata"
        },
        "openTelemetryCarrier": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "Open telemetry data propagated to asynchronous events"
        }
      },
      "title": "https://github.com/openconnectivityfoundation/cloud-services/blob/master/swagger2.0/oic.wk.rd.swagger.json#L173"
    },
    "pbResourceUpdated": {
      "type": "object",
      "properties": {
        "resourceId": {
          "$ref": "#/definitions/pbResourceId"
        },
        "status": {
          "$ref": "#/definitions/resourceaggregatepbStatus"
        },
        "content": {
          "$ref": "#/definitions/resourceaggregatepbContent"
        },
        "auditContext": {
          "$ref": "#/definitions/resourceaggregatepbAuditContext"
        },
        "eventMetadata": {
          "$ref": "#/definitions/resourceaggregatepbEventMetadata"
        },
        "openTelemetryCarrier": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "title": "Open telemetry data propagated to asynchronous events"
        }
      }
    },
    "pbTwinSynchronization": {
      "type": "object",
      "properties": {
        "state": {
          "$ref": "#/definitions/TwinSynchronizationState"
        },
        "syncingAt": {
          "type": "string",
          "format": "int64",
          "description": "unix timestamp in nanoseconds (https://golang.org/pkg/time/#Time.UnixNano) when synchronization started."
        },
        "inSyncAt": {
          "type": "string",
          "format": "int64",
          "description": "unix timestamp in nanoseconds (https://golang.org/pkg/time/#Time.UnixNano) when synchronization finished."
        },
        "commandMetadata": {
          "$ref": "#/definitions/pbCommandMetadata",
          "description": "when status is SYNCING, this field contains the connection id. To update state to IN_SYNC, this field must be same as the one in the previous message."
        },
        "forceSynchronizationAt": {
          "type": "string",
          "format": "int64",
          "description": "unix timestamp in nanoseconds (https://golang.org/pkg/time/#Time.UnixNano) when the force synchronization has been started. 0 means force synchronization has never started."
        }
      }
    },
    "pbUIConfiguration": {
      "type": "object",
      "properties": {
        "defaultDiscoveryTimeout": {
          "type": "string",
          "format": "int64",
          "title": "default discovery timeout in nanoseconds"
        }
      },
      "description": "similar to https://github.com/plgd-dev/hub/blob/4c4861a4bc483ba4080a1d448063da392eff4026/grpc-gateway/pb/hubConfiguration.proto#L61",
      "title": "UI configuration"
    },
    "pbUserAgent": {
      "type": "object",
      "properties": {
        "csrChallengeStateExpiration": {
          "type": "string",
          "format": "int64",
          "description": "@gotags: yaml:\"csrChallengeStateExpiration\"",
          "title": "in nanoseconds"
        }
      }
    },
    "pbWebOAuthClient": {
      "type": "object",
      "properties": {
        "clientId": {
          "type": "string",
          "title": "@gotags: yaml:\"clientID\""
        },
        "audience": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "protobufNullValue": {
      "type": "string",
      "enum": [
        "NULL_VALUE"
      ],
      "default": "NULL_VALUE",
      "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value."
    },
    "resourceaggregatepbAuditContext": {
      "type": "object",
      "properties": {
        "userId": {
          "type": "string"
        },
        "correlationId": {
          "type": "string"
        },
        "owner": {
          "type": "string"
        }
      }
    },
    "resourceaggregatepbContent": {
      "type": "object",
      "properties": {
        "data": {
          "type": "string",
          "format": "byte"
        },
        "contentType": {
          "type": "string"
        },
        "coapContentFormat": {
          "type": "integer",
          "format": "int32",
          "title": "-1 means content-format was not provided"
        }
      }
    },
    "resourceaggregatepbEventMetadata": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "format": "uint64"
        },
        "timestamp": {
          "type": "string",
          "format": "int64"
        },
        "connectionId": {
          "type": "string"
        },
        "sequence": {
          "type": "string",
          "format": "uint64",
          "title": "sequence number within the same connection_id; the ResourceChanged event uses the value to skip old events, other event types might not fill the value"
        },
        "hubId": {
          "type": "string",
          "title": "the hub which sent the event"
        }
      }
    },
    "resourceaggregatepbResource": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string"
        },
        "deviceId": {
          "type": "string"
        },
        "resourceTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "interfaces": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "anchor": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "supportedContentTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "validUntil": {
          "type": "string",
          "format": "int64"
        },
        "policy": {
          "$ref": "#/definitions/pbPolicy"
        },
        "endpointInformations": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/pbEndpointInformation"
          }
        }
      },
      "title": "https://github.com/openconnectivityfoundation/core/blob/master/schemas/oic.links.properties.core-schema.json"
    },
    "resourceaggregatepbStatus": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "OK",
        "BAD_REQUEST",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "NOT_FOUND",
        "UNAVAILABLE",
        "NOT_IMPLEMENTED",
        "ACCEPTED",
        "ERROR",
        "METHOD_NOT_ALLOWED",
        "CREATED",
        "CANCELED",
        "NOT_MODIFIED"
      ],
      "default": "UNKNOWN",
      "description": " - CANCELED: Canceled indicates the operation was canceled (typically by the user).\n - NOT_MODIFIED: Valid indicates the content hasn't changed. (provided etag in GET request is same as the resource etag)."
    },
    "servicepbBuildInfo": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "title": "version of the service"
        },
        "buildDate": {
          "type": "string",
          "title": "build date of the service"
        },
        "commitHash": {
          "type": "string",
          "title": "commit hash of the service"
        },
        "commitDate": {
          "type": "string",
          "title": "commit date of the service"
        },
        "releaseUrl": {
          "type": "string",
          "title": "release url of the service"
        }
      }
    }
  },
  "securityDefinitions": {
    "OAuth2": {
      "type": "oauth2",
      "description": "OAuth2 authorization is used when GetConfigurationResponse.device_authentication_mode == X509",
      "flow": "accessCode"
    }
  }
}