LocationAPI.yaml

openapi: 3.1.0
info:
  contact:
    url: https://forge.etsi.org/rep/mec/gs013-location-api
  title: ETSI GS MEC 013 - Location API
  version: 3.1.1
  description: The ETSI MEC ISG MEC013 Location API described using OpenAPI.
  license:
    name: BSD-3-Clause
    url: 'https://forge.etsi.org/legal-matters'
externalDocs:
  description: ETSI MEC013 V3.1.1 Location API
  url: 'https://www.etsi.org/deliver/etsi_gs/MEC/001_099/013/03.01.01_60/gs_mec013v030101p.pdf'
servers:
  - url: 'https://localhost/location/v2'
tags:
  - name: 'location'

paths:
  /queries/distance:
    get:
      tags:
        - 'location'
      summary: 'Query information about distance from a user to a location or between two users'
      description: 'The GET method is used to query information about distance from a user to a location or between two users.'
      operationId: distanceGET
      parameters:
        - $ref: '#/components/parameters/Query.Address'
        - $ref: '#/components/parameters/Query.Location'
      responses:
        '200':
          description: 'Upon success, a response body containing the list of distance information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  terminalDistance:
                    $ref: '#/components/schemas/TerminalDistance'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /queries/users:
    get:
      tags:
        - 'location'
      summary: 'Query location information about a specific UE or a group of Ues'
      description: 'The GET method is used to query location information about a specific UE or a group of Ues.'
      operationId: usersGET
      parameters:
        - $ref: '#/components/parameters/Query.ZoneId'
        - $ref: '#/components/parameters/Query.AccessPointId'
        - $ref: '#/components/parameters/Query.Address_3'
      responses:
        '200':
          description: 'Upon success, a response body containing the list of user location information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userList:
                    $ref: '#/components/schemas/UserList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /queries/zones:
    get:
      tags:
        - 'location'
      summary: 'Query the information about one or more specific zones or a list of zones.'
      description: 'The GET method is used to query the information about one or more specific zones or a list of zones.'
      operationId: zonesGET
      parameters:
        - $ref: '#/components/parameters/Query.ZoneId'
      responses:
        '200':
          description: 'Upon success, a response body containing the list of zone information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  zoneList:
                    $ref: '#/components/schemas/ZoneList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /queries/zones/{zoneId}:
    get:
      tags:
        - 'location'
      summary: 'Query information about a specific zone'
      description: 'The GET method is used to query the information about a specific zone.'
      operationId: zoneGetById
      parameters:
        - $ref: '#/components/parameters/Path.ZoneId'
      responses:
        '200':
          description: 'Upon success, a response body containing the zone information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  zoneInfo:
                    $ref: '#/components/schemas/ZoneInfo'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /queries/zones/{zoneId}/accessPoints:
    get:
      tags:
        - 'location'
      summary: 'Query information about a specific access point or a list of access points under a zone'
      description: 'The GET method is used to query the information about a specific access point or a list of access points under a zone.'
      operationId: accessPointsGET
      parameters:
        - $ref: '#/components/parameters/Path.ZoneId'
        - $ref: '#/components/parameters/Query.AccessPointId'
      responses:
        '200':
          description: 'Upon success, a response body containing the list of access point information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessPointList:
                    $ref: '#/components/schemas/AccessPointList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /queries/zones/{zoneId}/accessPoints/{accessPointId}:
    get:
      tags:
        - 'location'
      summary: 'Query information about a specific access point under a zone.'
      description: 'The GET method is used to query the information about a specific access point under a zone.'
      operationId: accessPointGetById
      parameters:
        - $ref: '#/components/parameters/Path.ZoneId'
        - $ref: '#/components/parameters/Path.AccessPointId'
      responses:
        '200':
          description: 'Upon success, a response body containing the access point information is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessPointInfo:
                    $ref: '#/components/schemas/AccessPointInfo'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'queries'
  /subscriptions/area:
    get:
      tags:
        - 'location'
      summary: 'Retrieves information about the subscriptions for this requestor.'
      description: 'The GET method is used to request information about the subscriptions for this requestor.'
      operationId: areaSubListGET
      parameters:
        - $ref: '#/components/parameters/Query.Subscription_type' 
      responses:
        '200':
          description: "Upon success, a response body containing the list of links to requestor's subscriptions is returned."
          content:
            application/json:
              schema:
                type: object
                required:
                  - notificationSubscriptionList
                properties:
                  notificationSubscriptionList:
                    $ref: '#/components/schemas/NotificationSubscriptionList'
                examples:
                  - notificationSubscriptionList:
                      subscription:
                        - href: 'http://meAppServer.example.com/location/v2/subscriptions/area/subscription123'
                          subscriptionType: 'UserAreaSubscription'
                      resourceURL:
                          href: 'http://meAppServer.example.com/location/v2/subscriptions/area'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
    post:
      tags:
        - 'location'
      summary: 'Creates subscription to area notifications.'
      description: 'The POST method is used to create a new subscription to area notifications.'
      operationId: areaSubPOST
      requestBody:
        description: 'Subscription to be created'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userAreaSubscription:
                  $ref: '#/components/schemas/UserAreaSubscription'
              examples:
                - userAreaSubscription:
                    subscriptionType: 'userAreaSubscription'
                    clientCorrelator: '0123'
                    callbackReference: 'http://my.callback.com/area_notification/some-id'
                    _links:
                      self:
                        href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
                    areaDefine:
                      shape: 1
                      points:
                        - latitude: -80.86302
                          longitude: 41.277306
                      radius:
                    addressList:
                      - acr:10.0.0.1
                      - acr:10.0.0.2
                    trackingAccuracy: 10.99
                    expiryDeadline:
                      seconds: 1973507343
                      nanoSeconds": 0
      responses:
        '201':
          description: 'Indicates successful resource creation, where the resource URI shall be returned in the HTTP Location header field.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userAreaSubscription:
                    $ref: '#/components/schemas/UserAreaSubscription'
                examples:
                  - userAreaSubscription:
                      subscriptionType: 'userAreaSubscription'
                      clientCorrelator: '0123'
                      callbackReference: 'http://my.callback.com/area_notification/some-id'
                      _links:
                        self:
                          href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
                      areaDefine:
                      shape: 1
                      points:
                        - latitude: -80.86302
                          longitude: 41.277306
                      radius:
                      addressList:
                        - acr:10.0.0.1
                        - acr:10.0.0.2
                      trackingAccuracy: 10.99
                      expiryDeadline:
                        seconds: 1973507343
                        nanoSeconds": 0
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
      callbacks:
        notification:
          '{$request.body#/userAreaSubscription.callbackReference}':
            post:
              summary: 'Callback POST used to send a notification'
              description: 'Notification from Location service, content based on subscription type'
              operationId: areaNotificationPOST
              requestBody:
                description: 'Subscription notification'
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        userAreaNotification:
                          $ref: '#/components/schemas/UserAreaNotification'
                      examples:
                        - userAreaNotification:
                            notificationType: 'UserAreaNotification'
                            timestamp:
                              seconds: 1673507343
                              nanoSeconds": 0
                            address: 'acr:10.0.0.1'
                            userLocationEvent: 'ENTERING_AREA_EVENT'
                            _links:
                              subscription:
                                href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
              responses:
                '204':
                  $ref: '#/components/responses/204'
      x-swagger-router-controller: 'subscriptions'
  /subscriptions/area/{subscriptionId}:
    get:
      tags:
        - 'location'
      summary: 'Retrieve subscription information'
      description: 'The GET method is used to retrieve information about this subscription.'
      operationId: areaSubGET
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the specific zone subscription is returned.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - userAreaSubscription
                properties:
                  userAreaNotification:
                    $ref: '#/components/schemas/UserAreaNotification'
                examples:
                  - userAreaNotification:
                      notificationType: 'UserAreaNotification'
                      address: 'acr:10.0.0.1'
                      userLocationEvent: 'ENTERING_AREA_EVENT'
                      _links:
                        subscription:
                          href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
    put:
      tags:
        - 'location'
      summary: 'Updates a subscription information'
      description: 'The PUT method is used to update the existing subscription.'
      operationId: areaSubPUT
      requestBody:
        description: 'Subscription to be modified'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userAreaNotification:
                  $ref: '#/components/schemas/UserAreaNotification'
              examples:
                - userAreaNotification:
                    notificationType: 'UserAreaNotification'
                    address: 'acr:10.0.0.1'
                    userLocationEvent: 'ENTERING_AREA_EVENT'
                    _links:
                      subscription:
                        href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the updated subscription is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userAreaNotification:
                    $ref: '#/components/schemas/UserAreaNotification'
                examples:
                  - userAreaNotification:
                      notificationType: 'UserAreaNotification'
                      address: 'acr:10.0.0.1'
                      userLocationEvent: 'ENTERING_AREA_EVENT'
                      _links:
                        subscription:
                          href: http://meAppServer.example.com/location/v2/subscriptions/area/subscription123
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '412':
          $ref: '#/components/responses/412'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
    delete:
      tags:
        - 'location'
      summary: 'Cancel a subscription'
      description: 'The DELETE method is used to cancel the existing subscription.'
      operationId: areaSubDELETE
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
  /subscriptions/distance:
    get:
      tags:
        - 'location'
      summary: 'Retrieves all active subscriptions to distance change notifications'
      description: 'This operation is used for retrieving all active subscriptions to a distance change notifications.'
      operationId: distanceSubListGET
      responses:
        '200':
          description: "Upon success, a response body containing the list of links to requestor's subscriptions is returned."
          content:
            application/json:
              schema:
                type: object
                required:
                  - notificationSubscriptionList
                properties:
                  notificationSubscriptionList:
                    $ref: '#/components/schemas/NotificationSubscriptionList'
                examples:
                  - notificationSubscriptionList:
                      subscription:
                        - href: 'http://meAppServer.example.com/location/v2/subscriptions/distance/subscription123'
                          subscriptionType: 'UserDistanceSubscription'
                      resourceURL:
                          href: 'http://meAppServer.example.com/location/v2/subscriptions/distance'
    post:
      tags:
        - 'location'
      summary: 'Creates a subscription for distance change notification'
      description: 'Creates a subscription to the Location Service for a distance change notification.'
      operationId: distanceSubPOST
      requestBody:
        description: 'The POST method is used to create a new subscription to user distance notifications.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userDistanceSubscription:
                  $ref: '#/components/schemas/UserDistanceSubscription'
              examples:
                - userDistanceSubscription:
                    subscriptionType: 'UserDistanceSubscription'
                    clientCorrelator: '0123'
                    callbackReference: 'http://my.callback.com/user-distance/some-id'
                    referenceAddress:
                      - 'acr:10.0.0.3'
                    monitoredAddress:
                      - 'acr:10.0.0.1'
                      - 'acr:10.0.0.2'
                    distance: 100
                    trackingAccuracy: 10
                    criteria: 'AllWithinDistance'
                    checkImmediate: true
      responses:
        '201':
          description: 'Successful subscription'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userDistanceSubscription:
                    $ref: '#/components/schemas/UserDistanceSubscription'
                examples:
                  - userDistanceSubscription:
                      subscriptionType: 'UserDistanceSubscription'
                      clientCorrelator: '0123'
                      callbackReference: 'http://my.callback.com/user-distance/some-id'
                      referenceAddress:
                        - 'acr:10.0.0.3'
                      monitoredAddress:
                        - 'acr:10.0.0.1'
                        - 'acr:10.0.0.2'
                      distance: 100
                      trackingAccuracy: 10
                      criteria: 'AllWithinDistance'
                      checkImmediate: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
      callbacks:
        notification:
          '{$request.body#/userDistanceSubscription.callbackReference}':
            post:
              summary: 'Callback POST used to send a notification'
              description: 'Notification from Location service, content based user distance subscription type'
              operationId: distanceNotificationPOST
              requestBody:
                description: 'User Distance Notification'
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        userDistanceNotification:
                          $ref: '#/components/schemas/UserDistanceNotification'
                      examples:
                        - userDistanceNotification:
                            notificationType: 'UserDistanceNotification'
                            timestamp:
                              seconds: 1673507343
                              nanoSeconds": 0
                            monitoredUsers: 
                              - user:
                                  address: 'acr:10.0.0.1'
                                  accessPointId: '001010000000000000000000000000001'
                                  zoneId: 'zone01'
                                  timestamp:
                                    seconds: 1673507343
                                    nanoSeconds": 0
                                resourceURL: 'http://meAppServer.example.com/location/v3/queries/users'
                            distanceEvent: 'AllWithinDistance'
                            _links:
                              subscription:
                                href: 'http://meAppServer.example.com/location/v3/subscriptions/distance/subscription123'
              responses:
                '204':
                  $ref: '#/components/responses/204'
      x-swagger-router-controller: 'subscriptions'
  /subscriptions/distance/{subscriptionId}:
    get:
      tags:
        - 'location'
      summary: 'Retrieve user distance subscription information'
      description: 'The GET method is used to retrieve information about user distance subscription subscription.'
      operationId: distanceSubGET
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the specific distance event subscription is returned.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - UserDistanceSubscription
                properties:
                  userDistanceSubscription:
                    $ref: '#/components/schemas/UserDistanceSubscription'
                examples:
                  - userDistanceSubscription:
                      subscriptionType: 'UserDistanceSubscription'
                      clientCorrelator: '0123'
                      callbackReference: 'http://my.callback.com/user-distance/some-id'
                      referenceAddress:
                        - 'acr:10.0.0.3'
                      monitoredAddress:
                        - 'acr:10.0.0.1'
                        - 'acr:10.0.0.2'
                      distance: 100
                      trackingAccuracy: 10
                      criteria: 'AllWithinDistance'
                      checkImmediate: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
    put:
      tags:
        - 'location'
      summary: 'Updates a user distance subscription information'
      description: 'The PUT method is used to update the existing user distance subscription.'
      operationId: distanceSubPUT
      requestBody:
        description: 'Subscription to be modified'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userDistanceSubscription:
                  $ref: '#/components/schemas/UserDistanceSubscription'
              examples:
                - userDistanceSubscription:
                    subscriptionType: 'UserDistanceSubscription'
                    clientCorrelator: '0123'
                    callbackReference: 'http://my.callback.com/user-distance/some-id'
                    referenceAddress:
                      - 'acr:10.0.0.3'
                    monitoredAddress:
                      - 'acr:10.0.0.1'
                      - 'acr:10.0.0.2'
                    distance: 100
                    trackingAccuracy: 10
                    criteria: 'AllWithinDistance'
                    checkImmediate: true
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the updated subscription is returned.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userDistanceSubscription:
                    $ref: '#/components/schemas/UserDistanceSubscription'
                examples:
                  - userDistanceSubscription:
                      subscriptionType: 'UserDistanceSubscription'
                      clientCorrelator: '0123'
                      callbackReference: 'http://my.callback.com/user-distance/some-id'
                      referenceAddress:
                        - 'acr:10.0.0.3'
                      monitoredAddress:
                        - 'acr:10.0.0.1'
                        - 'acr:10.0.0.2'
                      distance: 100
                      trackingAccuracy: 10
                      criteria: 'AllWithinDistance'
                      checkImmediate: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '412':
          $ref: '#/components/responses/412'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
    delete:
      tags:
        - 'location'
      summary: 'Cancel a subscription'
      description: 'The DELETE method is used to cancel the existing subscription.'
      operationId: distanceSubDELETE
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
  /subscriptions/users:
    get:
      tags:
        - 'location'
      summary: 'Retrieves information about the subscriptions for the requestor'
      description: 'The GET method is used to request information about the subscriptions for the requestor. '
      operationId: userSubListGET
      parameters:
        - $ref: '#/components/parameters/Query.Subscription_type_2'
        - $ref: '#/components/parameters/Query.Address_2'
      responses:
        '200':
          description: "Upon success, a response body containing the list of links to requestor's subscriptions is returned."
          content:
            application/json:
              schema:
                type: object
                required:
                  - notificationSubscriptionList
                properties:
                  notificationSubscriptionList:
                    $ref: '#/components/schemas/NotificationSubscriptionList'
                examples:
                  - notificationSubscriptionList:
                      subscription:
                        - href: 'http://meAppServer.example.com/location/v2/subscriptions/users/subscription123'
                          subscriptionType: 'UserLocationEventSubscription'
                        - href: 'http://meAppServer.example.com/location/v2/subscriptions/users/subscription456'
                          subscriptionType: 'UserLocationPeriodicSubscription'
                      resourceURL:
                          href: 'http://meAppServer.example.com/location/v2/subscriptions/users'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
    post:
      tags:
        - 'location'
      summary: 'Create subscription to UE location notifications.'
      description: 'The POST method is used to create a new subscription to UE location notifications.'
      operationId: userSubPOST
      requestBody:
        description: 'Subscription to be created'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userLocationEventSubscription:
                  $ref: '#/components/schemas/UserLocationEventSubscription'
                userLocationPeriodicSubscription:
                  $ref: '#/components/schemas/UserLocationPeriodicSubscription'
              examples:
                - userLocationEventSubscription:
                    subscriptionType: 'UserLocationEventSubscription'
                    callbackReference: 'http://my.callback.com/user-location-notification/some-id'
                    address: 'acr:10.0.0.1'
                    locationEventCriteria:
                      - ENTERING_AREA_EVENT
      responses:
        '201':
          description: 'Indicates successful subscription creation.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  userLocationEventSubscription:
                    $ref: '#/components/schemas/UserLocationEventSubscription'
                  userLocationPeriodicSubscription:
                    $ref: '#/components/schemas/UserLocationPeriodicSubscription'
                examples:
                  - userLocationEventSubscription:
                      subscriptionType: 'UserLocationEventSubscription'
                      callbackReference: 'http://my.callback.com/user-location-notification/some-id'
                      address: 'acr:10.0.0.1'
                      locationEventCriteria:
                        - ENTERING_AREA_EVENT
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      callbacks:
        notification:
          '{$request.body#/userLocationEventSubscription.callbackReference}':
            post:
              summary: 'Callback POST used to send a notification'
              description: 'Notification from Location service, content based on subscription type'
              operationId: userNotificationPOST
              requestBody:
                description: 'User LocationEvent Notification'
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        userLocationEventNotification:
                          $ref: '#/components/schemas/UserLocationEventNotification'
                        userLocationPeriodicNotification:
                          $ref: '#/components/schemas/UserLocationPeriodicNotification'
                      examples:
                        - userLocationEventNotification:
                            notificationType: 'UserLocationEventNotification'
                            timestamp:
                              seconds: 1673507343
                              nanoseconds: 0
                            address: 'acr:10.0.0.1'
                            userLocationEvent: 'ENTERING_AREA_EVENT'
                            zoneId: 'zone01'
                            accessPointId: '001010000000000000000000000000001'
                            _links:
                              subscription:
                                href: "http://meAppServer.example.com/location/v3/subscriptions/user/subscription123"
              responses:
                '204':
                  $ref: '#/components/responses/204'
      x-swagger-router-controller: 'subscriptions'
  /subscriptions/users/{subscriptionId}:
    get:
      tags:
        - 'location'
      summary: 'Retrieve subscription information'
      description: 'The GET method is used to retrieve information about this subscription. '
      operationId: userSubGET
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the specific Location event subscription is returned.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - UserLocationEventSubscription
                properties:
                  userLocationEventSubscription:
                    $ref: '#/components/schemas/UserLocationEventSubscription'
                  userLocationPeriodicSubscription:
                    $ref: '#/components/schemas/UserLocationPeriodicSubscription'
                examples:
                  - userLocationEventSubscription:
                      subscriptionType: 'UserLocationEventSubscription'
                      callbackReference: 'http://my.callback.com/user-location-notification/some-id'
                      address: 'acr:10.0.0.1'
                      locationEventCriteria:
                        - ENTERING_AREA_EVENT
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      x-swagger-router-controller: 'subscriptions'
    put:
      tags:
        - 'location'
      summary: 'Updates a subscription information'
      description: 'The PUT method is used to update the existing subscription.'
      operationId: userSubPUT
      requestBody:
        description: 'Subscription to be modified'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                  userLocationEventSubscription:
                    $ref: '#/components/schemas/UserLocationEventSubscription'
                  userLocationPeriodicSubscription:
                    $ref: '#/components/schemas/UserLocationPeriodicSubscription'
              examples:
                - userLocationEventSubscription:
                    subscriptionType: 'UserLocationEventSubscription'
                    callbackReference: 'http://my.callback.com/user-location-notification/some-id'
                    address: 'acr:10.0.0.1'
                    locationEventCriteria:
                      - ENTERING_AREA_EVENT
      parameters:
        - $ref: '#/components/parameters/Path.SubscrId'
      responses:
        '200':
          description: 'Upon success, a response body containing data type describing the updated subscription is returned. '
          content:
            application/json:
              schema:
                type: object
                properties:
                  userLocationEventSubscription:
                    $ref: '#/components/schemas/UserLocationEventSubscription'
                  userLocationPeriodicSubscription:
                    $ref: '#/components/schemas/UserLocationPeriodicSubscription'
                examples:
                  - userLocationEventSubscription:
                      subscriptionType: 'UserLocationEventSubscription'
                      callbackReference: 'http://my.callback.com/user-location-notification/some-id'
                      address: 'acr:10.0.0.1'
                      locationEventCriteria:
                        - ENTERING_AREA_EVENT
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'