openapi: 3.0.3
info:
  title: Device Status
  description: |
    This API provides the customer with the ability to query device:
      - Roaming Status
      - Connectivity Status


    Moreover, this API extends the functionality by allowing users customers to subscribe to events associated with these status queries.

    # Introduction

    ## Roaming Status
    API consumer is able to verify whether a certain user device is in roaming situation (or not). This capability is provided in 2 ways:
      - via direct request with the roaming situation in the response.
      - via a subscription  request - in this case the roaming situation is not in the response but event notification is sent back to the event subscriber when roaming situation has changed.

    The verification of the roaming situation depends on the network's ability. Additionally to the roaming status, when the device is in roaming situation, visited country information could be returned in the response.

    ## Connectivity Status

    API consumer is able to verify whether a certain user device is connected to the network via data- or sms-usage. This capability is provided in 2 ways:
      - via direct request with the connectivity situation in the response.
      - via a subscription  request - in this case the connectivity situation is not in the response but event notification is sent back to the event subscriber when connectivity situation has changed.

    ## Possible Use-Cases
    Device status verification could be useful in scenario such as (not exhaustive):
      - For regulatory reasons, where a customer may need to be within a certain jurisdiction, or out with others, in order for transactions to be authorized
      - For security / fraud reasons, to establish that a customer is located where they claim to be
      - For service delivery reasons, to ensure that the customer has access to particular service, and will not incur roaming charges in accessing them


    # Relevant terms and definitions

    * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication.
      At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device.

    * **Roaming** : Roaming status - `true`, if device is in roaming situation - `false` else.

    * **Country** : Country code and name - visited country information, provided if the device is in roaming situation.

    * **Connectivity** : Connectivity status.
      - `CONNECTED_SMS`, if device is connected to the network via SMS usage
      - `CONNECTED_DATA`, if device is connected to the network via data usage
      - `NOT_CONNECTED`, if device is not connected to the network

    # API Functionality

    The API exposes following capabilities:

    ## Device roaming situation

    The endpoint `POST /roaming` allows to get roaming status and country information (if device in roaming situation) synchronously.

    ## Device connectivity situation

    The endpoint `POST /connectivity` allows to get current connectivity status information synchronously.

    ## Device status subscription

    These endpoints allow to manage event subscription on roaming device status event.
    The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.

    It is mandatory in the subscription to provide the event `type` subscribed are several are managed in this API.

    Following event ``type`` are managed for this API:
      - ``org.camaraproject.device-status.v0.roaming-status`` - Event triggered when the device switch from roaming ON to roaming OFF and conversely

      - ``org.camaraproject.device-status.v0.roaming-on`` - Event triggered when the device switch from roaming OFF to roaming ON

      - ``org.camaraproject.device-status.v0.roaming-off``: Event triggered when the device switch from roaming ON to roaming OFF

      - ``org.camaraproject.device-status.v0.roaming-change-country``: Event triggered when the device in roaming change country code

      - ``org.camaraproject.device-status.v0.connectivity-data``: Event triggered when the device is connected to the network for Data usage.

      - ``org.camaraproject.device-status.v0.connectivity-sms``: Event triggered when the device is connected to the network for SMS usage

      - ``org.camaraproject.device-status.v0.connectivity-disconnected``: Event triggered when the device is not connected.

    Note: Additionally to these list, ``org.camaraproject.device-status.v0.subscription-ends`` notification `type` is sent when the subscription ends.
    This notification does not require dedicated subscription.
    It is used when the subscription expire time (optionally set by the requester) has been reached or if the API server has to stop sending notification prematurely.

    ### Notifications callback

    The  `notifications` callback describes the format of event notifications and expected responses to the messages sent when the event occurs. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.

    **WARNING**: This callback endpoint must be exposed and reachable on the listener side under 'notificationUrl` defined in the `webhook` attribute.

    ## Further info and support

    (FAQs will be added in a later version of the documentation)

  contact:
    email: contact@spryfoxnetworks.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.5.1
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/

servers:
  - url: https://labs-api.spryfoxnetworks.com/qpcloud-monet-swagger/device-status/v0
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root

tags:
  - name: Device connectivity status
    description: Operations to get the current connectivity status of a device
  - name: Device roaming status
    description: Operation to get device roaming status and country information (if roaming) synchronously
  - name: Device status subscription
    description: Operation to manage event subscription on device status event (roaming, connectivity)

paths:
  /connectivity:
    post:
      tags:
        - Device connectivity status
      summary: "Get the current connectivity status information"
      description: Get the current connectivity status information
      operationId: getConnectivityStatus
      security:
        - openId:
            - device-status:connectivity:read
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestConnectivityStatus"
        required: true
      responses:
        "200":
          description: Contains information about current connectivity status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectivityStatusResponse"
              examples:
                Connected-With-SMS:
                  value:
                    connectivityStatus: CONNECTED_SMS
                Connected-With-DATA:
                  value:
                    connectivityStatus: CONNECTED_DATA
                Not-Connected:
                  value:
                    connectivityStatus: NOT_CONNECTED
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /roaming:
    post:
      tags:
        - Device roaming status
      summary: "Get the current roaming status and the country information"
      description: Get the current roaming status and the country information
      operationId: getRoamingStatus
      security:
        - openId:
            - device-status:roaming:read
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestRoamingStatus"
        required: true
      responses:
        "200":
          description: Contains information about current roaming status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoamingStatusResponse"
              examples:
                No-Country-Name:
                  value:
                    roaming: true
                    countryCode: 901
                    countryName: []
                Single-Country-Code:
                  value:
                    roaming: true
                    countryCode: 262
                    countryName: ["DE"]
                Multiple-Country-Codes:
                  value:
                    roaming: true
                    countryCode: 340
                    countryName: ["BL", "GF", "GP", "MF", "MQ"]
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /subscriptions:
    post:
      tags:
        - Device status subscription
      summary: "Create a device status event subscription for a device"
      description: Create a device status event subscription for a device
      operationId: createDeviceStatusSubscription
      security:
        - openId:
            - device-status:subscriptions:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSubscription"
        required: true
      callbacks:
        notifications:
          "{$request.body#/webhook/notificationUrl}":
            post:
              tags:
                - Session notifications callback
              summary: "Session notifications callback"
              description: |
                Important: this endpoint is to be implemented by the API consumer.
                The Device status server will call this endpoint whenever any device status related event occurs.
              operationId: postNotification
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: "#/components/schemas/CloudEvent"
                    examples:
                      roaming-status:
                        $ref: "#/components/examples/ROAMING_STATUS"
                      roaming-change-country:
                        $ref: "#/components/examples/ROAMING_CHANGE_COUNTRY"
                      roaming-on:
                        $ref: "#/components/examples/ROAMING_ON"
                      roaming-off:
                        $ref: "#/components/examples/ROAMING_OFF"
                      connectivity-data:
                        $ref: "#/components/examples/CONNECTIVITY_DATA"
                      connectivity-sms:
                        $ref: "#/components/examples/CONNECTIVITY_SMS"
                      connectivity-disconnected:
                        $ref: "#/components/examples/CONNECTIVITY_DISCONNECTED"
                      subscription-ends:
                        $ref: "#/components/examples/SUBSCRIPTION_ENDS"
              responses:
                "204":
                  description: Successful notification
                "400":
                  $ref: "#/components/responses/Generic400"
                "401":
                  $ref: "#/components/responses/Generic401"
                "403":
                  $ref: "#/components/responses/Generic403"
                "500":
                  $ref: "#/components/responses/Generic500"
                "503":
                  $ref: "#/components/responses/Generic503"
              security:
                - {}
                - notificationsBearerAuth: []

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionInfo"
        "202":
          description: Request accepted to be processed. It applies for async creation process.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionAsync"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          $ref: "#/components/responses/Generic409"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    get:
      tags:
        - Device status subscription
      summary: "Retrieve a list of device status event subscription"
      description: Retrieve a list of device status event subscription(s)
      operationId: retrieveSubscriptionList
      security:
        - openId:
            - device-status:subscriptions:read
      responses:
        "200":
          description: List of event subscription details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionInfo"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /subscriptions/{subscriptionId}:
    get:
      tags:
        - Device status subscription
      summary: "Retrieve a device status event subscription for a device"
      operationId: retrieveSubscription
      description: retrieve event subscription information for a given subscription.
      security:
        - openId:
            - device-status:subscriptions:read
      parameters:
        - name: subscriptionId
          in: path
          description: Subscription identifier that was obtained from the create subscription operation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionInfo"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    delete:
      tags:
        - Device status subscription
      summary: "Delete a device status event subscription for a device"
      operationId: deleteSubscription
      description: delete a  given event subscription.
      security:
        - openId:
            - device-status:subscriptions:delete
      parameters:
        - name: subscriptionId
          in: path
          description: Subscription identifier that was obtained from the create event subscription operation
          required: true
          schema:
            type: string
      responses:
        "204":
          description: event subscription deleted
        "202":
          description: Request accepted to be processed. It applies for async deletion process.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionAsync"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  schemas:
    RoamingStatusResponse:
      type: object
      required:
        - roaming
      properties:
        roaming:
          $ref: "#/components/schemas/ActiveRoaming"
        countryCode:
          $ref: "#/components/schemas/CountryCode"
        countryName:
          $ref: "#/components/schemas/CountryName"

    ActiveRoaming:
      description: Roaming status. True, if it is roaming
      type: boolean

    ConnectivityStatusResponse:
      type: object
      required:
        - connectivityStatus
      properties:
        connectivityStatus:
          $ref: "#/components/schemas/ConnectivityStatus"

    ConnectivityStatus:
      description: |
        CONNECTED_DATA: The device is connected to the network for Data usage

        CONNECTED_SMS: The device is connected to the network for SMS usage

        NOT_CONNECTED: The device is not connected
      type: string
      enum:
        - CONNECTED_DATA
        - CONNECTED_SMS
        - NOT_CONNECTED

    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

        The developer can choose to provide the below specified device identifiers:

        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`

        NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1

    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
      type: string
      pattern: '^\+?[0-9]{5,15}$'
      example: "123456789"

    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      example: "123456789@domain.com"

    DeviceIpv4Addr:
      type: object
      description: |
        The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

        If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then  the same address should be specified for both publicAddress and privateAddress.

        If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

        In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
      properties:
        publicAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        privateAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        publicPort:
          $ref: "#/components/schemas/Port"
      anyOf:
        - required: [publicAddress, privateAddress]
        - required: [publicAddress, publicPort]
      example:
        publicAddress: "84.125.93.10"
        publicPort: 59765

    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "84.125.93.10"

    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535

    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

    CountryCode:
      description: The Mobile country code (MCC) as an geographic region identifier for the country and the dependent areas.
      type: integer

    CountryName:
      description: The ISO 3166 ALPHA-2 country-codes of mapped to mobile country code(MCC). If there is mapping of one MCC to multiple countries, then we have list of countries. If there is no mapping of MCC to any country, then an empty array [] shall be returned..
      type: array
      items:
        type: string

    RequestRoamingStatus:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
      required:
        - device

    RequestConnectivityStatus:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
      required:
        - device

    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description

    CreateSubscription:
      description: The request for creating a Device Status event subscription
      type: object
      required:
        - webhook
        - subscriptionDetail
      properties:
        subscriptionDetail:
          $ref: "#/components/schemas/SubscriptionDetail"
        subscriptionExpireTime:
          type: string
          format: date-time
          example: 2023-01-17T13:18:23.682Z
          description: The subscription expiration time in date-time format.
        webhook:
          $ref: "#/components/schemas/Webhook"

    Webhook:
      description: Webhook information for event channel
      type: object
      required:
        - notificationUrl
      properties:
        notificationUrl:
          type: string
          example: https://application-server.com
          description: https callback address where the event notification must be POST-ed
        notificationAuthToken:
          type: string
          example: c8974e592c2fa383d4a3960714
          description: |
            OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken

    SubscriptionDetail:
      description: The detail of the requested event subscription
      type: object
      required:
        - type
        - device
      properties:
        device:
          $ref: "#/components/schemas/Device"
        type:
          $ref: "#/components/schemas/SubscriptionCreationEventType"

    SubscriptionEventType:
      type: string
      description: |
        roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely

        roaming-on - Event triggered when the device switch from roaming OFF to roaming ON

        roaming-off - Event triggered when the device switch from roaming ON to roaming OFF

        roaming-change-country - Event triggered when the device in roaming change country code

        connectivity-data - Event triggered when the device is connected to the network for Data usage.

        connectivity-sms - Event triggered when the device is connected to the network for SMS usage

        connectivity-disconnected - Event triggered when the device is not connected.

        subscription-ends - Event triggered when the subscription is terminated
      enum:
        - org.camaraproject.device-status.v0.roaming-status
        - org.camaraproject.device-status.v0.roaming-on
        - org.camaraproject.device-status.v0.roaming-off
        - org.camaraproject.device-status.v0.roaming-change-country
        - org.camaraproject.device-status.v0.connectivity-data
        - org.camaraproject.device-status.v0.connectivity-sms
        - org.camaraproject.device-status.v0.connectivity-disconnected
        - org.camaraproject.device-status.v0.subscription-ends

    SubscriptionCreationEventType:
      type: string
      description: |
        roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely

        roaming-on - Event triggered when the device switch from roaming OFF to roaming ON

        roaming-off - Event triggered when the device switch from roaming ON to roaming OFF

        roaming-change-country - Event triggered when the device in roaming change country code

        connectivity-data - Event triggered when the device is connected to the network for Data usage.

        connectivity-sms - Event triggered when the device is connected to the network for SMS usage

        connectivity-disconnected - Event triggered when the device is not connected.

      enum:
        - org.camaraproject.device-status.v0.roaming-status
        - org.camaraproject.device-status.v0.roaming-on
        - org.camaraproject.device-status.v0.roaming-off
        - org.camaraproject.device-status.v0.roaming-change-country
        - org.camaraproject.device-status.v0.connectivity-data
        - org.camaraproject.device-status.v0.connectivity-sms
        - org.camaraproject.device-status.v0.connectivity-disconnected

    SubscriptionInfo:
      description: Represents a device status subscription.
      allOf:
        - $ref: "#/components/schemas/CreateSubscription"
        - type: object
          properties:
            subscriptionId:
              $ref: "#/components/schemas/SubscriptionId"
            startsAt:
              type: string
              format: date-time
              description: date time when subscription started
            expiresAt:
              type: string
              format: date-time
              description: date time when subscription will expire or expired
          required:
            - subscriptionId
            - type

    SubscriptionAsync:
      description: Response for a device status operation managed asynchronously (Creation or Deletion)
      type: object
      properties:
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"

    SubscriptionId:
      type: string
      description: The event subscription identifier.
      example: qs15-h556-rt89-1298

    CloudEvent:
      description: The notification callback
      required:
        - id
        - source
        - specversion
        - type
        - time
        - data
      properties:
        id:
          type: string
          description: identifier of this event, that must be unique in the source context.
          example: sd5e-uy52-88t4-za66
        source:
          $ref: "#/components/schemas/Source"
        type:
          $ref: "#/components/schemas/SubscriptionEventType"
        specversion:
          type: string
          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
          example: "1.0"
        datacontenttype:
          type: string
          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
          example: application/json
        data:
          type: object
          description: Event details payload described in each CAMARA API and referenced by its type
        time:
          $ref: "#/components/schemas/DateTime"
      discriminator:
        propertyName: "type"
        mapping:
          org.camaraproject.device-status.v0.roaming-status: "#/components/schemas/EventRoamingStatus"
          org.camaraproject.device-status.v0.roaming-change-country: "#/components/schemas/EventRoamingChangeCountry"
          org.camaraproject.device-status.v0.roaming-off: "#/components/schemas/EventRoamingOff"
          org.camaraproject.device-status.v0.roaming-on: "#/components/schemas/EventRoamingOn"
          org.camaraproject.device-status.v0.connectivity-data: "#/components/schemas/EventConnectivityData"
          org.camaraproject.device-status.v0.connectivity-sms: "#/components/schemas/EventConnectivitySms"
          org.camaraproject.device-status.v0.connectivity-disconnected: "#/components/schemas/EventConnectivityDisconnected"
          org.camaraproject.device-status.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds"

    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: "Identifies the context in which an event happened in the specific Provider Implementation."
      example: https://notificationSendServer12.supertelco.com

    DateTime:
      type: string
      format: date-time
      description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
      example: "2018-04-05T17:31:00Z"

    EventRoamingStatus:
      description: event structure for roaming status change
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/RoamingStatus"

    EventRoamingOn:
      description: event structure for roaming on change
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/BasicDeviceEventData"

    EventRoamingOff:
      description: event structure for roaming off change
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/BasicDeviceEventData"

    EventRoamingChangeCountry:
      description: event structure for roaming change country
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/RoamingChangeCountry"

    EventConnectivityData:
      description: event structure for connectivity data usage
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/BasicDeviceEventData"

    EventConnectivitySms:
      description: event structure for connectivity SMS usage
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/BasicDeviceEventData"

    EventConnectivityDisconnected:
      description: event structure for disconnection
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/BasicDeviceEventData"

    EventSubscriptionEnds:
      description: event structure for event subscription ends
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/SubscriptionEnds"

    BasicDeviceEventData:
      description: Event detail structure for basic device events
      type: object
      required:
        - device
      properties:
        device:
          $ref: "#/components/schemas/Device"
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"

    RoamingStatus:
      description: Event detail structure for org.camaraproject.device-status.v0.roaming-status event
      type: object
      required:
        - device
        - roaming
      properties:
        device:
          $ref: "#/components/schemas/Device"
        roaming:
          type: boolean
          description: Roaming status. True, if it is roaming.
        countryCode:
          $ref: "#/components/schemas/CountryCode"
        countryName:
          $ref: "#/components/schemas/CountryName"
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"

    RoamingChangeCountry:
      description: Event detail structure for org.camaraproject.device-status.v0.roaming-on event
      type: object
      required:
        - device
      properties:
        device:
          $ref: "#/components/schemas/Device"
        countryCode:
          $ref: "#/components/schemas/CountryCode"
        countryName:
          $ref: "#/components/schemas/CountryName"
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"

    SubscriptionEnds:
      description: Event detail structure for org.camaraproject.device-status.v0.subscription-ends event
      type: object
      required:
        - device
        - terminationReason
      properties:
        device:
          $ref: "#/components/schemas/Device"
        terminationReason:
          type: string
          enum: ["SUBSCRIPTION_EXPIRED", "NETWORK_TERMINATED"]
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"

  responses:
    Generic400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 400
            code: "INVALID_ARGUMENT"
            message: "Client specified an invalid argument, request body or query param"
    Generic401:
      description: Authentication problem with the client request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 401
            code: "UNAUTHENTICATED"
            message: "Request not authenticated due to missing, invalid, or expired credentials"
    Generic403:
      description: Client does not have sufficient permission
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 403
            code: "PERMISSION_DENIED"
            message: "Client does not have sufficient permissions to perform this action"
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 404
            code: NOT_FOUND
            message: "The specified resource is not found"
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: CONFLICT
            message: "The specified resource is in a conflict"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 500
            code: "INTERNAL"
            message: "Server error"
    Generic503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 503
            code: "UNAVAILABLE"
            message: "Service unavailable"

  examples:
    ROAMING_STATUS:
      value:
        id: "123654"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.roaming-status
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456789
          roaming: true
          countryCode: 208
          countryName: FR
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-17T13:18:23.682Z

    ROAMING_OFF:
      value:
        id: "123655"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.roaming-off
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456788
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-18T13:18:23.682Z

    ROAMING_ON:
      value:
        id: "123656"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.roaming-on
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456787
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z

    ROAMING_CHANGE_COUNTRY:
      value:
        id: "123657"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.roaming-change-country
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456789
          countryCode: 214
          countryName: ["ES"]
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z

    CONNECTIVITY_DATA:
      value:
        id: "123656"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.connectivity-data
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456787
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z

    CONNECTIVITY_SMS:
      value:
        id: "123656"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.connectivity-sms
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456787
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z

    CONNECTIVITY_DISCONNECTED:
      value:
        id: "123656"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.connectivity-disconnected
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456787
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z

    SUBSCRIPTION_ENDS:
      value:
        id: "123658"
        source: https://notificationSendServer12.supertelco.com
        type: org.camaraproject.device-status.v0.subscription-ends
        specversion: "1.0"
        datacontenttype: application/json
        data:
          device:
            phoneNumber: 123456789
          terminationReason: SUBSCRIPTION_EXPIRED
          subscriptionId: qs15-h556-rt89-1298
        time: 2023-01-19T13:18:23.682Z
