A.9 ServiceParameter API
29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS
openapi: 3.0.0
info:
title: 3gpp-service-parameter
version: 1.2.0-alpha.1
description: |
API for AF service paramter
© 2022, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
All rights reserved.
externalDocs:
description: >
3GPP TS 29.522 V18.0.0; 5G System; Network Exposure Function Northbound APIs.
url: ‘https://www.3gpp.org/ftp/Specs/archive/29_series/29.522/’
security:
– {}
– oAuth2ClientCredentials: []
servers:
– url: ‘{apiRoot}/3gpp-service-parameter/v1’
variables:
apiRoot:
default: https://example.com
description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.
paths:
/{afId}/subscriptions:
parameters:
– name: afId
in: path
description: Identifier of the AF
required: true
schema:
type: string
get:
summary: read all of the active subscriptions for the AF
operationId: ReadAllSubscriptions
tags:
– Service Parameter Subscriptions
parameters:
– name: gpsis
in: query
description: The GPSI of the requested UE(s).
required: false
schema:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Gpsi’
minItems: 1
– name: ip-addrs
in: query
description: The IP address(es) of the requested UE(s).
required: false
schema:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/IpAddr’
minItems: 1
– name: ip-domain
in: query
description: >
The IPv4 address domain identifier. The attribute may only be provided
if IPv4 address is included in the ip-addrs query parameter.
required: false
schema:
type: string
– name: mac-addrs
in: query
description: The MAC address(es) of the requested UE(s).
required: false
schema:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/MacAddr48’
minItems: 1
responses:
‘200’:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/ServiceParameterData’
minItems: 0
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘406’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/406’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
post:
summary: Creates a new subscription resource
operationId: CreateAnSubscription
tags:
– Service Parameter Subscriptions
requestBody:
description: Request to create a new subscription resource
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
responses:
‘201’:
description: Created (Successful creation of subscription)
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
headers:
Location:
description: Contains the URI of the newly created resource.
required: true
schema:
type: string
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
callbacks:
notificationDestination:
‘{$request.body#/notificationDestination}’:
post:
requestBody:
description: >
Notifications upon AF Service Parameter Authorization Update,
and/or AF subscribed event notification of the outcome related
to the invocation of service parameters provisioning.
required: true
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/AfNotification’
minItems: 1
responses:
‘204’:
description: Expected response to a successful callback processing without a body
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
/{afId}/subscriptions/{subscriptionId}:
parameters:
– name: afId
in: path
description: Identifier of the AF
required: true
schema:
type: string
– name: subscriptionId
in: path
description: Identifier of the subscription resource
required: true
schema:
type: string
get:
summary: read an active subscriptions for the SCS/AS and the subscription Id
operationId: ReadAnSubscription
tags:
– Individual Service Parameter Subscription
responses:
‘200’:
description: OK (Successful get the active subscription)
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘406’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/406’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
put:
summary: Fully updates/replaces an existing subscription resource
operationId: FullyUpdateAnSubscription
tags:
– Individual Service Parameter Subscription
requestBody:
description: Parameters to update/replace the existing subscription
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
responses:
‘200’:
description: OK (Successful update of the subscription)
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
‘204’:
description: OK (Successful update of the subscription)
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
patch:
summary: Partial updates/replaces an existing subscription resource
operationId: PartialUpdateAnSubscription
tags:
– Individual Service Parameter Subscription
requestBody:
required: true
content:
application/merge-patch+json:
schema:
$ref: ‘#/components/schemas/ServiceParameterDataPatch’
responses:
‘200’:
description: OK. The subscription was modified successfully.
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceParameterData’
‘204’:
description: OK. The subscription was modified successfully.
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
delete:
summary: Deletes an already existing subscription
operationId: DeleteAnSubscription
tags:
– Individual Service Parameter Subscription
responses:
‘204’:
description: No Content (Successful deletion of the existing subscription)
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
components:
securitySchemes:
oAuth2ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: ‘{tokenUrl}’
scopes: {}
schemas:
ServiceParameterData:
description: Represents an individual Service Parameter subscription resource.
type: object
properties:
afServiceId:
type: string
description: Identifies a service on behalf of which the AF is issuing the request.
appId:
type: string
description: Identifies an application.
dnn:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Dnn’
snssai:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Snssai’
externalGroupId:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/ExternalGroupId’
anyUeInd:
type: boolean
description: >
Identifies whether the AF request applies to any UE. This attribute
shall set to "true" if applicable for any UE, otherwise, set to "false".
gpsi:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Gpsi’
ueIpv4:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Ipv4Addr’
ueIpv6:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Ipv6Addr’
ueMac:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/MacAddr48’
self:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/Link’
subNotifEvents:
type: array
items:
$ref: ‘#/components/schemas/Event’
minItems: 1
notificationDestination:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uri’
requestTestNotification:
type: boolean
description: >
Set to true by the AF to request the NEF to send a test notification
as defined in clause 5.2.5.3 of 3GPP TS 29.122. Set to false or omitted otherwise.
websockNotifConfig:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig’
paramOverPc5:
$ref: ‘#/components/schemas/ParameterOverPc5’
paramOverUu:
$ref: ‘#/components/schemas/ParameterOverUu’
paramForProSeDd:
$ref: ‘#/components/schemas/ParamForProSeDd’
paramForProSeDc:
$ref: ‘#/components/schemas/ParamForProSeDc’
paramForProSeU2NRelUe:
$ref: ‘#/components/schemas/ParamForProSeU2NRelUe’
paramForProSeRemUe:
$ref: ‘#/components/schemas/ParamForProSeRemUe’
urspGuidance:
type: array
items:
$ref: ‘#/components/schemas/UrspRuleRequest’
minItems: 1
description: Contains the service parameter used to guide the URSP.
mtcProviderId:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/MtcProviderInformation’
suppFeat:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/SupportedFeatures’
ServiceParameterDataPatch:
description: >
Represents the parameters to request the modification of a service parameter
subscription resource.
type: object
properties:
paramOverPc5:
$ref: ‘#/components/schemas/ParameterOverPc5Rm’
paramOverUu:
$ref: ‘#/components/schemas/ParameterOverUuRm’
paramForProSeDd:
$ref: ‘#/components/schemas/ParamForProSeDdRm’
paramForProSeDc:
$ref: ‘#/components/schemas/ParamForProSeDcRm’
paramForProSeU2NRelUe:
$ref: ‘#/components/schemas/ParamForProSeU2NRelUeRm’
paramForProSeRemUe:
$ref: ‘#/components/schemas/ParamForProSeRemUeRm’
urspGuidance:
type: array
items:
$ref: ‘#/components/schemas/UrspRuleRequest’
minItems: 1
description: Contains the service parameter used to guide the URSP.
subNotifEvents:
type: array
items:
$ref: ‘#/components/schemas/Event’
minItems: 1
nullable: true
notificationDestination:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uri’
ParameterOverPc5:
description: >
Represents configuration parameters for V2X communications over PC5 reference point.
type: string
ParameterOverPc5Rm:
description: >
Represents the same as the ParameterOverPc5 data type but with the nullable:true property.
type: string
nullable: true
ParameterOverUu:
description: >
Represents configuration parameters for V2X communications over Uu reference point.
type: string
ParameterOverUuRm:
description: >
Represents the same as the ParameterOverUu data type but with the nullable:true property.
type: string
nullable: true
ParamForProSeDd:
description: Represents the service parameters for 5G ProSe direct discovery.
type: string
ParamForProSeDdRm:
description: >
This data type is defined in the same way as the ParamForProSeDd data type,
but with the OpenAPI nullable property set to true.
type: string
nullable: true
ParamForProSeDc:
description: Represents the service parameters for 5G ProSe direct communications.
type: string
ParamForProSeDcRm:
description: >
This data type is defined in the same way as the ParamForProSeDc data type,
but with the OpenAPI nullable property set to true.
type: string
nullable: true
ParamForProSeU2NRelUe:
description: Represents the service parameters for 5G ProSe UE-to-network relay UE.
type: string
ParamForProSeU2NRelUeRm:
description: >
This data type is defined in the same way as the ParamForProSeU2NRelay data type,
but with the OpenAPI nullable property set to true.
type: string
nullable: true
ParamForProSeRemUe:
description: Represents the service parameters for 5G ProSe Remate UE.
type: string
ParamForProSeRemUeRm:
description: >
This data type is defined in the same way as the ParamForProSeRemUe data type,
but with the OpenAPI nullable property set to true.
type: string
nullable: true
UrspRuleRequest:
description: Contains parameters that can be used to guide the URSP.
type: object
properties:
trafficDesc:
$ref: ‘#/components/schemas/TrafficDescriptorComponents’
relatPrecedence:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uinteger’
routeSelParamSets:
type: array
items:
$ref: ‘#/components/schemas/RouteSelectionParameterSet’
minItems: 1
description: >
Sets of parameters that may be used to guide the Route Selection Descriptors of the
URSP.
RouteSelectionParameterSet:
description: >
Contains parameters that can be used to guide the Route Selection
Descriptors of the URSP.
type: object
properties:
dnn:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Dnn’
snssai:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Snssai’
precedence:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uinteger’
spatialValidityAreas:
type: array
items:
$ref: ‘TS29522_AMPolicyAuthorization.yaml#/components/schemas/GeographicalArea’
minItems: 1
description: >
Indicates where the route selection parameters apply. It may correspond
to a geographical area, for example using a geographic shape that
is known to the AF and is configured by the operator to correspond to a list
of or TAIs.
spatialValidityTais:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Tai’
minItems: 1
description: >
Indicates the TAIs in which the route selection parameters apply. This attribute is
applicable only within the 5GC and it shall not be included in the request messages of
untrusted AFs for URSP guidance.
Event:
anyOf:
– type: string
enum:
– SUCCESS_UE_POL_DEL_SP
– UNSUCCESS_UE_POL_DEL_SP
– type: string
description: >
This string provides forward-compatibility with future extensions to the enumeration
and is not used to encode content defined in the present version of this API.
description: |
Possible values are:
– SUCCESS_UE_POL_DEL_SP: Successful UE Policy Delivery related to
the invocation of AF provisioned Service Parameters.
– UNSUCCESS_UE_POL_DEL_SP: Unsuccessful UE Policy Delivery related to the invocation of AF
provisioned Service Parameters.
AfNotification:
description: >
Notifications upon AF Service Parameter Authorization Update e.g. to
revoke the authorization, and/or AF subscribed event notification of the
outcome related to the invocation of service parameter provisioning.
type: object
properties:
subscription:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/Link’
reportEvent:
$ref: ‘#/components/schemas/Event’
authResult:
$ref: ‘#/components/schemas/AuthorizationResult’
gpsis:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Gpsi’
minItems: 1
dnn:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Dnn’
snssai:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Snssai’
eventInfo:
$ref: ‘#/components/schemas/EventInfo’
required:
– subscription
anyOf:
– required: [reportEvent]
– required: [authResult]
TrafficDescriptorComponents:
description: Traffic descriptor components for the requested URSP.
type: object
properties:
appDescs:
type: object
additionalProperties:
$ref: ‘TS29522_5GLANParameterProvision.yaml#/components/schemas/AppDescriptor’
minProperties: 1
description: Describes the operation systems and the corresponding applications for each
operation systems. The key of map is osId.
flowDescs:
type: array
items:
type: string
minItems: 1
description: Represents a 3-tuple with protocol, server ip and server port for UL/DL
application traffic. The content of the string has the same encoding as the IPFilterRule
AVP value as defined in IETF RFC 6733.
domainDescs:
type: array
items:
type: string
minItems: 1
description: FQDN(s) or a regular expression which are used as a domain name matching
criteria.
ethFlowDescs:
type: array
items:
$ref: ‘TS29514_Npcf_PolicyAuthorization.yaml#/components/schemas/EthFlowDescription’
minItems: 1
description: Descriptor(s) for destination information of non-IP traffic in which only
ethernet flow description is defined.
dnns:
type: array
items:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Dnn’
minItems: 1
description: This is matched against the DNN information provided by the application.
connCaps:
type: array
items:
$ref: ‘#/components/schemas/ConnectionCapabilities’
minItems: 1
description: This is matched against the information provided by a UE application when it
requests a network connection with certain capabilities.
anyOf:
– required: [appDescs]
– required: [flowDescs]
– required: [domainDescs]
– required: [ethFlowDescs]
– required: [dnns]
– required: [connCaps]
AuthorizationResult:
anyOf:
– type: string
enum:
– AUTH_REVOKED
– type: string
description: >
This string provides forward-compatibility with future extensions to the enumeration
and is not used to encode content defined in the present version of this API.
description: |
Possible values are:
– AUTH_REVOKED: Indicated the service parameters authorization is revoked.
EventInfo:
description: Indicates the event information.
type: object
properties:
failureCause:
$ref: ‘#/components/schemas/Failure’
Failure:
oneOf:
– type: string
enum:
– UNSPECIFIED
– UE_NOT_REACHABLE
– UNKNOWN
– UE_TEMP_UNREACHABLE
– type: string
description: >
This string provides forward-compatibility with future extensions to the enumeration
and is not used to encode content defined in the present version of this API.
description: |
Possible values are:
– UNSPECIFIED: Indicates the PCF received the UE sent UE policy delivery service cause #111
(Protocol error, unspecified).
– UE_NOT_REACHABLE: Indicates the PCF received the notification from the AMF that the UE is
not reachable.
– UNKNOWN: Indicates unknown reasons upon no response from the UE, e.g. UPDS message type is
not defined or not implemented by the UE, or not compatible with the UPDS state, in which
the UE shall ignore the UPDS message.
– UE_TEMP_UNREACHABLE: Indicates the PCF received the notification from the AMF that the UE
is not reachable but the PCF will retry again.
ConnectionCapabilities:
anyOf:
– type: string
enum:
– IMS
– MMS
– SUPL
– INTERNET
– type: string
description: >
This string provides forward-compatibility with future
extensions to the enumeration and is not used to encode
content defined in the present version of this API.
description: |
Possible values are
– IMS: Indicates the connection capability to support IMS service.
– MMS: Indicates the connection capability to support MMS service.
– SUPL: Indicates the connection capability to support SUPL service.
– INTERNET: Indicates the connection capability to support Internet service.