near-rt-ric-simulator/ric-plt/a1/a1-openapi.yaml

   1 openapi: 3.0.0
   2 info:
   3   title: 'A1-P Policy Management Service'
   4   version: 1.1.x
   5   description: |
   6     API for Policy Management Service.
   7     © 2019, O-RAN Alliance.
   8     All rights reserved.
   9 externalDocs:
  10   description: 'ORAN-WG2.A1.AP-v01.01 A1 interface: Application protocol'
  11   url: 'https://www.o-ran.org/specifications'
  12 servers:
  13   - url: '{apiRoot}/A1-P/v1'
  14     variables:
  15       apiRoot:
  16         default: 'https://example.com'
  17         description: 'apiRoot as defined in clause 4.2.1 in ORAN-WG2.A1.AP'
  18 paths:
  19   '/policies':
  20     get:
  21       operationId: a1.get_all_policies
  22       description: 'Get all policies including their enforcement status'
  23       tags:
  24       - All Policy Objects
  25       responses:
  26         200:
  27           description: 'Array of all policies and their enforcement status'
  28           content:
  29             application/json:
  30               schema:
  31                 type: array
  32                 items:
  33                   "$ref": "#/components/schemas/PolicyObject"
  34                 minItems: 0
  35
  36   '/policies/identities':
  37     get:
  38       operationId: a1.get_all_policy_identities
  39       description: 'Get all policy identities'
  40       tags:
  41       - All Policy Identities
  42       responses:
  43         200:
  44           description: 'Array of all policy identities'
  45           content:
  46             application/json:
  47               schema:
  48                 type: array
  49                 items:
  50                   "$ref": "#/components/schemas/PolicyId"
  51                 minItems: 0
  52
  53   '/policies/status':
  54     get:
  55       operationId: a1.get_all_policy_status
  56       description: 'Get enforcement status for all policy instances'
  57       tags:
  58       - All Policy Status Objects
  59       responses:
  60         200:
  61           description: 'Array of all policy identities and their related enforcement status'
  62           content:
  63             application/json:
  64               schema:
  65                 type: array
  66                 items:
  67                   "$ref": "#/components/schemas/PolicyStatusObject"
  68                 minItems: 0
  69
  70   '/policies/{policyId}':
  71     parameters:
  72       - name: policyId
  73         in: path
  74         required: true
  75         schema:
  76           "$ref": "#/components/schemas/PolicyId"
  77     put:
  78       operationId: a1.put_policy
  79       description: 'Create, or update, a policy'
  80       tags:
  81       - Individual Policy Object
  82       requestBody:
  83         content:
  84           application/json:
  85             schema:
  86               "$ref": "#/components/schemas/PolicyObject"
  87       responses:
  88         200:
  89           description: 'The policy was updated'
  90           content:
  91             application/json:
  92               schema:
  93                 "$ref": "#/components/schemas/PolicyObject"
  94         201:
  95           description: 'The policy was created'
  96           content:
  97             application/json:
  98               schema:
  99                 "$ref": "#/components/schemas/PolicyObject"
 100           headers:
 101             Location:
 102               description: 'Contains the URI of the created policy'
 103               required: true
 104               schema:
 105                 type: string
 106         400:
 107           "$ref": "#/components/responses/400-BadRequest"
 108       callbacks:
 109         policyNotification:
 110           '$request.body#/notificationDestination':
 111             post:
 112               description: 'Notify about enforcement status changes for this policy'
 113               requestBody:
 114                 required: true
 115                 content:
 116                   application/json:
 117                     schema:
 118                       "$ref": "#/components/schemas/PolicyStatusObject"
 119               responses:
 120                 204:
 121                   description: 'Notification received'
 122     get:
 123       operationId: a1.get_policy
 124       description: 'Query single policy'
 125       tags:
 126       - Individual Policy Object
 127       responses:
 128         200:
 129           description: 'The requested policy'
 130           content:
 131             application/json:
 132               schema:
 133                 "$ref": "#/components/schemas/PolicyObject"
 134         404:
 135           "$ref": "#/components/responses/404-NotFound"
 136     delete:
 137       operationId: a1.delete_policy
 138       description: 'Delete policy'
 139       tags:
 140       - Individual Policy Object
 141       responses:
 142         204:
 143           description: 'The policy was deleted'
 144         404:
 145           "$ref": "#/components/responses/404-NotFound"
 146
 147   '/policies/{policyId}/status':
 148     parameters:
 149       - name: policyId
 150         in: path
 151         required: true
 152         schema:
 153           "$ref": "#/components/schemas/PolicyId"
 154     get:
 155       operationId: a1.get_policy_status
 156       description: 'Get the enforcement status of a policy'
 157       tags:
 158       - Individual Policy Status Object
 159       responses:
 160         200:
 161           description: 'The requested enforcement status'
 162           content:
 163             application/json:
 164               schema:
 165                 "$ref": "#/components/schemas/PolicyStatusObject"
 166         404:
 167           "$ref": "#/components/responses/404-NotFound"
 168
 169   '/policytypes':
 170     get:
 171       operationId: a1.get_all_policytypes
 172       description: 'Get all policy type schemas'
 173       tags:
 174       - All Policy Types
 175       responses:
 176         200:
 177           description: 'Array of all policy type schemas'
 178           content:
 179             application/json:
 180               schema:
 181                 type: array
 182                 items:
 183                   "$ref": "#/components/schemas/PolicyTypeSchema"
 184                 minItems: 0
 185
 186   '/policytypes/identities':
 187     get:
 188       operationId: a1.get_all_policytypes_identities
 189       description: 'Get all policy type identities'
 190       tags:
 191       - All Policy Type Identities
 192       responses:
 193         200:
 194           description: 'Array of all policy type identities'
 195           content:
 196             application/json:
 197               schema:
 198                 type: array
 199                 items:
 200                   "$ref": "#/components/schemas/PolicyTypeId"
 201                 minItems: 0
 202
 203   '/policytypes/{policyTypeId}':
 204     parameters:
 205       - name: policyTypeId
 206         in: path
 207         required: true
 208         schema:
 209           "$ref": "#/components/schemas/PolicyTypeId"
 210     get:
 211       operationId: a1.get_policytypes
 212       description: 'Get the schema for a policy type'
 213       tags:
 214       - Individual Policy Type
 215       responses:
 216         200:
 217           description: 'The policy type schema'
 218           content:
 219             application/json:
 220               schema:
 221                 "$ref": "#/components/schemas/PolicyTypeSchema"
 222         404:
 223           "$ref": "#/components/responses/404-NotFound"
 224
 225   '/policytypes/subscription':
 226     put:
 227       operationId: a1.put_policytypes_subscription
 228       description: 'Subscribe to notification when any change is made to supported policy types'
 229       tags:
 230       - Policy Types Subscription Object
 231       requestBody:
 232         content:
 233           application/json:
 234             schema:
 235               "$ref": "#/components/schemas/SubscriptionObject"
 236       responses:
 237         200:
 238           description: 'The subscription was updated'
 239         201:
 240           description: 'The subscription was created'
 241       callbacks:
 242         policyTypesNotification:
 243           '$request.body#/notificationDestination':
 244             post:
 245               description: 'Notify about any change in supported policy types'
 246               responses:
 247                 204:
 248                   description: 'Notification received'
 249     get:
 250       operationId: a1.get_policytypes_subscription
 251       description: 'Get current notification destination'
 252       tags:
 253       - Policy Types Subscription Object
 254       responses:
 255         200:
 256           description: 'The current notification destination'
 257           content:
 258             application/json:
 259               schema:
 260                 "$ref": "#/components/schemas/SubscriptionObject"
 261         404:
 262           "$ref": "#/components/responses/404-NotFound"
 263
 264 components:
 265   schemas:
 266     #
 267     # Representation objects
 268     #
 269     PolicyStatusObject:
 270       type: object
 271       properties:
 272         policyId:
 273           "$ref": "#/components/schemas/PolicyId"
 274         enforceStatus:
 275           "$ref": "#/components/schemas/EnforcementStatusType"
 276         enforceReason:
 277           "$ref": "#/components/schemas/EnforcementReasonType"
 278       required:
 279       - policyId
 280       - enforceStatus
 281
 282     PolicyObject:
 283       description: 'A policy object, including its identification, type information, its notification destination, and optionally its enforcement status.'
 284       type: object
 285       properties:
 286         policyId:
 287           "$ref": "#/components/schemas/PolicyId"
 288         policyTypeId:
 289           "$ref": "#/components/schemas/PolicyTypeId"
 290         policyClause:
 291           "$ref": "#/components/schemas/PolicyClause"
 292         notificationDestination:
 293           "$ref": "#/components/schemas/NotificationDestination"
 294         enforceStatus:
 295           "$ref": "#/components/schemas/EnforcementStatusType"
 296       required:
 297       - policyId
 298       - policyTypeId
 299       - policyClause
 300       - notificationDestination
 301
 302     PolicyTypeSchema:
 303       description: 'The JSON Schema for a policy type. All policies of a policy type shall validate against this schema.'
 304       type: object
 305       properties:
 306         description:
 307           type: string
 308         properties:
 309           type: object
 310         title:
 311           type: string
 312         type:
 313           type: string
 314       required:
 315       - description
 316       - properties
 317       - title
 318       - type
 319
 320     ProblemDetails:
 321       description: 'A problem detail to carry details in a HTTP response according to RFC 7807 extended with A1 specific attributes'
 322       type: object
 323       properties:
 324         type:
 325           type: string
 326         title:
 327           type: string
 328         status:
 329           type: number
 330         detail:
 331           type: string
 332         instance:
 333           type: string
 334         policyErrorCode:
 335           "$ref": "#/components/schemas/PolicyErrorType"
 336         invalidParams:
 337           type: array
 338           items:
 339             "$ref": "#/components/schemas/InvalidParam"
 340           minItems: 1
 341
 342     SubscriptionObject:
 343       description: 'A subscription object used for specifying the destination where to send notifications.'
 344       type: object
 345       properties:
 346         notificationDestination:
 347           "$ref": "#/components/schemas/NotificationDestination"
 348       required:
 349       - notificationDestination
 350
 351     #
 352     # Structured data types
 353     #
 354     InvalidParam:
 355       description: 'Used in a ProblemDetails to indicate a specific invalid parameter'
 356       type: object
 357       properties:
 358         param:
 359           type: string
 360         reason:
 361           type: string
 362       required:
 363         - param
 364
 365     PolicyClause:
 366       description: 'The schema for a generic policy clause that shall be valid for all different specific policy types.'
 367       type: object
 368       properties:
 369         scope:
 370           "$ref": "#/components/schemas/ScopeIdentifier"
 371         statement:
 372           description: 'The statement for a specific policy type. The schema is specified by a specific policy type.'
 373           type: object
 374       required:
 375       - scope
 376       - statement
 377
 378     ScopeIdentifier:
 379       description: 'The schema for a generic scope identifier that shall be valid for all different specific policy types.'
 380       type: object
 381       properties:
 382         ueId:
 383           description: 'UE identifier based on RAN UE Id'
 384           type: string
 385         groupId:
 386           description: 'Identifier of a pre-defined group of UEs, SPID'
 387           type: string
 388         sliceId:
 389           description: 'Network slice identifie, NSSAI'
 390           type: string
 391         qosId:
 392           description: 'QoS identifer, 5QI'
 393           type: string
 394         cellId:
 395           description: 'Network resource identifier for a cell'
 396           type: string
 397
 398     #
 399     # Simple data types
 400     #
 401     PolicyId:
 402       description: 'Policy identifier assigned by the A1-P Consumer when a policy is created'
 403       type: string
 404
 405     PolicyTypeId:
 406       description: 'Policy type identifier assigned by the A1-P Provider'
 407       pattern: "^(STD|EXT)_[a-zA-Z]+_(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
 408       type: string
 409
 410     NotificationDestination:
 411       description: 'A complete URI defined according to IETF RFC 3986 where to send notifications'
 412       type: string
 413       nullable: true
 414
 415     #
 416     # Enumerations
 417     #
 418     EnforcementStatusType:
 419       description: 'Indicating if a policy is being enforced or not'
 420       type: string
 421       enum:
 422        - "ENFORCED"
 423        - "NOT_ENFORCED"
 424        - "UNDEFINED"
 425
 426     EnforcementReasonType:
 427       description: 'Indicating the reason why a policy is not being enforced'
 428       anyOf:
 429       - type: string
 430         enum:
 431         - "100"
 432         - "200"
 433         - "300"
 434         - "800"
 435       - type: string
 436
 437     PolicyErrorType:
 438       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.'
 439       anyOf:
 440       - type: string
 441         enum:
 442         - "CONF_POLICY_ID"
 443         - "BAD_REQ_MISSING_PARAM"
 444       - type: string
 445
 446   responses:
 447     400-BadRequest:
 448       description: 'Object in payload not properly formulated or not related to the method'
 449       content:
 450         application/problem+json:
 451           schema:
 452             "$ref": "#/components/schemas/ProblemDetails"
 453
 454     404-NotFound:
 455       description: 'No resource found at the URI'
 456       content:
 457         application/problem+json:
 458           schema:
 459             "$ref": "#/components/schemas/ProblemDetails"
 460
 461     405-MethodNotAllowed:
 462       description: 'Method not allowed for the URI'
 463       content:
 464         application/problem+json:
 465           schema:
 466             "$ref": "#/components/schemas/ProblemDetails"