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