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 |