5.4 Nnwdaf_MLModelProvision Service API

29.5203GPP5G SystemNetwork Data Analytics ServicesRelease 18Stage 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 clause 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 clause 5.4.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 clause 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 clause 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 clause 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 clause 5.2.3.2 of 3GPP TS 29.500 [6] and may support HTTP custom header fields specified in clause 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

This clause describes the structure for the Resource URIs and the resources and methods used for the service.

Figure 5.4.3.1-1 depicts the resource URIs structure for the Nnwdaf_MLModelProvision API.

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/<apiVersion>/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 clause 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

Creates 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.

ProblemDetails

O

0..1

500 Internal Server Error

(NOTE 2)

NOTE 1: 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.

NOTE 2: Failure causes are described in subclause 5.4.7.3.

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/<apiVersion>/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/<apiVersion>/subscriptions/{subscriptionId}

The <apiVersion> shall be set as described in clause 5.4.1.

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 clause 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.

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.

ProblemDetails

O

0..1

500 Internal Server Error

(NOTE 2)

NOTE 1: 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.

NOTE 2: Failure causes are described in subclause 5.4.7.3.

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.

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.

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 clause 6.2 of 3GPP TS 29.500 [6] and clause 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

array(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.

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.

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 clause specifies the application data model supported by the API.

Table 5.4.6.1-1 specifies the data types defined for the Nnwdaf_MLModelProvision service based interface protocol.

Table 5.4.6.1-1: Nnwdaf_MLModelProvision specific Data Types

Data type

Section defined

Description

Applicability

FailureEventInfoForMLModel

5.4.6.2.7

MLEventNotif

5.4.6.2.6

MLEventSubscription

5.4.6.2.3

MLModelAddr

5.4.6.2.8

NwdafMLModelProvNotif

5.4.6.2.5

NwdafMLModelProvSubsc

5.4.6.2.2

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_MLModelProvision 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 clause 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 "eventReq" 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 clause 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.

failEventReports

array(FailureEventInfoForMLModel)

O

1..N

Supplied by the NWDAF containing MTLF when available, shall contain the event(s) that the subscription is not successful including the failure reason(s).

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

Identifies the subscribed event.

mLEventFilter

EventFilter

M

1

Identifies the analytics filter for the subscribed event.

tgtUe

TargetUeInformation

O

0..1

Identifies target UE information

mLTargetPeriod

TimeWindow

O

0..1

Indicates the time interval during which the ML model shall be reported.

expiryTime

DateTime

O

0..1

Indicates the time when the subscription expired.

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

MLModelAddr

M

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.2.7 Type FailureEventInfoForMLModel

Table 5.1.6.2.7-1: Definition of type FailureEventInfoForMLModel

Attribute name

Data type

P

Cardinality

Description

Applicability

event

NwdafEvent

M

1

Event that is subscribed.

failureCode

FailureCode

M

1

Identifies the failure reason.

5.4.6.2.8 Type MLModelAddr

Table 5.4.6.2.8-1: Definition of type MLModelAddr

Attribute name

Data type

P

Cardinality

Description

Applicability

mLModelUrl

Uri

C

0..1

The URL of the ML Model file.

(NOTE)

mlFileFqdn

string

C

0..1

The FQDN of the ML Model file.

(NOTE)

NOTE: One of the "mLModelUrl" and "mlFileFqdn" attributes shall be provided.

5.4.6.3 Simple data types and enumerations

5.4.6.3.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

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.6.3.3 Enumeration: FailureCode

Table 5.4.6.3.3-1: Enumeration FailureCode

Enumeration value

Description

Applicability

UNAVAILABLE_ML_MODEL

Indicates the requested ML model for the event is unavailable.

5.4.7 Error handling

5.4.7.1 General

HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [6].

For the Nnwdaf_MLModelProvision API, HTTP error responses shall be supported as specified in clause 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.

In addition, the requirements in the following clauses 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.

Table 5.4.7.3-1: Application errors

Application Error

HTTP status code

Description

UNAVAILABLE_ML_MODEL_FOR_ALLEVENTS

500 Internal Server Error

Indicates the requested all events ML model is unavailable.

NOTE: Including a "ProblemDetails" data structure with the "cause" attribute in the HTTP response is optional unless explicitly mandated in the service operation clauses.

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 clause 6.6 of 3GPP TS 29.500 [6].

Table 5.4.8-1: Supported Features

Feature number

Feature Name

Description

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], clause 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