GSMA Camara Project Device Geofencing Subscriptions API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Device Geofencing Subscriptions API
  description: >-
    Device Geofencing Subscriptions API enables the subscription to geographical
    position changes. With this API, customers can create subscriptions for
    their devices to receive notifications when a device enters or exits a
    specified area. If the geofencing-state of a device changes, the event
    subscriber will be notified back.
  version: 0.3.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.4.0
externalDocs:
  description: Project documentation at Camara
  url: https://github.com/camaraproject/DeviceLocation
servers:
  - url: '{apiRoot}/geofencing-subscriptions/v0.3'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root
tags:
  - name: Geofencing Subscriptions
    description: >-
      Operations to manage event subscription on geofencing events for leaving
      and entering an area
paths:
  /subscriptions:
    post:
      tags:
        - Geofencing Subscriptions
      summary: Global System for Mobile Communications Create a geofencing subscription for a device
      description: >-
        Create a subscription for a device to receive notifications when a
        device enters or exits a specified area
      operationId: createSubscription
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - openId:
            - >-
              geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-entered:create
            - >-
              geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-left:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
            examples:
              CIRCLE_AREA_ENTERED:
                $ref: '#/components/examples/REQUEST_CIRCLE_AREA_ENTERED'
        required: true
      callbacks:
        notifications:
          '{$request.body#/sink}':
            post:
              summary: notifications callback
              description: >
                Important: this endpoint is to be implemented by the API
                consumer.

                The Geofencing server will call this endpoint whenever a
                Geofencing event occurs.

                `operationId` value will have to be replaced accordingly with WG
                API specific semantic
              operationId: postNotification
              parameters:
                - $ref: '#/components/parameters/x-correlator'
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: '#/components/schemas/CloudEvent'
                    examples:
                      CIRCLE_AREA_ENTERED:
                        $ref: '#/components/examples/CIRCLE_AREA_ENTERED'
                      CIRCLE_AREA_LEFT:
                        $ref: '#/components/examples/CIRCLE_AREA_LEFT'
                      SUBSCRIPTION_ENDS:
                        $ref: '#/components/examples/SUBSCRIPTION_ENDS'
                      SUBSCRIPTION_UNPROCESSABLE:
                        $ref: '#/components/examples/SUBSCRIPTION_UNPROCESSABLE'
              responses:
                '204':
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/x-correlator'
                '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 (Successful creation of subscription)
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '202':
          description: >-
            Request accepted to be processed. It applies for async creation
            process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '400':
          $ref: '#/components/responses/CreateSubscriptionBadRequest400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '422':
          $ref: '#/components/responses/CreateSubscriptionUnprocessableEntity422'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    get:
      tags:
        - Geofencing Subscriptions
      summary: Global System for Mobile Communications Retrieve a list of geofencing event subscription
      description: Retrieve a list of geofencing event subscription(s)
      operationId: retrieveGeofencingSubscriptionList
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - openId:
            - geofencing-subscriptions:read
      responses:
        '200':
          description: List of event subscription details
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: array
                minItems: 0
                items:
                  $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
  /subscriptions/{subscriptionId}:
    get:
      tags:
        - Geofencing Subscriptions
      summary: Global System for Mobile Communications Operation to retrieve a subscription based on the provided ID
      description: >-
        retrieve Geofencing subscription information for a given subscription
        ID.
      operationId: retrieveGeofencingSubscription
      security:
        - openId:
            - geofencing-subscriptions:read
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
        - $ref: '#/components/parameters/x-correlator'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    delete:
      tags:
        - Geofencing Subscriptions
      summary: Global System for Mobile Communications Delete a Geofencing event subscription
      operationId: deleteGeofencingSubscription
      description: delete a given Geofencing subscription.
      security:
        - openId:
            - geofencing-subscriptions:delete
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
        - $ref: '#/components/parameters/x-correlator'
      responses:
        '202':
          description: >-
            Request accepted to be processed. It applies for async deletion
            process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '204':
          description: Geofencing subscription deleted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  securitySchemes:
    openId:
      description: OpenID Connect authentication
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      description: >-
        Subscription identifier that was obtained from the create event
        subscription operation
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    ErrorInfo:
      description: The error info object for possible error cases
      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
    SubscriptionRequest:
      description: The request for creating a event-type event subscription
      type: object
      required:
        - sink
        - protocol
        - config
        - types
      properties:
        protocol:
          $ref: '#/components/schemas/Protocol'
        sink:
          type: string
          format: url
          description: >-
            The address to which events shall be delivered using the selected
            protocol.
          example: https://endpoint.example.com/sink
        sinkCredential:
          allOf:
            - description: >-
                A sink credential provides authentication or authorization
                information necessary to enable delivery of events to a target.
            - $ref: '#/components/schemas/SinkCredential'
        types:
          description: |
            Camara Event types eligible to be delivered by this subscription.
            Note: As of now we enforce to have only event type per subscription.
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/SubscriptionEventType'
        config:
          $ref: '#/components/schemas/Config'
      discriminator:
        propertyName: protocol
        mapping:
          HTTP: '#/components/schemas/HTTPSubscriptionRequest'
          MQTT3: '#/components/schemas/MQTTSubscriptionRequest'
          MQTT5: '#/components/schemas/MQTTSubscriptionRequest'
          AMQP: '#/components/schemas/AMQPSubscriptionRequest'
          NATS: '#/components/schemas/NATSSubscriptionRequest'
          KAFKA: '#/components/schemas/ApacheKafkaSubscriptionRequest'
    Protocol:
      type: string
      enum:
        - HTTP
        - MQTT3
        - MQTT5
        - AMQP
        - NATS
        - KAFKA
      description: Identifier of a delivery protocol. Only HTTP is allowed for now
      example: HTTP
    Config:
      description: >
        Implementation-specific configuration parameters needed by the
        subscription manager for acquiring events.

        In CAMARA we have predefined attributes like `subscriptionExpireTime`,
        `subscriptionMaxEvents`, `initialEvent`

        Specific event type attributes must be defined in `subscriptionDetail`

        Note: if a request is performed for several event type, all subscribed
        event will use same `config` parameters.
      type: object
      required:
        - 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) requested by
            the API consumer.
        subscriptionMaxEvents:
          type: integer
          description: >-
            Identifies the maximum number of event reports to be generated (>=1)
            requested by the API consumer - Once this number is reached, the
            subscription ends.
          minimum: 1
          example: 5
        initialEvent:
          type: boolean
          description: >
            Set to `true` by API consumer if consumer wants to get an event as
            soon as the subscription is created and current situation reflects
            event request.

            Example: Consumer request area entered event. If consumer sets
            initialEvent to true and device is already in the geofence, an event
            is triggered
    SinkCredential:
      type: object
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
            - ACCESSTOKEN
            - REFRESHTOKEN
          description: The type of the credential.
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: '#/components/schemas/PlainCredential'
          ACCESSTOKEN: '#/components/schemas/AccessTokenCredential'
          REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential'
      required:
        - credentialType
    PlainCredential:
      type: object
      description: A plain credential as a combination of an identifier and a secret.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          required:
            - identifier
            - secret
          properties:
            identifier:
              description: The identifier might be an account or username.
              type: string
            secret:
              description: The secret might be a password or passphrase.
              type: string
    AccessTokenCredential:
      type: object
      description: An access token credential.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          properties:
            accessToken:
              description: >-
                REQUIRED. An access token is a previously acquired token
                granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: >-
                REQUIRED. An absolute UTC instant at which the token shall be
                considered expired.
            accessTokenType:
              description: >-
                REQUIRED. Type of the access token (See [OAuth
                2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
          required:
            - accessToken
            - accessTokenExpiresUtc
            - accessTokenType
    RefreshTokenCredential:
      type: object
      description: An access token credential with a refresh token.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          properties:
            accessToken:
              description: >-
                REQUIRED. An access token is a previously acquired token
                granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: >-
                REQUIRED. An absolute UTC instant at which the token shall be
                considered expired.
            accessTokenType:
              description: >-
                REQUIRED. Type of the access token (See [OAuth
                2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
            refreshToken:
              description: >-
                REQUIRED. An refresh token credential used to acquire access
                tokens.
              type: string
            refreshTokenEndpoint:
              type: string
              format: uri
              description: >-
                REQUIRED. A URL at which the refresh token can be traded for an
                access token.
      required:
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
        - refreshToken
        - refreshTokenEndpoint
    SubscriptionDetail:
      description: The detail of the requested event subscription
      type: object
      properties:
        device:
          $ref: '#/components/schemas/Device'
        area:
          $ref: '#/components/schemas/Area'
      required:
        - device
        - area
    SubscriptionEventType:
      type: string
      description: |
        area-entered - Event triggered when the device enters the given area

        area-left - Event triggered when the device leaves the given area
      enum:
        - org.camaraproject.geofencing-subscriptions.v0.area-entered
        - org.camaraproject.geofencing-subscriptions.v0.area-left
    NotificationEventType:
      type: string
      description: |
        area-entered - Event triggered when the device enters the given area

        area-left - Event triggered when the device leaves the given area

        subscription-ends - Event triggered when the subscription ends
      enum:
        - org.camaraproject.geofencing-subscriptions.v0.area-entered
        - org.camaraproject.geofencing-subscriptions.v0.area-left
        - org.camaraproject.geofencing-subscriptions.v0.subscription-ends
    Subscription:
      description: Represents a event-type subscription.
      type: object
      required:
        - sink
        - protocol
        - config
        - types
        - id
        - startsAt
      properties:
        protocol:
          $ref: '#/components/schemas/Protocol'
        sink:
          type: string
          format: url
          description: >-
            The address to which events shall be delivered using the selected
            protocol.
          example: https://endpoint.example.com/sink
        sinkCredential:
          $ref: '#/components/schemas/SinkCredential'
        types:
          description: |
            Camara Event types eligible to be delivered by this subscription.
          type: array
          items:
            type: string
        config:
          $ref: '#/components/schemas/Config'
        id:
          type: string
          description: >-
            The unique identifier of the subscription in the scope of the
            subscription manager. When this information is contained within an
            event notification, this concept SHALL be referred as
            `subscriptionId` as per [Commonalities Event Notification
            Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
          example: '1119920371'
        startsAt:
          type: string
          format: date-time
          description: Date when the event subscription will begin/began
        expiresAt:
          type: string
          format: date-time
          description: >-
            Date when the event subscription will expire. Only provided when
            `subscriptionExpireTime` is indicated by API client or Telco
            Operator has specific policy about that.
        status:
          type: string
          description: >-
            Current status of the subscription - Management of Subscription
            State engine is not mandatory for now. Note not all statuses may be
            considered to be implemented. Details:
              - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.
              - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
              - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
              - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
              - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).
          enum:
            - ACTIVATION_REQUESTED
            - ACTIVE
            - EXPIRED
            - INACTIVE
            - DELETED
      discriminator:
        propertyName: protocol
        mapping:
          HTTP: '#/components/schemas/HTTPSubscriptionResponse'
          MQTT3: '#/components/schemas/MQTTSubscriptionResponse'
          MQTT5: '#/components/schemas/MQTTSubscriptionResponse'
          AMQP: '#/components/schemas/AMQPSubscriptionResponse'
          NATS: '#/components/schemas/NATSSubscriptionResponse'
          KAFKA: '#/components/schemas/ApacheKafkaSubscriptionResponse'
    SubscriptionAsync:
      description: >-
        Response for a event-type subscription request managed asynchronously
        (Creation or Deletion)
      type: object
      properties:
        id:
          $ref: '#/components/schemas/SubscriptionId'
    SubscriptionId:
      type: string
      description: >-
        The unique identifier of the subscription in the scope of the
        subscription manager. When this information is contained within an event
        notification, this concept SHALL be referred as `subscriptionId` as per
        [Commonalities Event Notification
        Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
      example: qs15-h556-rt89-1298
    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`


        NOTE1: 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. When returned as part of a response, the device object must
        include the same identifier values that were provided originally. Please
        note that IP addresses of devices can change and get reused, so the
        original values may no longer identify the same device. They identified
        the device at the time of the subscription request.

        NOTE2: for the Commonalities release v0.4, we are enforcing that the
        networkAccessIdentifier is only part of the schema for future-proofing,
        and CAMARA does not currently allow its use. After the CAMARA
        meta-release work is concluded and the relevant issues are resolved, its
        use will need to be explicitly documented in the guidelines.
      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,
        prefixed with '+'.
      type: string
      pattern: ^\+[1-9][0-9]{4,14}$
      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: [email protected]
    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
    Area:
      type: object
      properties:
        areaType:
          $ref: '#/components/schemas/AreaType'
      required:
        - areaType
      discriminator:
        propertyName: areaType
        mapping:
          CIRCLE: '#/components/schemas/Circle'
    AreaType:
      type: string
      description: |
        Type of this area.
        CIRCLE - The area is defined as a circle.
      enum:
        - CIRCLE
    Circle:
      description: Circular area
      allOf:
        - $ref: '#/components/schemas/Area'
        - type: object
          properties:
            center:
              $ref: '#/components/schemas/Point'
            radius:
              type: integer
              description: >-
                Expected accuracy for the subscription event of device location
                in m, from location (radius)
              minimum: 2000
              maximum: 200000
          required:
            - center
            - radius
      example:
        areaType: CIRCLE
        center:
          latitude: 50.735851
          longitude: 7.10066
        radius: 50000
    Point:
      type: object
      description: Coordinates (latitude, longitude) defining a location in a map
      required:
        - latitude
        - longitude
      properties:
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
      example:
        latitude: 50.735851
        longitude: 7.10066
    Latitude:
      description: Latitude component of a location
      type: number
      format: double
      minimum: -90
      maximum: 90
      example: 50.735851
    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180
      example: 7.10066
    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.
        source:
          $ref: '#/components/schemas/Source'
        type:
          $ref: '#/components/schemas/NotificationEventType'
        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)
          enum:
            - '1.0'
        datacontenttype:
          type: string
          description: >-
            media-type that describes the event payload encoding, must be
            "application/json" for CAMARA APIs
          enum:
            - 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.geofencing-subscriptions.v0.area-left: '#/components/schemas/EventAreaLeft'
          org.camaraproject.geofencing-subscriptions.v0.area-entered: '#/components/schemas/EventAreaEntered'
          org.camaraproject.geofencing-subscriptions.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds'
    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: >
        Identifies the context in which an event happened - be a non-empty
        `URI-reference` like:

        - URI with a DNS authority:
          * https://github.com/cloudevents
          * mailto:[email protected]
        - Universally-unique URN with a UUID:
          * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
        - Application-specific identifier:
          * /cloudevents/spec/pull/123
          * 1-555-123-4567
      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'
    EventAreaLeft:
      description: event structure for event when the device leaves the area
      allOf:
        - $ref: '#/components/schemas/CloudEvent'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/AreaLeft'
    EventAreaEntered:
      description: event structure for event when the device enters the area
      allOf:
        - $ref: '#/components/schemas/CloudEvent'
        - type

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/global-system-for-mobile-communications/refs/heads/main/openapi/device-geofencing-subscriptions-api-openapi.yml