5.4 Nnwdaf_MLModelProvision Service API
29.5203GPP5G SystemNetwork Data Analytics ServicesRelease 17Stage 3TS
5.4.1 Introduction
The Nnwdaf_MLModelProvision Service shall use the Nnwdaf_MLModelProvision API.
The API URI of the Nnwdaf_MLModelProvision API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in each HTTP requests from the NF service consumer towards the NWDAF shall have the Resource URI structure defined in subclause 4.4.1 of 3GPP TS 29.501 [7], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [7].
– The<apiName> shall be "nnwdaf-mlmodelprovision".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in subclause 5.2.3.
5.4.2 Usage of HTTP
5.4.2.1 General
HTTP/2, IETF RFC 7540 [9], shall be used as specified in clause 5 of 3GPP TS 29.500 [6].
HTTP/2 shall be transported as specified in subclause 5.3 of 3GPP TS 29.500 [6].
The OpenAPI [11] specification of HTTP messages and content bodies for the Nnwdaf_MLModelProvision is contained in Annex A.
5.4.2.2 HTTP standard headers
5.4.2.2.1 General
See subclause 5.2.2 of 3GPP TS 29.500 [6] for the usage of HTTP standard headers.
5.4.2.2.2 Content type
JSON, IETF RFC 8259 [10], shall be used as content type of the HTTP bodies specified in the present specification as specified in subclause 5.4 of 3GPP TS 29.500 [6]. The use of the JSON format shall be signalled by the content type "application/json".
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [15].
5.4.2.3 HTTP custom headers
The Nnwdaf_MLModelProvision Service API shall support mandatory HTTP custom header fields specified in subclause 5.2.3.2 of 3GPP TS 29.500 [6] and may support HTTP custom header fields specified in subclause 5.2.3.3 of 3GPP TS 29.500 [6].
In this release of the specification, no specific custom headers are defined for the Nnwdaf_MLModelProvision Service API.
5.4.3 Resources
5.4.3.1 Resource Structure
Figure 5.4.3.1-1: Resource URI structure of the Nnwdaf_MLModelProvision API
Table 5.4.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 5.4.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
NWDAF ML Model Provision Subscriptions |
/subscriptions |
POST |
Creates a new Individual NWDAF ML Model Provision Subscription resource. |
|
Individual NWDAF ML Model Provision Subscription |
/subscriptions/{subscriptionId} |
DELETE |
Deletes an Individual NWDAF ML Model Provision Subscription identified by subresource {subscriptionId}. |
|
PUT |
Modifies an existing Individual NWDAF ML Model Provision Subscription identified by subresource {subscriptionId}. |
5.4.3.2 Resource: NWDAF ML Model Provision Subscriptions
5.4.3.2.1 Description
The NWDAF ML Model Provision Subscriptions resource represents all subscriptions to the Nnwdaf_MLModelProvision Service at a given NWDAF. The resource allows an NF service consumer to create a new Individual NWDAF ML Model Provision Subscription resource.
5.4.3.2.2 Resource definition
Resource URI: {apiRoot}/nnwdaf-mlmodelprovision/v1/subscriptions
This resource shall support the resource URI variables defined in table 5.4.3.2.2-1.
Table 5.4.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See subclause 5.4.1 |
5.4.3.2.3 Resource Standard Methods
5.4.3.2.3.1 POST
This method shall support the URI query parameters specified in table 5.4.3.2.3.1-1.
Table 5.4.3.2.3.1-1: URI query parameters supported by the POST method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 5.4.3.2.3.1-2 and the response data structures and response codes specified in table 5.4.3.2.3.1-3.
Table 5.4.3.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
NwdafMLModelProvSubsc |
M |
1 |
Create a new Individual NWDAF ML Model Provision Subscription resource. |
Table 5.4.3.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
NwdafMLModelProvSubsc |
M |
1 |
201 Created |
The creation of an Individual NWDAF ML Model Provision Subscription resource is confirmed and a representation of that resource is returned. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [6] also apply. |
||||
Table 5.4.3.2.3.1-4: Headers supported by the 201 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
Contains the URI of the newly created resource, according to the structure: {apiRoot}/nnwdaf-mlmodelprovision/v1/subscriptions/{subscriptionId} |
5.4.3.2.4 Resource Custom Operations
None in this release of the specification.
5.4.3.3 Resource: Individual NWDAF ML Model Provision Subscription
5.4.3.3.1 Description
The Individual NWDAF ML Model Provision Subscription resource represents a single subscription to the Nnwdaf_MLModelProvision Service at a given NWDAF.
5.4.3.3.2 Resource definition
Resource URI: {apiRoot}/nnwdaf-mlmodelprovision/v1/subscriptions/{subscriptionId}
This resource shall support the resource URI variables defined in table 5.4.3.3.2-1.
Table 5.4.3.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See subclause 5.4.1 |
|
subscriptionId |
string |
Identifies a subscription to the Nnwdaf_MLModelProvision Service |
5.4.3.3.3 Resource Standard Methods
5.4.3.3.3.1 PUT
This method shall support the URI query parameters specified in table 5.4.3.3.3.1-1.
Table 5.4.3.3.3.1-1: URI query parameters supported by the PUT method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 5.4.3.3.3.1-2 and the response data structures and response codes specified in table 5.4.3.3.3.1-3.
Table 5.4.3.3.3.1-2: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
NwdafMLModelProvSubsc |
M |
1 |
Parameters to replace a subscription to NWDAF ML Model Provision Subscription resource. |
Table 5.4.3.3.3.1-3: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
NwdafMLModelProvSubsc |
M |
1 |
200 OK |
The Individual NWDAF ML Model Provision Subscription resource was modified successfully and a representation of that resource is returned. |
|
n/a |
204 No Content |
The Individual NWDAF ML Model Provision Subscription resource was modified successfully. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during Individual NWDAF ML Model Provision Subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NWDAF (service) instance. Applicable if the feature "ES3XX" is supported. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during Individual NWDAF ML Model Provision Subscription modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NWDAF (service) instance. Applicable if the feature "ES3XX" is supported. |
|
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [6] also apply. |
||||
Table 5.4.3.3.3.1-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NWDAF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected |
Table 5.4.3.3.3.1-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NWDAF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected |
5.4.3.3.3.2 DELETE
This method shall support the URI query parameters specified in table 5.4.3.3.3.2-1.
Table 5.4.3.3.3.2-1: URI query parameters supported by the DELETE method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 5.4.3.3.3.2-2 and the response data structures and response codes specified in table 5.4.3.3.3.2-3.
Table 5.4.3.3.3.2-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 5.4.3.3.3.2-3: Data structures supported by the DELETE Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Successful case: The Individual NWDAF ML Model Provision Subscription resource matching the subscriptionId was deleted. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during Individual NWDAF ML Model Provision Subscription deletion. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NWDAF (service) instance. Applicable if the feature "ES3XX" is supported. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during Individual NWDAF ML Model Provision Subscription deletion. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NWDAF (service) instance. Applicable if the feature "ES3XX" is supported. |
|
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [6] also apply. |
||||
Table 5.4.3.3.3.2-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NWDAF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected |
Table 5.4.3.3.3.2-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative NWDAF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the request is redirected |
5.4.3.3.4 Resource Custom Operations
None in this release of the specification.
5.4.4 Custom Operations without associated resources
None in this release of the specification.
5.4.5 Notifications
5.4.5.1 General
Notifications shall comply with subclause 6.2 of 3GPP TS 29.500 [6] and subclause 4.6.2.3 of 3GPP TS 29.501 [7].
Table 5.4.3.4.1-1: Notifications overview
|
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
|
Event Notification |
{notifUri} |
POST |
Report one or several observed Events. |
5.4.5.2 Event Notification
5.4.5.2.1 Description
The Event Notification is used by the NWDAF to report one or several observed Events to a NF service consumer that has subscribed to such Notifications via the Individual NWDAF ML Model Provision Subscription Resource.
5.4.5.2.2 Operation Definition
Callback URI: {notifUri}
The operation shall support the callback URI variables defined in table 5.4.5.2.2-1, the request data structures specified in table 5.4.5.2.2-2 and the response data structure and response codes specified in table 5.4.5.2.2-3.
Table 5.4.5.2.2-1: Callback URI variables
|
Name |
Data type |
Definition |
|
notifUri |
Uri |
The Notification Uri as assigned within the Individual NWDAF ML Model Provision Subscription and described within the NwdafMLModelProvSubsc type (see table 5.4.6.2.2-1). |
Table 5.4.5.2.2-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
NwdafMLModelProvNotif |
M |
1..N |
Provides Information about observed events |
Table 5.4.5.2.2-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
The receipt of the Notification is acknowledged. |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during the event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF consumer (service) instance where the notification should be sent. Applicable if the feature "ES3XX" is supported. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during the event notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative NF consumer (service) instance where the notification should be sent. Applicable if the feature "ES3XX" is supported. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [6] also apply. |
||||
Table 5.4.5.2.2-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative NF consumer (service) instance towards which the notification should be redirected. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the notification request is redirected |
Table 5.4.5.2.2-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative NF consumer (service) instance towards which the notification should be redirected. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target NF (service) instance towards which the notification request is redirected |
5.4.6 Data Model
5.4.6.1 General
This subclause specifies the application data model supported by the API.
Table 5.4.6.1-1 specifies the data types defined for the Nnwdaf_ service based interface protocol.
Table 5.4.6.1-1: Nnwdaf_MLModelProvision specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
NwdafMLModelProvSubsc |
5.4.6.2.2 |
||
|
NwdafMLModelProvNotif |
5.4.6.2.5 |
||
|
MLEventSubscription |
5.4.6.2.3 |
||
|
MLEventNotif |
5.4.6.2.6 |
||
|
MLAnalyticsFilter |
5.4.6.2.4 |
Table 5.4.6.1-2 specifies data types re-used by the Nnwdaf_MLModelProvision service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nnwdaf service based interface.
Table 5.4.6.1-2: Nnwdaf_MLModelProvision re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|||
|
DateTime |
3GPP TS 29.571 [8] |
Identifies the time. |
||||
|
EventFilter |
5.2.6.2.3 |
Identifies the filter for the subscribed event. |
||||
|
NetworkAreaInfo |
3GPP TS 29.554 [18] |
Identifies the network area. |
||||
|
NwdafEvent |
5.1.6.3.4 |
|||||
|
RedirectResponse |
3GPP TS 29.571 [8] |
|||||
|
ReportingInformation |
3GPP TS 29.523 [20] |
Represents the requirements of reporting the subscription. |
||||
|
SupportedFeatures |
3GPP TS 29.571 [8] |
|||||
|
TargetUeInformation |
5.1.6.2.8 |
|||||
|
TimeWindow |
3GPP TS 29.122 [19] |
|||||
|
Uri |
3GPP TS 29.571 [8] |
|||||
5.4.6.2 Structured data types
5.4.6.2.1 Introduction
This subclause defines the structures to be used in resource representations.
5.4.6.2.2 Type NwdafMLModelProvSubsc
Table 5.4.6.2.2-1: Definition of type NwdafMLModelProvSubsc
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
mLEventSubscs |
array(MLEventSubscription) |
M |
1..N |
Each element identifies the subscription for each event. |
|
|
notifUri |
Uri |
M |
1 |
Identifies the recipient of Notifications sent by the NWDAF. |
|
|
mLEventNotifs |
array(MLEventNotif) |
C |
1..N |
Notifications about Individual Events. Shall only be present if the immediate reporting indication in the "immRep" attribute within the "evtReq" attribute sets to true in the event subscription, and the reports are available. |
|
|
suppFeats |
SupportedFeatures |
C |
0..1 |
List of Supported features used as described in subclause 5.4.8. It shall be supplied by NF service consumer in the POST requests that request the creation of an NWDAF ML Model Provision Subscriptions resource, and shall be supplied by the NWDAF in the reply of corresponding request. |
|
|
notifCorreId |
string |
O |
0..1 |
The value of Notification Correlation ID in the corresponding notification. |
|
|
eventReq |
ReportingInformation |
O |
0..1 |
Reporting requirement information of the subscription. If omitted, the default values within the ReportingInformation data type apply. |
Editor’s Note: It’s FFS for partial failure events handling.
5.4.6.2.3 Type MLEventSubscription
Table 5.4.6.2.3-1: Definition of type MLEventSubscription
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
mLEvent |
NwdafEvent |
M |
1..N |
Identifies the subscribed event. |
|
|
mLEventFilter |
EventFilter |
M |
1..N |
Identifies the analytics filter for the subscribed event. |
|
|
tgtUe |
TargetUeInformation |
O |
0..1 |
Identifies target UE information |
|
|
mLTgtPeriod |
TimeWindow |
O |
0..1 |
Indicates the time interval during which the ML model shall be reported. |
5.4.6.2.4 Void
5.4.6.2.5 Type NwdafMLModelProvNotif
Table 5.4.6.2.5-1: Definition of type NwdafMLModelProvNotif
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
eventNotifs |
array(MLEventNotif) |
M |
1..N |
Notifications about Individual Events |
|
|
subscriptionId |
string |
M |
1 |
String identifying a subscription to the Nnwdaf_MLModelProvision Service |
5.4.6.2.6 Type MLEventNotif
Table 5.4.6.2.6-1: Definition of type MLEventNotif
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
event |
NwdafEvent |
M |
1 |
Identifies the subscribed event. |
|
|
notifCorreId |
string |
O |
0..1 |
Notification correlation ID used to identify the subscription to which the notification relates. It shall be set to the same value as the "notifCorreId" attribute of NwdafMLModelProvSubsc data type. |
|
|
mLFileAddr |
string |
M |
0..1 |
Indicates the address (e.g. a URL or an FQDN) of the ML model file. |
|
|
validityPeriod |
TimeWindow |
O |
0..1 |
Indicates the time period when the provided ML model applies. |
|
|
spatialValidity |
NetworkAreaInfo |
O |
0..1 |
Indicates the area where the provided ML model applies. |
5.4.6.3 Simple data types and enumerations
5.4.6.3.1 Introduction
This subclause defines simple data types and enumerations that can be referenced from data structures defined in the previous subclauses.
5.4.6.3.2 Simple data types
The simple data types defined in table 5.1.6.3.2-1 shall be supported.
Table 5.4.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.4.7 Error handling
5.4.7.1 General
HTTP error handling shall be supported as specified in subclause 5.2.4 of 3GPP TS 29.500 [6].
For the Nnwdaf_MLModelProvision API, HTTP error responses shall be supported as specified in subclause 4.8 of 3GPP TS 29.501 [7].
Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [6] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [6].
Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [6] for HTTP redirections shall be supported if the feature "ES3XX" is supported.
In addition, the requirements in the following subclauses shall apply.
5.4.7.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the Nnwdaf_MLModelProvision API.
5.4.7.3 Application Errors
The application errors defined for the Nnwdaf_MLModelProvision API are listed in table 5.4.7.3-1. The NWDAF shall include in the HTTP status code a "ProblemDetails" data structure with the "cause" attribute indicating the application error as listed in table 5.4.7.3-1.
Table 5.4.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
5.4.8 Feature negotiation
The optional features in table 5.4.8-1 are defined for the Nnwdaf_MLModelProvision API. They shall be negotiated using the extensibility mechanism defined in subclause 6.6 of 3GPP TS 29.500 [6].
Table 5.4.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
|
1 |
ServiceExperience |
This feature indicates support for the event related to service experience. |
|
2 |
UeMobility |
This feature indicates the support of analytics based on UE mobility information. |
|
3 |
UeCommunication |
This feature indicates the support of analytics based on UE communication information. |
|
4 |
QoSSustainability |
This feature indicates support for the event related to QoS sustainability. |
|
5 |
AbnormalBehaviour |
This feature indicates support for the event related to abnormal behaviour information. |
|
6 |
UserDataCongestion |
This feature indicates support for the event related to user data congestion. |
|
7 |
NfLoad |
This feature indicates the support of the analytics related to the load of NF instances. |
|
8 |
NetworkPerformance |
This feature indicates support of analytics based on network performance. |
|
9 |
NsiLoad |
This feature indicates support of the event related to the load level of Network Slice and the optionally associated Network Slice Instance. |
|
10 |
SMCongestion |
This feature indicates support for the event related to SM congestion control experience. |
|
11 |
RedundantTransmission |
This feature indicates support for the event related to redundant transmission. |
|
12 |
WLANPerformance |
This feature indicates support for the event related to WLAN performance. |
|
13 |
ES3XX |
Extended Support for 3xx redirections. This feature indicates the support of redirection for any service operation, according to Stateless NF procedures as specified in subclauses 6.5.3.2 and 6.5.3.3 of 3GPP TS 29.500 [6] and according to HTTP redirection principles for indirect communication, as specified in subclause 6.10.9 of 3GPP TS 29.500 [6]. |
5.4.9 Security
As indicated in 3GPP TS 33.501 [13] and 3GPP TS 29.500 [6], the access to the Nnwdaf_MLModelProvision API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [14]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [12]) plays the role of the authorization server.
If OAuth2 is used, a n NF Service Consumer, prior to consuming services offered by the Nnwdaf_MLModelProvision API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [12], subclause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nnwdaf_MLModelProvision service.
The Nnwdaf_MLModelProvision API defines a single scope "nnwdaf-mlmodelprovision" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification