openapi: 3.2.0
info:
  title: Device location Location verification API
  description: Service Enabling Network Function API for location verification
  termsOfService: http://swagger.io/terms/
  contact:
    email: project-email@sample.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.1.0
servers:
- url: '{apiRoot}/{basePath}'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root
    basePath:
      default: location/v0
      description: Base path for the device location API
security:
- oAuth2ClientCredentials: []
- three_legged:
  - device-location-read
tags:
- name: Location verification
paths:
  /verify:
    post:
      tags:
      - Location verification
      summary: Execute location verification for a user equipment
      operationId: verifyLocation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyLocationRequest'
        required: true
      responses:
        '200':
          description: Location verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyLocationResponse'
        '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:
  schemas:
    Accuracy:
      description: Accuracy expected for location verification in km
      type: number
      minimum: 2
      maximum: 200
      example: 50
    MSISDN:
      type: string
      pattern: ^\+?[0-9]{5,15}$
      example: '123456789'
      description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'.
    Latitude:
      description: Latitude component of location
      type: number
      format: double
      minimum: -90
      maximum: 90
      example: 50.735851
    Ipv6Addr:
      type: string
      format: ipv6
      allOf:
      - pattern: ^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$
      - pattern: ^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
      description: "IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:\n  - address - The /128 subnet is optional for single addresses:\n    - 2001:db8:85a3:8d3:1319:8a2e:370:7344\n    - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128\n  - address/mask - an IP v6 number with a mask:\n    - 2001:db8:85a3:8d3::0/64\n    - 2001:db8:85a3:8d3::/64\n"
    VerificationResult:
      description: Result of a verification request, true on match
      type: boolean
    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180
      example: 7.10066
    ExternalId:
      type: string
      example: 123456789@domain.com
    VerifyLocationRequest:
      type: object
      properties:
        ueId:
          $ref: '#/components/schemas/UeId'
        uePort:
          $ref: '#/components/schemas/Port'
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
        accuracy:
          $ref: '#/components/schemas/Accuracy'
      required:
      - ueId
      - latitude
      - longitude
      - accuracy
    VerifyLocationResponse:
      type: object
      required:
      - verificationResult
      properties:
        verificationResult:
          $ref: '#/components/schemas/VerificationResult'
    Port:
      type: integer
      minimum: 0
      maximum: 65535
      description: User equipment port. Device port may be required along with IP address to identify the target device
      example: 5060
    ErrorInfo:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
    Ipv4Addr:
      type: string
      format: ipv4
      pattern: ^([01]?\d\d?|2[0-4]\d|25[0-5])(?:\.(?:[01]?\d\d?|2[0-4]\d|25[0-5])){3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$
      example: 192.168.0.1/24
      description: "IPv4 address may be specified in form <address/mask> as:\n  - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.\n  - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.\n    In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.\n"
    UeId:
      description: User equipment identifier
      type: object
      properties:
        externalId:
          $ref: '#/components/schemas/ExternalId'
        msisdn:
          $ref: '#/components/schemas/MSISDN'
        ipv4Addr:
          $ref: '#/components/schemas/Ipv4Addr'
        ipv6Addr:
          $ref: '#/components/schemas/Ipv6Addr'
      minProperties: 1
  responses:
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: UNAUTHORIZED
            message: 'Authorization failed: ...'
    Generic404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: NOT_FOUND
            message: The specified resource is not found
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: INVALID_INPUT
            message: Invalid input
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: SERVICE_UNAVAILABLE
            message: Service unavailable
    Generic500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: INTERNAL_SERVER_ERROR
            message: Internal server error
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: FORBIDDEN
            message: 'Operation not allowed: ...'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
    three_legged:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            device-location-read: Read device location
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/