openapi: 3.0.0
info:
  title: 'A1-P Policy Management Service'
  version: 1.1.x
  description: |
    API for Policy Management Service.
    © 2019, O-RAN Alliance.
    All rights reserved.
externalDocs:
  description: 'ORAN-WG2.A1.AP-v01.01 A1 interface: Application protocol'
  url: 'https://www.o-ran.org/specifications'
servers:
  - url: '{apiRoot}/A1-P/v1'
    variables:
      apiRoot:
        default: 'https://example.com'
        description: 'apiRoot as defined in clause 4.2.1 in ORAN-WG2.A1.AP'
paths:
  '/policies':
    get:
      operationId: a1.get_all_policies
      description: 'Get all policies including their enforcement status'
      tags:
      - All Policy Objects
      responses:
        200:
          description: 'Array of all policies and their enforcement status'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyObject"
                minItems: 0

  '/policies/identities':
    get:
      operationId: a1.get_all_policy_identities
      description: 'Get all policy identities'
      tags:
      - All Policy Identities
      responses:
        200:
          description: 'Array of all policy identities'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyId"
                minItems: 0

  '/policies/status':
    get:
      operationId: a1.get_all_policy_status
      description: 'Get enforcement status for all policy instances'
      tags:
      - All Policy Status Objects
      responses:
        200:
          description: 'Array of all policy identities and their related enforcement status'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyStatusObject"
                minItems: 0

  '/policies/{policyId}':
    parameters:
      - name: policyId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyId"
    put:
      operationId: a1.put_policy
      description: 'Create, or update, a policy'
      tags:
      - Individual Policy Object
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PolicyObject"
      responses:
        200:
          description: 'The policy was updated'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
        201:
          description: 'The policy was created'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
          headers:
            Location:
              description: 'Contains the URI of the created policy'
              required: true
              schema:
                type: string
        400:
          "$ref": "#/components/responses/400-BadRequest"
      callbacks:
        policyNotification:
          '$request.body#/notificationDestination':
            post:
              description: 'Notify about enforcement status changes for this policy'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      "$ref": "#/components/schemas/PolicyStatusObject"
              responses:
                204:
                  description: 'Notification received'
    get:
      operationId: a1.get_policy
      description: 'Query single policy'
      tags:
      - Individual Policy Object
      responses:
        200:
          description: 'The requested policy'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
        404:
          "$ref": "#/components/responses/404-NotFound"
    delete:
      operationId: a1.delete_policy
      description: 'Delete policy'
      tags:
      - Individual Policy Object
      responses:
        204:
          description: 'The policy was deleted'
        404:
          "$ref": "#/components/responses/404-NotFound"

  '/policies/{policyId}/status':
    parameters:
      - name: policyId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyId"
    get:
      operationId: a1.get_policy_status
      description: 'Get the enforcement status of a policy'
      tags:
      - Individual Policy Status Object
      responses:
        200:
          description: 'The requested enforcement status'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyStatusObject"
        404:
          "$ref": "#/components/responses/404-NotFound"

  '/policytypes':
    get:
      operationId: a1.get_all_policytypes
      description: 'Get all policy type schemas'
      tags:
      - All Policy Types
      responses:
        200:
          description: 'Array of all policy type schemas'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyTypeSchema"
                minItems: 0

  '/policytypes/identities':
    get:
      operationId: a1.get_all_policytypes_identities
      description: 'Get all policy type identities'
      tags:
      - All Policy Type Identities
      responses:
        200:
          description: 'Array of all policy type identities'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyTypeId"
                minItems: 0

  '/policytypes/{policyTypeId}':
    parameters:
      - name: policyTypeId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyTypeId"
    get:
      operationId: a1.get_policytypes
      description: 'Get the schema for a policy type'
      tags:
      - Individual Policy Type
      responses:
        200:
          description: 'The policy type schema'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyTypeSchema"
        404:
          "$ref": "#/components/responses/404-NotFound"

  '/policytypes/subscription':
    put:
      operationId: a1.put_policytypes_subscription
      description: 'Subscribe to notification when any change is made to supported policy types'
      tags:
      - Policy Types Subscription Object
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SubscriptionObject"
      responses:
        200:
          description: 'The subscription was updated'
        201:
          description: 'The subscription was created'
      callbacks:
        policyTypesNotification:
          '$request.body#/notificationDestination':
            post:
              description: 'Notify about any change in supported policy types'
              responses:
                204:
                  description: 'Notification received'
    get:
      operationId: a1.get_policytypes_subscription
      description: 'Get current notification destination'
      tags:
      - Policy Types Subscription Object
      responses:
        200:
          description: 'The current notification destination'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SubscriptionObject"
        404:
          "$ref": "#/components/responses/404-NotFound"

components:
  schemas:
    #
    # Representation objects
    #
    PolicyStatusObject:
      type: object
      properties:
        policyId:
          "$ref": "#/components/schemas/PolicyId"
        enforceStatus:
          "$ref": "#/components/schemas/EnforcementStatusType"
        enforceReason:
          "$ref": "#/components/schemas/EnforcementReasonType"
      required:
      - policyId
      - enforceStatus

    PolicyObject:
      description: 'A policy object, including its identification, type information, its notification destination, and optionally its enforcement status.'
      type: object
      properties:
        policyId:
          "$ref": "#/components/schemas/PolicyId"
        policyTypeId:
          "$ref": "#/components/schemas/PolicyTypeId"
        policyClause:
          "$ref": "#/components/schemas/PolicyClause"
        notificationDestination:
          "$ref": "#/components/schemas/NotificationDestination"
        enforceStatus:
          "$ref": "#/components/schemas/EnforcementStatusType"
      required:
      - policyId
      - policyTypeId
      - policyClause
      - notificationDestination

    PolicyTypeSchema:
      description: 'The JSON Schema for a policy type. All policies of a policy type shall validate against this schema.'
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
        title:
          type: string
        type:
          type: string
      required:
      - description
      - properties
      - title
      - type

    ProblemDetails:
      description: 'A problem detail to carry details in a HTTP response according to RFC 7807 extended with A1 specific attributes'
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: number
        detail:
          type: string
        instance:
          type: string
        policyErrorCode:
          "$ref": "#/components/schemas/PolicyErrorType"
        invalidParams:
          type: array
          items:
            "$ref": "#/components/schemas/InvalidParam"
          minItems: 1

    SubscriptionObject:
      description: 'A subscription object used for specifying the destination where to send notifications.'
      type: object
      properties:
        notificationDestination:
          "$ref": "#/components/schemas/NotificationDestination"
      required:
      - notificationDestination

    #
    # Structured data types
    #
    InvalidParam:
      description: 'Used in a ProblemDetails to indicate a specific invalid parameter'
      type: object
      properties:
        param:
          type: string
        reason:
          type: string
      required:
        - param

    PolicyClause:
      description: 'The schema for a generic policy clause that shall be valid for all different specific policy types.'
      type: object
      properties:
        scope:
          "$ref": "#/components/schemas/ScopeIdentifier"
        statement:
          description: 'The statement for a specific policy type. The schema is specified by a specific policy type.'
          type: object
      required:
      - scope
      - statement

    ScopeIdentifier:
      description: 'The schema for a generic scope identifier that shall be valid for all different specific policy types.'
      type: object
      properties:
        ueId:
          description: 'UE identifier based on RAN UE Id'
          type: string
        groupId:
          description: 'Identifier of a pre-defined group of UEs, SPID'
          type: string
        sliceId:
          description: 'Network slice identifie, NSSAI'
          type: string
        qosId:
          description: 'QoS identifer, 5QI'
          type: string
        cellId:
          description: 'Network resource identifier for a cell'
          type: string

    #
    # Simple data types
    #
    PolicyId:
      description: 'Policy identifier assigned by the A1-P Consumer when a policy is created'
      type: string

    PolicyTypeId:
      description: 'Policy type identifier assigned by the A1-P Provider'
      pattern: "^(STD|EXT)_[a-zA-Z]+_(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
      type: string

    NotificationDestination:
      description: 'A complete URI defined according to IETF RFC 3986 where to send notifications'
      type: string
      nullable: true

    #
    # Enumerations
    #
    EnforcementStatusType:
      description: 'Indicating if a policy is being enforced or not'
      type: string
      enum:
       - "ENFORCED"
       - "NOT_ENFORCED"
       - "UNDEFINED"

    EnforcementReasonType:
      description: 'Indicating the reason why a policy is not being enforced'
      anyOf:
      - type: string
        enum:
        - "100"
        - "200"
        - "300"
        - "800"
      - type: string

    PolicyErrorType:
      description: 'Represents information that can be provided in addition to the HTTP response error code. Corresponds to the "cause" attribute defined in 3GPP specification 29.501.'
      anyOf:
      - type: string
        enum:
        - "CONF_POLICY_ID"
        - "BAD_REQ_MISSING_PARAM"
      - type: string

  responses:
    400-BadRequest:
      description: 'Object in payload not properly formulated or not related to the method'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    404-NotFound:
      description: 'No resource found at the URI'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    405-MethodNotAllowed:
      description: 'Method not allowed for the URI'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"