A.2 Npcf_BDTPolicyControl API

29.5543GPP5G SystemBackground Data Transfer Policy Control ServiceRelease 18Stage 3TS

openapi: 3.0.0

info:

title: Npcf_BDTPolicyControl Service API

version: 1.3.0-alpha.1

description: |

PCF BDT Policy Control Service.

© 2022, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).

All rights reserved.

externalDocs:

description: >

3GPP TS 29.554 V18.0.0; 5G System; Background Data Transfer Policy Control Service.

url: ‘https://www.3gpp.org/ftp/Specs/archive/29_series/29.554/’

servers:

– url: ‘{apiRoot}/npcf-bdtpolicycontrol/v1’

variables:

apiRoot:

default: https://example.com

description: apiRoot as defined in clause 4.4 of 3GPP TS 29.501.

security:

– {}

– oAuth2ClientCredentials:

– npcf-bdtpolicycontrol

paths:

/bdtpolicies:

post:

summary: Create a new Individual BDT policy

operationId: CreateBDTPolicy

tags:

– BDT policies (Collection)

requestBody:

description: >

Contains information for the creation of a new Individual BDT policy resource.

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/BdtReqData’

responses:

‘201’:

description: Background data transfer policies offered to an ASP.

content:

application/json:

schema:

$ref: ‘#/components/schemas/BdtPolicy’

headers:

Location:

description: >

Contains the URI of the created individual BDT policy resource,

according to the structure

{apiRoot}/npcf-bdtpolicycontrol/v1/bdtpolicies/{bdtPolicyId}

required: true

schema:

type: string

‘303’:

description: >

See Other. The result of the POST request would be equivalent to the

existing Individual BDT policy resource.

headers:

Location:

description: Contains the URI of the existing individual BDT policy resource.

required: true

schema:

type: string

‘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’

‘502’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/502’

‘503’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/503’

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

callbacks:

BdtNotification:

‘{$request.body#/notifUri}’:

post:

requestBody:

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/Notification’

responses:

‘204’:

description: No Content, a reception of the BDT notification was successful.

‘307’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/307’

‘308’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/308’

‘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’

‘502’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/502’

‘503’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/503’

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

/bdtpolicies/{bdtPolicyId}:

get:

summary: Read an Individual BDT policy

operationId: GetBDTPolicy

tags:

– Individual BDT policy (Document)

parameters:

– name: bdtPolicyId

description: String identifying the individual BDT policy resource in the PCF.

in: path

required: true

schema:

type: string

responses:

‘200’:

description: Background data transfer policies offered to and selected by an ASP.

content:

application/json:

schema:

$ref: ‘#/components/schemas/BdtPolicy’

‘307’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/307’

‘308’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/308’

‘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’

‘406’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/406’

‘429’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/429’

‘500’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/500’

‘502’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/502’

‘503’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/503’

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

patch:

summary: Update an Individual BDT policy

operationId: UpdateBDTPolicy

tags:

– Individual BDT policy (Document)

parameters:

– name: bdtPolicyId

description: String identifying the individual BDT policy resource in the PCF.

in: path

required: true

schema:

type: string

requestBody:

description: >

Contains modification instruction to be performed on the BdtPolicy data

structure to select a transfer policy and in addition, may indicate whether

the BDT warning notification is enabled or disabled.

required: true

content:

application/merge-patch+json:

schema:

$ref: ‘#/components/schemas/PatchBdtPolicy’

responses:

‘200’:

description: >

The Individual BDT Policy resource is modified and a representation of that

resource is returned.

content:

application/json:

schema:

$ref: ‘#/components/schemas/BdtPolicy’

‘204’:

description: The Individual BDT Policy resource is modified.

‘307’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/307’

‘308’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/308’

‘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’

‘502’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/502’

‘503’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/503’

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

components:

securitySchemes:

oAuth2ClientCredentials:

type: oauth2

flows:

clientCredentials:

tokenUrl: ‘{nrfApiRoot}/oauth2/token’

scopes:

npcf-bdtpolicycontrol: Access to the Npcf_BDTPolicyControl API

schemas:

# Structured data types

BdtPolicy:

description: Represents an Individual BDT policy resource.

type: object

properties:

bdtPolData:

$ref: ‘#/components/schemas/BdtPolicyData’

bdtReqData:

$ref: ‘#/components/schemas/BdtReqData’

BdtReqData:

description: >

Contains service requirements for creation a new Individual BDT policy resource.

type: object

required:

– aspId

– desTimeInt

– numOfUes

– volPerUe

properties:

aspId:

$ref: ‘#/components/schemas/AspId’

desTimeInt:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/TimeWindow’

dnn:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Dnn’

interGroupId:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/GroupId’

notifUri:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uri’

nwAreaInfo:

$ref: ‘#/components/schemas/NetworkAreaInfo’

numOfUes:

description: Indicates a number of UEs.

type: integer

volPerUe:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/UsageThreshold’

snssai:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Snssai’

suppFeat:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/SupportedFeatures’

trafficDes:

$ref: ‘TS29122_ResourceManagementOfBdt.yaml#/components/schemas/TrafficDescriptor’

warnNotifReq:

description: Indicates whether the BDT warning notification is enabled or disabled.

type: boolean

default: false

BdtPolicyData:

description: Describes the authorization data of an Individual BDT policy resource.

type: object

required:

– bdtRefId

– transfPolicies

properties:

bdtRefId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/BdtReferenceId’

transfPolicies:

description: Contains transfer policies.

type: array

items:

$ref: ‘#/components/schemas/TransferPolicy’

minItems: 1

selTransPolicyId:

description: Contains an identity of the selected transfer policy.

type: integer

suppFeat:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/SupportedFeatures’

PatchBdtPolicy:

description: >

Describes the updates in authorization data of an Individual BDT Policy created

by the PCF.

type: object

properties:

bdtPolData:

$ref: ‘#/components/schemas/BdtPolicyDataPatch’

bdtReqData:

$ref: ‘#/components/schemas/BdtReqDataPatch’

BdtPolicyDataPatch:

description: >

A JSON Merge Patch body schema containing modification instruction to be performed

on the bdtPolData attribute of the BdtPolicy data structure to select a transfer

policy. Adds selTransPolicyId to BdtPolicyData data structure.

type: object

required:

– selTransPolicyId

properties:

selTransPolicyId:

description: >

Contains an identity (i.e. transPolicyId value) of the selected transfer

policy. If the BdtNotification_5G feature is supported value 0 indicates that

no transfer policy is selected.

type: integer

BdtReqDataPatch:

description: >

A JSON Merge Patch body schema containing modification instruction to be performed

on the bdtReqData attribute of the BdtPolicy data structure to indicate whether

the BDT warning notification is enabled or disabled. Modifies warnNotifReq from

BdtReqData data structure.

type: object

properties:

warnNotifReq:

description: Indicates whether the BDT warning notification is enabled or disabled.

type: boolean

TransferPolicy:

description: Describes a transfer policy.

type: object

required:

– ratingGroup

– recTimeInt

– transPolicyId

properties:

maxBitRateDl:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/BitRate’

maxBitRateUl:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/BitRate’

ratingGroup:

description: Indicates a rating group for the recommended time window.

type: integer

recTimeInt:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/TimeWindow’

transPolicyId:

description: Contains an identity of a transfer policy.

type: integer

NetworkAreaInfo:

description: >

Describes a network area information in which the NF service consumer requests

the number of UEs.

type: object

properties:

ecgis:

description: Contains a list of E-UTRA cell identities.

type: array

items:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Ecgi’

minItems: 1

ncgis:

description: Contains a list of NR cell identities.

type: array

items:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Ncgi’

minItems: 1

gRanNodeIds:

description: Contains a list of NG RAN nodes.

type: array

items:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/GlobalRanNodeId’

minItems: 1

tais:

description: Contains a list of tracking area identities.

type: array

items:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Tai’

minItems: 1

Notification:

description: Describes a BDT notification.

type: object

required:

– bdtRefId

properties:

bdtRefId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/BdtReferenceId’

candPolicies:

description: >

Contains a list of the candidate transfer policies from which the AF may

select a new transfer policy due to a network performance is below the criteria

set by the operator.

type: array

items:

$ref: ‘#/components/schemas/TransferPolicy’

minItems: 1

nwAreaInfo:

$ref: ‘#/components/schemas/NetworkAreaInfo’

timeWindow:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/TimeWindow’

# Simple data types

AspId:

description: Contains an identity of an application service provider.

type: string

Annex B (informative):
Change history

Change history

Date

TSG #

TSG Doc.

CR

Rev

Cat

Subject/Comment

New version

2018-01

TS skeleton

0.0.0

2018-01

CT3#94

C3-180369

Inclusion of C3-180188 agreed in CT3#94.

0.1.0

2018-03

CT3#95

C3-181376

Inclusion of documents agreed in CT3#95:

C3-181055, C3-181091, C3-181268, C3-181269,

C3-181270.

0.2.0

2018-04

CT3#96

C3-182524

Inclusion of documents agreed in CT3#96:

C3-182048, C3-182428, C3-182427, C3-182051,

C3-182052, C3-182053, C3-182429, C3-182454,

C3-182430, C3-182232.

0.3.0

2018-06

CT3#97

C3-183915

Inclusion of documents agreed in CT3#97:

C3-183241, C3-183280, C3-183289, C3-183291,

C3-183292, C3-183297, C3-183298, C3-183562,

C3-183563, C3-183564, C3-183565, C3-183714,

C3-183869.

0.4.0

2018-06

CT#80

CP-181028

TS sent to plenary for approval

1.0.0

2018-06

CT#80

CP-181028

TS approved by plenary

15.0.0

2018-09

CT#81

CP-182015

0001

1

B

Format of bdtPolicyId

15.1.0

2018-09

CT#81

CP-182015

0002

4

B

Network area information

15.1.0

2018-09

CT#81

CP-182015

0003

1

F

Description of Structured data types

15.1.0

2018-09

CT#81

CP-182015

0004

1

F

Resource structure presentation

15.1.0

2018-09

CT#81

CP-182015

0005

1

F

Removal of externalDoc field

15.1.0

2018-09

CT#81

CP-182015

0006

F

Corrections related to Feature negotiation

15.1.0

2018-09

CT#81

CP-182015

0007

F

"404 Not found" response in OpenAPI

15.1.0

2018-12

CT#82

CP-183205

0008

1

F

Correction of apiName

15.2.0

2018-12

CT#82

CP-183205

0010

F

Supported content types

15.2.0

2018-12

CT#82

CP-183205

0011

F

Definition of BdtPolicyData structure

15.2.0

2018-12

CT#82

CP-183205

0012

F

Non-empty arrays in OpenAPI file

15.2.0

2018-12

CT#82

CP-183205

0013

1

F

Adding the externalDocs field in the OpenAPI

15.2.0

2018-12

CT#82

CP-183205

0014

F

Adding HTTP status code "200 OK"

15.2.0

2018-12

CT#82

CP-183205

0015

1

F

Error indicating "Unspecified resource URI structure"

15.2.0

2018-12

CT#82

CP-183205

0016

3

F

Npcf_BDTPolicyControl API Authorization based on OAuth2

15.2.0

2018-12

CT#82

CP-183205

0017

1

F

API version update

15.2.0

2018-12

CT#82

CP-183205

0018

F

Default value for apiRoot

15.2.0

2018-12

CT#82

CP-183205

0019

1

F

OpenAPI: HTTP status codes alignment

15.2.0

2018-12

CT#82

CP-183205

0020

1

F

NgRanNodeId definition in OpenAPI

15.2.0

2018-12

CT#82

CP-183205

0021

F

OpenAPI: usage of the "tags" keyword

15.2.0

2018-12

CT#82

CP-183205

0022

F

Location header field in OpenAPI

15.2.0

2018-12

CT#82

CP-183205

0023

1

F

Data structure used in PATCH request

15.2.0

2019-03

CT#83

CP-190112

0024

F

Alignment of the BDT procedures

15.3.0

2019-05

CT#84

CP-191084

0025

1

F

Storage and precedence of OpenAPI specification file

15.4.0

2019-06

CT#84

CP-191084

0028

1

F

Copyright Note in YAML file

15.4.0

2019-06

CT#84

CP-191084

0030

F

OpenAPI version number update

15.4.0

2019-06

CT#84

CP-191105

0026

2

B

Support of Npcf_BDTPolicyControl_Notify service operation

16.0.0

2019-06

CT#84

CP-191090

0027

1

B

Add External group Id

16.0.0

2019-06

CT#84

CP-191101

0031

2

F

OpenAPI version number update

16.0.0

2019-09

CT#85

CP-192157

0032

1

B

Modification of BDT warning notification request indication

16.1.0

2019-09

CT#85

CP-192173

0034

F

OpenAPI version update for TS 29.554 Rel-16

16.1.0

2019-12

CT#86

CP-193198

0035

1

F

Indication of "BdtNotification_5G" feature

16.2.0

2019-12

CT#86

CP-193212

0037

F

Update of API version and TS version in OpenAPI file

16.2.0

2020-03

CT#87e

CP-200208

0036

2

B

BDT renegotiation upon the network conditions change

16.3.0

2020-03

CT#87e

CP-200219

0038

2

B

map ASPid to DNN and SNSSAI for xBDT

16.3.0

2020-03

CT#87e

CP-200216

0039

F

Update of OpenAPI version and TS version in externalDocs field

16.3.0

2020-06

CT#88e

CP-201234

0040

1

F

Removal of not valid BDT policy from UDR

16.4.0

2020-06

CT#88e

CP-201244

0041

1

F

Storage of YAML files in ETSI Forge

16.4.0

2020-06

CT#88e

CP-201256

0043

1

F

URI of the Npcf_BDTPolicyControl service

16.4.0

2020-06

CT#88e

CP-201276

0045

1

F

Traffic descriptor for xBDT

16.4.0

2020-06

CT#88e

CP-201225

0047

A

OpenAPI: adding Location header field in 303 response

16.4.0

2020-06

CT#88e

CP-201244

0048

1

F

Optionality of ProblemDetails

16.4.0

2020-06

CT#88e

CP-201244

0049

1

F

Supported headers, Resource Data type and yaml mapping

16.4.0

2020-06

CT#88e

CP-201255

0051

F

Update of OpenAPI version and TS version in externalDocs field

16.4.0

2020-12

CT#90e

CP-203139

0053

1

F

TS 29.554 Essential Corrections and alignments

16.5.0

2020-12

CT#90e

CP-203129

0054

1

F

Correction to the BDT policy re-negotiation

16.5.0

2020-12

CT#90e

CP-203139

0055

1

F

Storage of YAML files in ETSI Forge

16.5.0

2020-12

CT#90e

CP-203110

0056

1

F

Correction to support redirection codes and the update of the Callback URI

16.5.0

2020-12

CT#90e

CP-203152

0057

F

Update of OpenAPI version and TS version in externalDocs field

16.5.0

2021-03

CT#91e

CP-210191

0058

F

Supported feature number of ES3XX

16.6.0

2021-03

CT#91e

CP-210206

0062

1

F

set bdtpStatus to VALID

16.6.0

2021-03

CT#91e

CP-210201

0064

1

A

Correction to PATCH method

16.6.0

2021-03

CT#91e

CP-210239

0066

F

Update of OpenAPI version and TS version in externalDocs field

16.6.0

2021-03

CT#91e

CP-210219

0059

F

Support of optional HTTP custom header fields

17.0.0

2021-03

CT#91e

CP-210220

0060

F

Terminology alignment: usage of "NF service consumer"

17.0.0

2021-03

CT#91e

CP-210220

0061

F

OpenAPI reference

17.0.0

2021-06

CT#92e

CP-211200

0068

1

A

Redirect responses with "application/json" media type

17.1.0

2021-06

CT#92e

CP-211265

0070

F

Update of OpenAPI version and TS version in externalDocs field

17.1.0

2021-12

CT#94e

CP-213239

0071

F

API URI of the Npcf_BDTPolicyControl API

17.2.0

2022-03

CT#95e

CP-220176

0072

2

A

Alignment of "Application Errors" clause with SBI TS template

17.3.0

2022-03

CT#95e

CP-220201

0073

1

F

Formatting of description fields

17.3.0

2022-03

CT#95e

CP-220194

0075

F

Update of info and externalDocs fields

17.3.0

2022-06

CT#96

CP-221154

0076

F

Readability of the OpenAPI file and alignment with the SBI template

17.4.0

2022-06

CT#96

CP-221152

0077

F

Update of info and externalDocs fields

17.4.0

2022-12

CT#98e

CP-223192

0078

1

F

Adding the mandatory error code 502 Bad Gateway for Npcf_BDTPolicyControl

18.0.0

2022-12

CT#98e

CP-223200

0079

1

F

Correction to DNN encoding

18.0.0

2022-12

CT#98e

CP-223190

0080

F

Update of info and externalDocs fields

18.0.0