openapi: 3.0.0
info:
  version: '1.0.2'
  title: 'LMF Location'
  description: |
    LMF Location Service.
    © 2019, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
servers:
  - url: '{apiRoot}/nlmf-loc/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in subclause 4.4 of 3GPP TS 29.501
security:
  - {}
  - oAuth2ClientCredentials:
      - nlmf-loc
paths:
  /determine-location:
    post:
      summary: Determine Location of an UE
      operationId: DetermineLocation
      tags:
        - Determine Location
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputData'
        required: true
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationData'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        '504':
          $ref: 'TS29571_CommonData.yaml#/components/responses/504'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows: 
        clientCredentials: 
          tokenUrl: '{nrfApiRoot}/oauth2/token'
          scopes:
            nlmf-loc: Access to the Nlmf_Location API
  schemas:
#
# COMPLEX TYPES
#
    InputData:
      type: object
      not:
        required: [ ecgi, ncgi ]
      properties:
        externalClientType:
          $ref: '#/components/schemas/ExternalClientType'
        correlationID:
          $ref: '#/components/schemas/CorrelationID'        
        amfId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfInstanceId'
        locationQoS:
          $ref: '#/components/schemas/LocationQoS'
        supportedGADShapes:
          type: array
          items:
            $ref: '#/components/schemas/SupportedGADShapes'
          minItems: 1
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        pei:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Pei'
        gpsi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
        ecgi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ecgi'
        ncgi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ncgi'
        priority:
          $ref: '#/components/schemas/LcsPriority'
        velocityRequested:
          $ref: '#/components/schemas/VelocityRequested'
        ueLcsCap:
          $ref: '#/components/schemas/UeLcsCapability'
    LocationData:
      type: object
      required:
        - locationEstimate
      properties:
        locationEstimate:
          $ref: '#/components/schemas/GeographicArea'
        accuracyFulfilmentIndicator:
          $ref: '#/components/schemas/AccuracyFulfilmentIndicator'
        ageOfLocationEstimate:
          $ref: '#/components/schemas/AgeOfLocationEstimate'
        velocityEstimate:
          $ref: '#/components/schemas/VelocityEstimate'
        civicAddress:
          $ref: '#/components/schemas/CivicAddress'
        positioningDataList:
          type: array
          items:
            $ref: '#/components/schemas/PositioningMethodAndUsage'
          minItems: 1
        gnssPositioningDataList:
          type: array
          items:
            $ref: '#/components/schemas/GnssPositioningMethodAndUsage'
          minItems: 1
        ecgi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ecgi'
        ncgi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ncgi'
        altitude:
          $ref: '#/components/schemas/Altitude'
        barometricPressure:
          $ref: '#/components/schemas/BarometricPressure'
    GeographicArea:
      anyOf:
        - $ref: '#/components/schemas/Point'
        - $ref: '#/components/schemas/PointUncertaintyCircle'
        - $ref: '#/components/schemas/PointUncertaintyEllipse'
        - $ref: '#/components/schemas/Polygon'
        - $ref: '#/components/schemas/PointAltitude'
        - $ref: '#/components/schemas/PointAltitudeUncertainty'
        - $ref: '#/components/schemas/EllipsoidArc'
    GADShape:
      type: object
      required:
        - shape
      properties:
        shape:
          $ref: '#/components/schemas/SupportedGADShapes'
      discriminator:
        propertyName: shape
        mapping:
          POINT: '#/components/schemas/Point'
          POINT_UNCERTAINTY_CIRCLE: '#/components/schemas/PointUncertaintyCircle'          
          POINT_UNCERTAINTY_ELLIPSE: '#/components/schemas/PointUncertaintyEllipse'          
          POLYGON: '#/components/schemas/Polygon'          
          POINT_ALTITUDE: '#/components/schemas/PointAltitude'          
          POINT_ALTITUDE_UNCERTAINTY: '#/components/schemas/PointAltitudeUncertainty'          
          ELLIPSOID_ARC: '#/components/schemas/EllipsoidArc'
    Point:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
    PointUncertaintyCircle:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
            - uncertainty
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
            uncertainty:
              $ref: '#/components/schemas/Uncertainty'
    PointUncertaintyEllipse:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
            - uncertaintyEllipse
            - confidence
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
            uncertaintyEllipse:
              $ref: '#/components/schemas/UncertaintyEllipse'
            confidence:
              $ref: '#/components/schemas/Confidence'
    Polygon:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - pointList
          properties:
            pointList:
              $ref: '#/components/schemas/PointList'
    PointAltitude:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
            - altitude
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
            altitude:
              $ref: '#/components/schemas/Altitude'
    PointAltitudeUncertainty:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
            - altitude
            - uncertaintyEllipse
            - uncertaintyAltitude
            - confidence
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
            altitude:
              $ref: '#/components/schemas/Altitude'
            uncertaintyEllipse:
              $ref: '#/components/schemas/UncertaintyEllipse'
            uncertaintyAltitude:
              $ref: '#/components/schemas/Uncertainty'
            confidence:
              $ref: '#/components/schemas/Confidence'
    EllipsoidArc:
      allOf:
        - $ref: '#/components/schemas/GADShape'
        - type: object
          required:
            - point
            - innerRadius
            - uncertaintyRadius
            - offsetAngle
            - includedAngle
            - confidence
          properties:
            point:
              $ref: '#/components/schemas/GeographicalCoordinates'
            innerRadius:
              $ref: '#/components/schemas/InnerRadius'
            uncertaintyRadius:
              $ref: '#/components/schemas/Uncertainty'
            offsetAngle:
              $ref: '#/components/schemas/Angle'
            includedAngle:
              $ref: '#/components/schemas/Angle'
            confidence:
              $ref: '#/components/schemas/Confidence'     
    GeographicalCoordinates:
      type: object
      required:
        - lon
        - lat
      properties:
        lon:
          type: number
          format: float
          minimum: -180
          maximum: 180
        lat:
          type: number
          format: float
          minimum: -90
          maximum: 90
    UncertaintyEllipse:
      type: object
      required:
        - semiMajor
        - semiMinor
        - orientationMajor
      properties:
        semiMajor:
          $ref: '#/components/schemas/Uncertainty'
        semiMinor:
          $ref: '#/components/schemas/Uncertainty'
        orientationMajor:
          $ref: '#/components/schemas/Orientation'
    PointList:
      type: array
      items:
        $ref: '#/components/schemas/GeographicalCoordinates'
      minItems: 3
      maxItems: 15
    LocationQoS:
      type: object
      properties:
        hAccuracy:
          $ref: '#/components/schemas/Accuracy'
        vAccuracy:
          $ref: '#/components/schemas/Accuracy'
        verticalRequested:
          type: boolean
        responseTime:
          $ref: '#/components/schemas/ResponseTime'
    PositioningMethodAndUsage:
      type: object
      required:
        - method
        - mode
        - usage
      properties:
        method:
          $ref: '#/components/schemas/PositioningMethod'
        mode:
          $ref: '#/components/schemas/PositioningMode'
        usage:
          $ref: '#/components/schemas/Usage'
    GnssPositioningMethodAndUsage:
      type: object
      required:
        - mode
        - gnss
        - usage
      properties:
        mode:
          $ref: '#/components/schemas/PositioningMode'
        gnss:
          $ref: '#/components/schemas/GnssId'
        usage:
          $ref: '#/components/schemas/Usage'
    CivicAddress:
      type: object
      properties:
        country:
          type: string
        A1:
          type: string
        A2:
          type: string
        A3:
          type: string
        A4:
          type: string
        A5:
          type: string
        A6:
          type: string
        PRD:
          type: string
        POD:
          type: string
        STS:
          type: string
        HNO:
          type: string
        HNS:
          type: string
        LMK:
          type: string
        LOC:
          type: string
        NAM:
          type: string
        PC:
          type: string
        BLD:
          type: string
        UNIT:
          type: string
        ROOM:
          type: string
        PLC:
          type: string
        PCN:
          type: string
        POBOX:
          type: string
        ADDCODE:
          type: string
        SEAT:
          type: string
        RD:
          type: string
        RDSEC:
          type: string
        RDBR:
          type: string
        RDSUBBR:
          type: string
        PRM:
          type: string
        POM:
          type: string
    VelocityEstimate:
      oneOf:
        - $ref: '#/components/schemas/HorizontalVelocity'
        - $ref: '#/components/schemas/HorizontalWithVerticalVelocity'
        - $ref: '#/components/schemas/HorizontalVelocityWithUncertainty'
        - $ref: '#/components/schemas/HorizontalWithVerticalVelocityAndUncertainty'
    HorizontalVelocity:
      type: object
      required:
        - hSpeed
        - bearing
      properties:
        hSpeed:
          $ref: '#/components/schemas/HorizontalSpeed'
        bearing:
          $ref: '#/components/schemas/Angle'
    HorizontalWithVerticalVelocity:
      type: object
      required:
        - hSpeed
        - bearing
        - vSpeed
        - vDirection
      properties:
        hSpeed:
          $ref: '#/components/schemas/HorizontalSpeed'
        bearing:
          $ref: '#/components/schemas/Angle'
        vSpeed:
          $ref: '#/components/schemas/VerticalSpeed'
        vDirection:
          $ref: '#/components/schemas/VerticalDirection'
    HorizontalVelocityWithUncertainty:
      type: object
      required:
        - hSpeed
        - bearing
        - hUncertainty
      properties:
        hSpeed:
          $ref: '#/components/schemas/HorizontalSpeed'
        bearing:
          $ref: '#/components/schemas/Angle'
        hUncertainty:
          $ref: '#/components/schemas/SpeedUncertainty'
    HorizontalWithVerticalVelocityAndUncertainty:
      type: object
      required:
        - hSpeed
        - bearing
        - vSpeed
        - vDirection
        - hUncertainty
        - vUncertainty
      properties:
        hSpeed:
          $ref: '#/components/schemas/HorizontalSpeed'
        bearing:
          $ref: '#/components/schemas/Angle'
        vSpeed:
          $ref: '#/components/schemas/VerticalSpeed'
        vDirection:
          $ref: '#/components/schemas/VerticalDirection'
        hUncertainty:
          $ref: '#/components/schemas/SpeedUncertainty'
        vUncertainty:
          $ref: '#/components/schemas/SpeedUncertainty'
    UeLcsCapability:
      type: object
      properties:
        lppSupport:
          type: boolean
          default: true
#
# SIMPLE TYPES
#
    Altitude:
      type: number
      format: float
      minimum: -32767
      maximum: 32767
    Angle:
      type: integer
      minimum: 0
      maximum: 360
    Uncertainty:
      type: number
      format: float
      minimum: 0
    Orientation:
      type: integer
      minimum: 0
      maximum: 180
    Confidence:
      type: integer
      minimum: 0
      maximum: 100
    Accuracy:
      type: number
      format: float
      minimum: 0
    InnerRadius:
      type: integer
      format: int32
      minimum: 0
      maximum: 327675
    CorrelationID:
      type: string
      minLength: 1
      maxLength: 255
    AgeOfLocationEstimate:
      type: integer
      minimum: 0
      maximum: 32767
    HorizontalSpeed:
      type: number
      format: float
      minimum: 0
      maximum: 2047
    VerticalSpeed:
      type: number
      format: float
      minimum: 0
      maximum: 255
    SpeedUncertainty:
      type: number
      format: float
      minimum: 0
      maximum: 255
    BarometricPressure:
      type: integer
      minimum: 30000
      maximum: 115000
#
# ENUMS
#
    ExternalClientType:
      anyOf:
        - type: string
          enum:
            - EMERGENCY_SERVICES
            - VALUE_ADDED_SERVICES
            - PLMN_OPERATOR_SERVICES
            - LAWFUL_INTERCEPT_SERVICES
            - PLMN_OPERATOR_BROADCAST_SERVICES
            - PLMN_OPERATOR_OM
            - PLMN_OPERATOR_ANONYMOUS_STATISTICS
            - PLMN_OPERATOR_TARGET_MS_SERVICE_SUPPORT
        - type: string
    SupportedGADShapes:
      anyOf:
        - type: string
          enum:
            - POINT
            - POINT_UNCERTAINTY_CIRCLE
            - POINT_UNCERTAINTY_ELLIPSE
            - POLYGON
            - POINT_ALTITUDE
            - POINT_ALTITUDE_UNCERTAINTY
            - ELLIPSOID_ARC
        - type: string
    ResponseTime:
      anyOf:
        - type: string
          enum:
            - LOW_DELAY
            - DELAY_TOLERANT
        - type: string
    PositioningMethod:
      anyOf:
        - type: string
          enum:
            - CELLID
            - ECID
            - OTDOA         
            - BAROMETRIC_PRESSURE
            - WLAN
            - BLUETOOTH
            - MBS   
        - type: string
    PositioningMode:
      anyOf:
        - type: string
          enum:
            - UE_BASED
            - UE_ASSISTED
            - CONVENTIONAL
        - type: string
    GnssId:
      anyOf:
        - type: string
          enum:
            - GPS
            - GALILEO
            - SBAS
            - MODERNIZED_GPS
            - QZSS
            - GLONASS
        - type: string
    Usage:
      anyOf:
        - type: string
          enum:
            - UNSUCCESS
            - SUCCESS_RESULTS_NOT_USED
            - SUCCESS_RESULTS_USED_TO_VERIFY_LOCATION
            - SUCCESS_RESULTS_USED_TO_GENERATE_LOCATION
            - SUCCESS_METHOD_NOT_DETERMINED
        - type: string
    LcsPriority:
      anyOf:
        - type: string
          enum:
            - HIGHEST_PRIORITY
            - NORMAL_PRIORITY
        - type: string
    VelocityRequested:
      anyOf:
        - type: string
          enum:
            - VELOCITY_IS_NOT_REQUESTED
            - VELOCITY_IS_REQUESTED
        - type: string
    AccuracyFulfilmentIndicator:
      anyOf:
        - type: string
          enum:
            - REQUESTED_ACCURACY_FULFILLED
            - REQUESTED_ACCURACY_NOT_FULFILLED
        - type: string
    VerticalDirection:
      type: string
      enum:
        - UPWARD
        - DOWNWARD
externalDocs:
  description: 3GPP TS 29.572 V15.3.0; 5G System; Location Management Services; Stage 3
  url: 'http://www.3gpp.org/ftp/Specs/archive/29_series/29.572/'