5.2 Information applicable to several APIs
29.1223GPPRelease 18T8 reference point for Northbound APIsTS
5.2.1 Data Types
5.2.1.1 Introduction
This clause defines structured data types, simple data types and enumerations that are applicable to several APIs defined in the present specification and can be referenced from data structures defined in the subsequent clauses. In addition, data types that are defined in OpenAPI Specification [27] can also be referenced from data structures defined in the subsequent clauses.
NOTE: As a convention, data types in the present specification are written with an upper-case letter in the beginning. Parameters are written with a lower-case letter in the beginning. As an exception, data types that are also defined in OpenAPI Specification [27] can use a lower-case case letter in the beginning for consistency.
Table 5.2.1.1-1 lists these common data types.
Table 5.2.1.1-1: Common Data Types applicable to several T8 APIs
Data type |
Section defined |
Description |
Applicability |
AccumulatedUsage |
5.2.1.2.7 |
Represents an accumulated usage. |
|
Acknowledgement |
5.2.1.2.4 |
Represents a successful acknowledgement of a notification. |
|
Bandwidth |
5.2.1.3.2 |
Represents an integer indicating a bandwidth in bits per second. |
|
BdtReferenceId |
5.2.1.3.2 |
Represents a BDT Reference ID. |
|
BdtReferenceIdRm |
5.2.1.3.2 |
Represents the same as the BdtReferenceId data type, but with the "nullable: true" property. |
|
Binary |
5.2.1.3.2 |
String with format "binary" as defined in the OpenAPI Specification. |
|
Bytes |
5.2.1.3.2 |
String with format "byte" as defined in the OpenAPI Specification. |
|
ConfigResult |
5.2.1.2.15 |
Represents one configuration processing result for a group’s members. |
|
DateTime |
5.2.1.3.2 |
String with format "date-time" as defined in OpenAPI Specification. |
|
DateTimeRm |
5.2.1.3.2 |
Represents the same as the DateTime data type, but with the "nullable: true" property. |
|
DateTimeRo |
5.2.1.3.2 |
Represents the same as the DateTime data type, but with the "readOnly=true" property. |
|
DayOfWeek |
5.2.1.3.2 |
Integer between 1 and 7 denoting a weekday. 1 shall indicate Monday, and the subsequent weekdays shall be indicated with the next higher numbers. 7 shall indicate Sunday. |
|
DurationMin |
5.2.1.3.2 |
Unsigned integer identifying a period of time in units of minutes. |
|
DurationSec |
5.2.1.3.2 |
Unsigned integer identifying a period of time in units of seconds. |
|
DurationSecRm |
5.2.1.3.2 |
Represents the same as the DurationSec data type, but with the "nullable: true" property. |
|
DurationSecRo |
5.2.1.3.2 |
Represents the same as the DurationSec data type, but with the "readOnly=true" property. |
|
Event |
5.2.1.3.3 |
Represents a bearer event. |
|
EventReport |
5.2.1.2.6 |
Represents an event report. |
|
EthFlowInfo |
5.2.1.2.18 |
Represents flow Ethernet flow information |
|
ExternalGroupId |
5.2.1.3.2 |
Represents an external group identifier. |
|
ExternalId |
5.2.1.3.2 |
Represents an external identifier. |
|
FlowInfo |
5.2.1.2.8 |
Represents IP flow information. |
|
InvalidParam |
5.2.1.2.13 |
Represents the description of invalid parameters, for a request rejected due to invalid parameters. |
|
Ipv4Addr |
5.2.1.3.2 |
Represents an IPv4 address. |
|
Ipv4AddrRo |
5.2.1.3.2 |
Represents the same as the Ipv4Addr data type, but with the "readOnly=true" property. |
|
Ipv6Addr |
5.2.1.3.2 |
Represents an IPv6 address. |
|
Ipv6AddrRo |
5.2.1.3.2 |
Represents the same as the Ipv6Addr data type, but with the "readOnly=true" property. |
|
Link |
5.2.1.3.2 |
Represents a link towards a referenced resource. |
|
LinkRm |
5.2.1.3.2 |
Represents the same as the Link data type, but with the "nullable: true" property. |
|
LocationArea |
5.2.1.2.11 |
Represents a user location area. |
|
LocationArea5G |
5.2.1.2.17 |
Represents a user location area when the UE is attached to 5G. |
|
Mcc |
5.2.1.3.2 |
Represents a Mobile Country Code. |
|
Mnc |
5.2.1.3.2 |
Represents a Mobile Network Code. |
|
Msisdn |
5.2.1.3.2 |
Represents an MSISDN. |
|
NotificationData |
5.2.1.2.5 |
Represents the information to be conveyed in a bearer level event(s) notification. |
|
PlmnId |
5.2.1.2.14 |
Represents the identifier of a PLMN. |
|
Port |
5.2.1.3.2 |
Unsigned integer with valid values between 0 and 65535 representing a port. |
|
PortRo |
5.2.1.3.2 |
Represents the same as the Port data type, but with the "readOnly=true" property. |
|
ProblemDetails |
5.2.1.2.12 |
Represents additional information and details on an error response. |
|
ResourceId |
5.2.1.3.2 |
Represents an identifier of a resource within a resource URI. |
|
ResultReason |
5.2.1.3.4 |
Represents a failure result reason. |
|
ScsAsId |
5.2.1.3.2 |
Represents an SCS/AS identifier. |
|
SponsorInformation |
5.2.1.2.1 |
Represents a sponsor information. |
|
TestNotification |
5.2.1.2.9 |
Represents a notification that can be sent to test whether a chosen notification mechanism works. |
|
TimeOfDay |
5.2.1.3.2 |
Represents a time in a day. |
|
TimeWindow |
5.2.1.2.3 |
Represents a time window identified by a start time and a stop time. |
|
Uri |
5.2.1.3.2 |
Represents a URI. |
|
UsageThreshold |
5.2.1.2.2 |
Represents a usage threshold. |
|
UsageThresholdRm |
5.2.1.2.16 |
Represents the same as the UsageThreshold data type but with the "nullable: true" property. |
|
Volume |
5.2.1.3.2 |
Unsigned integer identifying a volume in units of bytes. |
|
VolumeRm |
5.2.1.3.2 |
Represents the same as the Volume data type, but with the "readOnly=true" property. |
|
WebsockNotifConfig |
5.2.1.2.10 |
Represents the configuration information for the delivery of notifications over Websockets. |
5.2.1.2 Referenced structured data types
5.2.1.2.1 Type: SponsorInformation
This type represents a sponsor information. It shall comply with the provisions defined in table 5.2.1.2.1-1.
Table 5.2.1.2.1-1: Definition of the SponsorInformation data type
Attribute name |
Data type |
Cardinality |
Description |
sponsorId |
string |
1 |
It indicates Sponsor ID. |
aspId |
string |
1 |
It indicates Application Service Provider ID. |
5.2.1.2.2 Type: UsageThreshold
This type represents a usage threshold. It shall comply with the provisions defined in table 5.2.1.2.2-1.
Only one of DownlinkVolume, UplinkVolume and TotalVolume shall be provided. If the server supports both duration and volume, then the first threshold that has been reached will apply.
Table 5.2.1.2.2-1: Definition of the UsageThreshold data type
Attribute name |
Data type |
Cardinality |
Description |
duration |
DurationSec |
0..1 |
Indicates the length of time in seconds |
totalVolume |
Volume |
0..1 |
Total data octets for both downlink and uplink |
downlinkVolume |
Volume |
0..1 |
Downlink data octets |
uplinkVolume |
Volume |
0..1 |
Uplink data octets |
5.2.1.2.3 Type: TimeWindow
This type represents a start time and a stop time of a time window. It shall comply with the provisions defined in table 5.2.1.2.3-1.
Table 5.2.1.2.3-1: Definition of the TimeWindow data type
Attribute name |
Data type |
Cardinality |
Description |
startTime |
DateTime |
1 |
Indicates the absolute start time of the time window |
stopTime |
DateTime |
1 |
Indicates the absolute stop time of the time window |
5.2.1.2.4 Type: Acknowledgement
This type represents a successful acknowledgement for a notification.
Table 5.2.1.2.4-1: Definition of the Acknowledgement data type
Attribute name |
Data type |
Cardinality |
Description |
details |
string |
1 |
A human-readable explanation specific to this successful acknowledgement |
5.2.1.2.5 Type: NotificationData
This type represents the parameters which shall be notify the SCS/AS for bearer level event(s).
Table 5.2.1.2.5-1: Definition of the NotificationData data type
Attribute name |
Data type |
Cardinality |
Description |
transaction |
Link |
1 |
Link to the transaction resource to which this notification is related. |
eventReports |
array(EventReport) |
1..N |
Contains the reported event and applicable information |
5.2.1.2.6 Type: EventReport
This type represents an event report. It shall comply with the provisions defined in table 5.2.1.2.6-1.
Table 5.2.1.2.6-1: Definition of the EventReport data type
Attribute name |
Data type |
Cardinality |
Description |
event |
Event |
1 |
Indicates the event reported by the SCEF. |
accumulatedUsage |
AccumulatedUsage |
0..1 |
Contains the applicable information corresponding to the event. |
flowIds |
array(integer) |
0..N |
Identifies the IP flows that were sent during event subscription |
5.2.1.2.7 Type: AccumulatedUsage
This type represents an accumulated usage. It shall comply with the provisions defined in table 5.2.1.2.7-1.
Table 5.2.1.2.7-1: Definition of the AccumulatedUsage data type
Attribute name |
Data type |
Cardinality |
Description |
duration |
DurationSec |
0..1 |
Indicates the length of time in seconds |
totalVolume |
Volume |
0..1 |
Total data octets for both downlink and uplink |
downlinkVolume |
Volume |
0..1 |
Downlink data octets |
uplinkVolume |
Volume |
0..1 |
Uplink data octets |
5.2.1.2.8 Type: FlowInfo
This type represents flow information. It shall comply with the provisions defined in table 5.2.1.2.8-1.
Table 5.2.1.2.8-1: Definition of the FlowInfo data type
Attribute name |
Data type |
Cardinality |
Description |
flowId |
integer |
1 |
Indicates the IP flow. |
flowDescriptions |
array(string) |
0..2 |
Indicates the packet filters of the IP flow. Refer to clause 5.3.8 of 3GPP TS 29.214 [10] for encoding. It shall contain UL and/or DL IP flow description. |
NOTE: This data type is not on par with the information that can be provided via N5, namely the ToSTrafficClass attribute is not included here because the respective IP header fields can be changed by the operator network and there is no description about how to address this issue.
5.2.1.2.9 Type: TestNotification
This type represents a notification that can be sent to test whether a chosen notification mechanism works. It shall be supported if the feature "Notification_test_event", as defined for APIs that use notifications, is supported.
Table 5.2.1.2.9-1: Definition of the TestNotification data type
Attribute name |
Data type |
Cardinality |
Description |
subscription |
Link |
1 |
Link of the subscription resource to which the notification is related. |
5.2.1.2.10 Type: WebsockNotifConfig
This type represents configuration for the delivery of notifications over Websockets. It shall be supported if the feature "Notification_websocket", as defined for APIs that use notifications, is supported.
Table 5.2.1.2.10-1: Definition of the WebsockNotifConfig data type
Attribute name |
Data type |
Cardinality |
Description |
websocketUri |
Link |
0..1 |
Set by the SCEF to indicate to the SCS/AS the Websocket URI to be used for delivering notifications. (NOTE 1) |
requestWebsocketUri |
boolean |
0..1 |
Set by the SCS/AS to indicate that the Websocket delivery is requested. (NOTE 2) |
NOTE 1: A Websocket URI should use the scheme "wss" (Websocket Secure) for encrypted delivery and may use the scheme "ws" (Websocket) for unencrypted delivery. If the WebsockNotifConfig data type is used in an HTTP response, this attribute shall be present. If the WebsockNotifConfig data type is used in an HTTP request, this attribute shall not be set by the SCS/AS in a request to create a resource, and shall not be modified by the SCS/AS in a request to modify a resource. NOTE 2: In a request to create or update a resource, this attribute shall be set to true by the SCS/AS to request the SCEF to provide a Websocket URI for the delivery of notifications, and shall be absent otherwise. In any HTTP response, this attribute shall retain the value that was provided upon resource creation or update. |
5.2.1.2.11 Type: LocationArea
This data type represents the user location area which is sent from the SCS/AS to the SCEF.
Table 5.2.1.2.11-1: Definition of the LocationArea data Type
Attribute name |
Data type |
Cardinality |
Description |
cellIds |
array(string) |
0..N |
Indicates a list of Cell Global Identities of the user which identifies the cell the UE is registered. |
enodeBIds |
array(string) |
0..N |
Indicates a list of eNodeB identities in which the UE is currently located. |
routingAreaIds |
array(string) |
0..N |
Identifies a list of Routing Area Identities of the user where the UE is located. |
trackingAreaIds |
array(string) |
0..N |
Identifies a list of Tracking Area Identities of the user where the UE is located. |
geographicAreas |
array(GeographicArea) |
0..N |
Identifies a list of geographic area of the user where the UE is located. |
civicAddresses |
array(CivicAddress) |
0..N |
Identifies a list of civic addresses of the user where the UE is located. |
5.2.1.2.12 Type: ProblemDetails
Table 5.2.1.2.12-1: Definition of the ProblemDetails data type
Attribute name |
Data type |
Cardinality |
Description |
type |
Uri |
0..1 |
A URI reference according to IETF RFC 3986 [6] that identifies the problem type. |
title |
string |
0..1 |
A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem. |
status |
integer |
0..1 |
The HTTP status code for this occurrence of the problem. |
detail |
string |
0..1 |
A human-readable explanation specific to this occurrence of the problem. |
instance |
Uri |
0..1 |
A URI reference that identifies the specific occurrence of the problem. |
cause |
string |
0..1 |
A machine-readable application error cause specific to this occurrence of the problem This IE should be present and provide application-related error information, if available. |
invalidParams |
array(InvalidParam) |
0..N |
Description of invalid parameters, for a request rejected due to invalid parameters. |
supportedFeatures |
SupportedFeatures |
0..1 |
Features supported by the server (SCEF or SCS/AS). When present, this IE shall indicate the features supported by the server; if the server supports no features, this IE shall be set to the character "0". |
NOTE 1: See IETF RFC 7807 [8] for detailed information and guidance for each attribute. NOTE 2: Additional attributes may be defined per API. |
5.2.1.2.13 Type: InvalidParam
Table 5.2.1.2.13-1: Definition of the InvalidParam data type
Attribute name |
Data type |
Cardinality |
Description |
param |
string |
1 |
Attribute’s name encoded as a JSON Pointer, or header’s name. |
reason |
string |
0..1 |
A human-readable reason, e.g. "must be a positive integer". |
5.2.1.2.14 Type: PlmnId
Table 5.2.1.2.14-1: Definition of the PlmnId data type
Attribute name |
Data type |
Cardinality |
Description |
mcc |
Mcc |
1 |
Mobile Country Code |
mnc |
Mnc |
1 |
Mobile Network Code |
5.2.1.2.15 Type: ConfigResult
This type represents one configuration processing result for the group members.
Table 5.2.1.2.15-1: Definition of the ConfigResult data type
Attribute name |
Data type |
Cardinality |
Description |
externalIds |
array(ExternalId) |
0..N |
Each element indicates an external identifier of the UE. (NOTE) |
msisdns |
array(Msisdn) |
0..N |
Each element identifies the MS internal PSTN/ISDN number allocated for the UE (NOTE) |
resultReason |
ResultReason |
1 |
Identifies the configuration failure reason for the group members. |
NOTE: Either "externalId" or "msisdn" shall be included for a group member. |
5.2.1.2.16 Type: UsageThresholdRm
This type represents a usage threshold which is defined in clause 5.2.1.2.2 but defined with "nullable: true" property so it can be removed in "JSON Merge Patch", as defined in IETF RFC 7396 [39]. It shall comply with the provisions defined in table 5.2.1.2.16-1.
Only one of "downlinkVolume", "uplinkVolume" and "totalVolume" shall be provided. Duration and volume are also removable in "JSON Merge Patch". If the server supports both duration and volume, then the first threshold that has been reached will apply.
Table 5.2.1.2.16-1: Definition of the UsageThresholdRm data type
Attribute name |
Data type |
Cardinality |
Description |
duration |
DurationSecRm |
0..1 |
Indicates the length of time in seconds |
totalVolume |
VolumeRm |
0..1 |
Total data octets for both downlink and uplink |
downlinkVolume |
VolumeRm |
0..1 |
Downlink data octets |
uplinkVolume |
VolumeRm |
0..1 |
Uplink data octets |
5.2.1.2.17 Type: LocationArea5G
This data type represents the user location area which is sent from the AF to the NEF.
Table 5.2.1.2.17-1: Definition of the LocationArea5G data Type
Attribute name |
Data type |
Cardinality |
Description |
geographicAreas |
array(GeographicArea) |
0..N |
Identifies a list of geographic area of the user where the UE is located. |
civicAddresses |
array(CivicAddress) |
0..N |
Identifies a list of civic addresses of the user where the UE is located. |
nwAreaInfo |
NetworkAreaInfo |
0..1 |
This IE represents the network area information of the user where the UE is located. |
5.2.1.2.18 Type: EthFlowInfo
This type represents Ethernet flow information. It shall comply with the provisions defined in table 5.2.1.2.18-1.
Table 5.2.1.2.18-1: Definition of the EthFlowInfo data type
Attribute name |
Data type |
Cardinality |
Description |
flowId |
integer |
1 |
Indicates the Ethernet flow. |
ethFlowDescriptions |
array(EthFlowDescription) |
0..2 |
Indicates the packet filters of the Ethernet flow. Refer to clause 5.6.2.17 of 3GPP TS 29.514 [52] for encoding of each Ethernet flow. It shall contain UL and/or DL Ethernet flow description. |
5.2.1.3 Referenced Simple data types and enumerations
5.2.1.3.1 Introduction
This clause defines simple data types and enumerations that are referenced from data structures.
5.2.1.3.2 Simple data types
The reused datatypes defined in OpenAPI Specification [27] listed in table 5.2.1.3.2-1 and the simple data types defined in table 5.2.1.3.2-2 apply to several T8 APIs.
Table 5.2.1.3.2-1: Reused OpenAPI data types
Type name |
Description |
boolean |
As defined in OpenAPI Specification [27], i.e. either value "true" or value "false" as defined in IETF RFC 7159 [5]. |
integer |
As defined in OpenAPI Specification [27]. |
number |
As defined in OpenAPI Specification [27]. |
string |
As defined in OpenAPI Specification [27]. |
NOTE: Data type names defined in OpenAPI Specification [27] do not follow the convention to start with capital letters otherwise used in this specification. |
Table 5.2.1.3.2-2: Simple data types applicable to several APIs
Type name |
Description |
Bandwidth |
Integer indicating a bandwidth in bits per second. |
BdtReferenceId |
String identifying a BDT Reference ID as defined in clause 5.3.3 of 3GPP TS 29.154 [9]. |
BdtReferenceIdRm |
This data type is defined in the same way as the "BdtReferenceId" data type, but with the "nullable: true" property. |
Binary |
String with format "binary" as defined in OpenAPI Specification [27]. |
Bytes |
String with format "byte" as defined in OpenAPI Specification [27], i.e, base64-encoded characters. |
DayOfWeek |
Integer between and including 1 and 7 denoting a weekday. "1" shall indicate "Monday", and the subsequent weekdays shall be indicated with the next higher numbers. "7" shall indicate "Sunday". |
DateTime |
String with format "date-time" as defined in OpenAPI Specification [27]. |
DateTimeRm |
String with format "date-time" as defined in OpenAPI [27] with "nullable: true" property. |
DateTimeRo |
String with format "date-time" as defined in OpenAPI [27] with "readOnly: true" property. |
DurationSec |
Unsigned integer identifying a period of time in units of seconds. |
DurationSecRm |
Unsigned integer identifying a period of time in units of seconds with "nullable: true" property. |
DurationSecRo |
Unsigned integer identifying a period of time in units of seconds with "readOnly: true" property. |
DurationMin |
Unsigned integer identifying a period of time in units of minutes. |
ExternalId |
String containing a local identifier followed by "@" and a domain identifier. Both the local identifier and the domain identifier shall be encoded as strings that do not contain any "@" characters. See clause 4.6.2 of 3GPP TS 23.682 [2] for more information. |
ExternalGroupId |
String containing a local identifier followed by "@" and a domain identifier. Both the local identifier and the domain identifier shall be encoded as strings that do not contain any "@" characters. See clauses 4.6.2 and 4.6.3 of 3GPP TS 23.682 [2] for more information. |
Ipv4Addr |
String identifying an Ipv4 address formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [28]. |
Ipv6Addr |
String identifying an Ipv6 address formatted according to clause 4 in IETF RFC 5952 [29]. The mixed Ipv4 Ipv6 notation according to clause 5 of IETF RFC 5952 [29] shall not be used. |
Ipv4AddrRo |
String identifying an Ipv4 address formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [28], with "readOnly: true" property. |
Ipv6AddrRo |
String identifying an Ipv6 address formatted according to clause 4 in IETF RFC 5952 [29], with "readOnly: true" property. The mixed Ipv4 Ipv6 notation according to clause 5 of IETF RFC 5952 [29] shall not be used. |
Link |
String formatted according to IETF RFC 3986 [7] identifying a referenced resource. |
LinkRm |
String formatted according to IETF RFC 3986 [7] identifying a referenced resource, but with the "nullable: true" property. |
Mcc |
String encoding a Mobile Country Code part of the PLMN, comprising 3 digits, as defined in 3GPP TS 38.413 [54]. |
Mnc |
String encoding a Mobile Network Code part of the PLMN, comprising 2 or 3 digits, as defined in 3GPP TS 38.413 [54]. |
Msisdn |
String formatted according to clause 3.3 of 3GPP TS 23.003 [14] that describes an MSISDN. |
Port |
Unsigned integer with valid values between 0 and 65535. |
PortRo |
Unsigned integer with valid values between 0 and 65535, with "readOnly: true" property. |
ResourceId |
String chosen by the SCEF to serve as an identifier in a resource URI. |
ScsAsId |
String that identifies an SCS/AS. |
TimeOfDay |
String with format "partial-time" or "full-time" as defined in clause 5.6 of IETF RFC 3339 [15]. Examples: "20:15:00", "20:15:00-08:00" (for 8 hours behind UTC). |
Uri |
String providing an URI formatted according to IETF RFC 3986 [7]. |
Volume |
Unsigned integer identifying a volume in units of bytes. |
VolumeRm |
Unsigned integer identifying a volume in units of bytes with "nullable: true" property. |
5.2.1.3.3 Enumeration: Event
The enumeration Event represents event reported by the SCEF.
Table 5.2.1.3.3-1: Enumeration Event
Enumeration value |
Description |
SESSION_TERMINATION |
Indicates that Rx session is terminated. |
LOSS_OF_BEARER |
Indicates a loss of a bearer. |
RECOVERY_OF_BEARER |
Indicates a recovery of a bearer. |
RELEASE_OF_BEARER |
Indicates a release of a bearer. |
USAGE_REPORT |
Indicates the usage report event. |
FAILED_RESOURCES_ALLOCATION |
Indicates the resource allocation is failed. |
SUCCESSFUL_RESOURCES_ALLOCATION |
Indicates the resource allocation is successful. |
NOTE: The "enNB" feature defined in clause 5.5.4 supports both subscription and notification for SUCCESSFUL_RESOURCES_ALLOCATION event, and explicit subscription for all the events. |
5.2.1.3.4 Enumeration: ResultReason
The enumeration ResultReason represents a failure result reason.
Table 5.2.1.3.4-1: Enumeration ResultReason
Enumeration value |
Description |
ROAMING_NOT_ALLOWED |
Identifies the configuration parameters are not allowed by roaming agreement. |
OTHER_REASON |
Identifies the configuration parameters are not configured due to other reason. |
5.2.1.4 Conventions for documenting structured data types
The structured data types shall represent an object (see IETF RFC 8259 [40]). The structured data types shall contain attributes that are simple data types, structured data types, arrays (see below), maps (see below) or enumerations.
An array (see IETF RFC 8259 [40]) shall represent a list of values without keys and with significance in the order of sequence. All values shall be of the same type.
A map shall represent an object (see IETF RFC 8259 [40]) with a list of key-value pairs (with no significance in the order of sequence), where all keys are of type string and shall be unique identifiers assigned by the application rather than by the schema, and where all values shall be of the same type.
NOTE 1: Maps are supported by the OpenAPI specification [27] as described at https://swagger.io/docs/specification/data-models/dictionaries/. Maps can enable a faster lookup of elements identified by some key in huge data structures compared to arrays that contain the key within the elements. Maps can also be used instead of arrays to modify individual elements when modification instructions of the PATCH method are compliant to IETF RFC 7396 [39].
Each structured data type shall be specified in a separate clause as illustrated in table 5.2.1.4-1.
Table 5.2.1.4-1: Definition of type <Data type>
Attribute name |
Data type |
Cardinality |
Description |
<attribute name> |
"<type>" or "array(<type>)" or "map(<type>)" |
"0..1", "1", or "M..N", |
<only if applicable> |
Attribute name: Name of attributes that belong to the specified data type.
Data type: Data type of the attribute. If the data type is indicated as "<type>", the attribute shall be of data type <type>. If the data type is indicated as "array(<type>)", the attribute shall be an array (see IETF RFC 8259 [40]) that contains elements of data type <type>. If the data type is indicated as "map (<type>)", the attribute shall be an object (see IETF RFC 8259 [40]) encoding a map (see OpenAPI specification [27]) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [27]), or a data type defined in a 3GPP specification.
Cardinality: Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 1 and M, For data type "<type>", the cardinality shall be set to "0..1" or "1". A lower boundary of "0" for the cardinality also indicates that the attribute is optional. A lower boundary of "0" for the cardinality indicates that the attribute is optional.
NOTE 2: The "0..N" implies the array or map type of the attribute may be optional. If the attribute is present, the minimum number of elements is described in openAPI file.
Description: Describes the meaning and use of the attribute and may contain normative statements.
5.2.2 Usage of HTTP
5.2.2.1 General
For T8 APIs, support of HTTP/1.1 (IETF RFC 7230 [16], IETF RFC 7231 [17], IETF RFC 7232 [18], IETF RFC 7233 [19], IETF RFC 7234 [20] and IETF RFC 7235 [21]) over TLS is mandatory and support of HTTP/2 (IETF RFC 7540 [22]) over TLS is recommended. TLS shall be used as specified in clause 5.5 of 3GPP TS 33.187 [35]. An SCS/AS desiring to use HTTP/2 shall use the HTTP upgrade mechanism to negotiate applicable HTTP version as described in IETF RFC 7540 [22].
5.2.2.2 Usage of the HTTP PATCH method
The HTTP PATCH method, as defined in IETF RFC 5789 [38], allows for a partial update of previously sent data, e.g. resources. For a complete replacement of previously sent data, the HTTP PUT method is used. It is defined separately for each resource whether the HTTP PUT and/or the HTTP PATCH are applicable.
If the HTTP PATCH method is used:
– if no modification of individual elements within an array needs to be supported, the JSON bodies within the PATCH request shall be encoded according to "JSON Merge Patch", as defined in IETF RFC 7396 [39]; or
– if a modification of individual elements within an array needs to be supported, the "JSON Patch" encoding of changes defined in IETF RFC 6902 [67] shall be used.
5.2.3 Content type
The bodies of HTTP request and successful HTTP responses shall be encoded in JSON format (see IETF RFC 8259 [5]).
The MIME media type that shall be used within the related Content-Type header field is "application/json", as defined in IETF RFC 8259 [5].
JSON object used in the HTTP PATCH request shall be encoded according to:
– "JSON Merge Patch" and shall be signalled by the content type "application/merge-patch+json", as defined in IETF RFC 7396 [39]; or
– "JSON Patch" and shall be signalled by the content type "application/json-patch+json", as defined in IETF RFC 6902 [67].
"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 [8].
NOTE: This release only supports the content type JSON.
5.2.4 URI structure
5.2.4.1 Resource URI structure
Resources are either individual resources, or structured resources that can contain child resources. It is recommended to design each resource following one of the archetypes provided in the Annex C of 3GPP TS 29.501 [49].
All API URIs of T8 APIs shall be:
{apiRoot}/<apiName>/<apiVersion>
"apiRoot" is configured by means outside the scope of the present document. "apiName" and "apiVersion" shall be set dependent on the API, as defined in the corresponding clauses below. All resource URIs in the clauses below are defined relative to the above root API URI.
NOTE 1: The "apiVersion" will only be increased if the new API version contains not backward compatible changes. Otherwise, the supported feature mechanism defined in clause 5.2.7 can instead be used to negotiate extensions.
NOTE 2: A different root structure can be used when the Resource URI is preconfigured in the SCS/AS.
The root structure may be followed by "apiSpecificSuffixes" that are dependent on the API and are defined separately for each API as resource URI where they apply:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificSuffixes>
The naming conventions defined in clause 5.1.3 of 3GPP TS 29.501 [49] shall apply.
5.2.4.2 Custom operations URI structure
The URI of a custom operation which is associated with a resource shall have the following structure:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificSuffixes>/<custOpName>
Custom operations can also be associated with the service instead of a resource. The URI of a custom operation which is not associated with a resource shall have the following structure:
{apiRoot}/<apiName>/<apiVersion>/<custOpName>
In the above URI structures, "apiRoot", "apiName", "apiVersion" and "apiSpecificSuffixes" are as defined in clause 5.2.4.1 and "custOpName" represents the name of the custom operation as defined in clause 5.1.3.2 of 3GPP TS 29.501 [49].
5.2.4.3 Callback URI structure
The purpose of the callback URI is to enable an HTTP client (the SCS/AS or SCEF) to provide the URI to be used by an HTTP server (the SCEF or SCS/AS) to send notifications or callback requests.
The callback URI shall be in the form of an absolute URI as defined in clause 4.3 of IETF RFC 3986 [7], including an authority, and excluding any query component, any fragment component and any userinfo subcomponent.
Therefore, a callback URI consists of the following components, specified with ABNF syntax (see IETF RFC 5234 [69]):
URI = scheme ":" "//" host [ ":" port ] / path
Where ‘host’ is either an FQDN or an IP address and the ‘path’ is a path to an HTTP client (the SCS/AS or SCEF) resource.
5.2.5 Notifications
5.2.5.1 General
The SCEF and SCS/AS shall support the delivery of Notifications using a separate HTTP connection towards an address assigned by the SCS/AS, as described in clause 5.2.5.2.
An SCEF and SCS/AS may support testing a notification connection as described in clause 5.2.5.3. An SCEF and SCS/AS may support the delivery of Notification using Websocket (IETF RFC 6455 [32]) as described in clause 5.2.5.4.
5.2.5.2 Notification Delivery using a separate HTTP connection
If a delivery of notifications is required for an API, the SCS/AS shall provide a URI in the "notificationDestination" attribute defined in the data types that are passed in a request to create a resource that represents a subscription to notifications, designating where to send HTTP Notifications to the SCEF unless it is specified for that API that a preconfigured destination address is used.
The SCS/AS may provide the same "notificationDestination" for several subscriptions, and the SCEF should then use the same HTTP connection to deliver related notifications.
The SCEF shall take the role of the HTTP client on the HTTP connection for the delivery of Notifications. Clause 5.2.2 shall also apply for this HTTP connection with the exception that an SCEF (rather than an SCS/AS) desiring to use HTTP/2 shall use the HTTP upgrade mechanism to negotiate applicable HTTP version.
5.2.5.3 Notification Test Event
If the optional "Notification_test_event" feature is supported, the SCS/AS may test whether notifications can be received by subscribing to the notification of a test event by providing a "requestTestNotification" attribute set to "true" in the HTTP request to create or update a subscription for notifications. In any other HTTP request or response, this attribute shall retain the value that was provided upon subscription resource creation.
Upon receiving the "requestTestNotification" attribute as part of a subscription creation or update request, the SCEF shall send immediately after establishing the notification delivery mechanism a test notification containing a body formatted according to the "TestNotification" data type as defined in clause 5.2.1.2.12. If the SCS/AS does not receive the test notification within a configured time, the SCS/AS knows that the notification delivery with the selected method is not possible and may take corrective actions.
5.2.5.4 Notification Delivery using Websocket
The procedures in the present clause only apply if SCS/AS and SCEF support the "Notification_websocket" feature. If the feature "Notification_websocket" is supported, then the feature "Notification_test_event" shall also be supported.
If a delivery of notifications is required for an API and the SCS/AS does not know from previous interactions with the SCEF whether delivery of notifications over a separate HTTP connection works, the SCS/AS should initially request the SCEF to try to establish a separate HTTP connection for notification delivery according to clause 5.2.5.2 by providing a URI to the SCEF designating where to send HTTP Notifications, and shall also subscribe to the notification of a test event as in clause 5.2.5.3.
If the SCS/AS does not receive the requested notification of the test event during a configured period after the subscription, the SCS/AS may configure the subscription to request the SCEF to provide a URI for an HTTP connection to upgrade to Websocket, setting the "requestWebsocketUri" attribute to "true" as specified in clause 5.2.1.2.13. The SCS/AS may also request the SCEF to provide a URI in a new subscription creation request, and should in this case terminate the original subscription.
NOTE 1: If the SCS/AS has requested the delivery of notifications to a separate entity, it needs to be informed by that separate entity about the receipt of the test notification. That communication between the separate entity and the SCS/AS is out of scope of the present document.
When the SCEF receives a subscription creation or update request to use Websockets to deliver notifications (i.e. with the "requestWebsocketUri" attribute set to "true"), it shall assign a Websocket URI where to receive a Websocket connection establishment and provide this URI in the "websocketUri" attribute in the response, as defined in clause 5.1.2.1.13. Once such Websocket URI has been assigned for a particular subscription resource, subsequent update requests to this resource that ask for the assignment of a new Websocket URI for that subscription shall be rejected by the SCEF.
Upon the reception of the Websocket URI from the SCEF in the "websocketUri" attribute, as specified in clause 5.2.1.2.13-1, in the subscription creation or subscription update response, the SCS/AS or a separate entity that is intended to receive the notification shall establish an HTTP connection towards that URI and shall upgrade that connection to the Websocket protocol (IETF RFC 6455 [32]) using the HTTP upgrade mechanism defined in IETF RFC 7230 [16].
NOTE 2: For delivery of Notifications to a separate entity, the SCS/AS needs to provide the Websocket URI to that separate entity. That communication between the SCS/AS and the separate entity is out of scope of the present document.
The following framing of the request and response shall be used when delivering a notification or acknowledging its delivery through Websockets.
NOTE 3: The framing is aligned as much as possible with HTTP delivery in order to simplify implementations.
To deliver a notification towards the SCS/AS, the SCEF shall embed the following structure in a separate Websocket data frame with 0x2 (Binary) opcode in the following order:
1) The string "3GPP-WS-Notif-Seq:", followed by a blank, followed by a four-byte sequence number, encoded as decimal number in ASCII, followed by CRLF
2) The following HTTP headers in any order, with the syntax and semantics as defined in IETF RFC 7230 [16] and IETF RFC 7231 [17]: Content-Type (mandatory), Content-Encoding (optional), Content-Length (mandatory). Every HTTP header line shall be ended by CRLF.
3) CRLF to end the headers section.
4) The payload body of the notification, as defined in the individual APIs.
NOTE 4: The payload body is the same as the one that would be used if delivering the notification as defined in clause 5.2.5.3.
To acknowledge the reception of a notification message towards the SCEF, the SCS/AS shall embed the following structure in a separate Websocket data frame with 0x2 (Binary) opcode in the following order:
1) The string "3GPP-WS-Notif-Seq:", followed by a blank, followed by the four-byte sequence number of the notification to be confirmed, encoded as decimal number in ASCII, followed by CRLF.
2) The HTTP status code (e.g. 204) and status message (e.g. No Content) as defined for HTTP delivery of the notification in the individual APIs, separated by a single blank character, and ended by CRLF.
3) Conditionally, as defined in IETF RFC 7230 [16] and IETF RFC 7231 [17], the following HTTP headers in any order: Content-Type, Content-Encoding, and Content-Length. Every HTTP header line shall be ended by CRLF.
4) CRLF to end the headers section.
5) The payload body of the response, if applicable based on the status code and the HTTP headers, as defined in IETF RFC 7230 [16] and IETF RFC 7231 [17].
NOTE 5: The status code, the status message and the payload body (if applicable), are the same as if delivering the notification as defined in clause 5.2.5.3.
Use of CRLF is defined in IETF RFC 7230 [16].
The SCEF need not wait for the confirmation of each notification before delivering the next notification. The SCEF shall determine whether a notification has been delivered successfully by correlating the sent notification with the received acknowledgement by checking the sequence numbers of both for equality. The SCEF may re-send a notification, using the same sequence number, if it has not received an acknowledgement with a matching sequence number after a configurable time-out. The SCS/AS shall consider notifications with the same sequence number that arrive within a configurable time interval as duplicates.
The SCS/AS should send periodic Websocket "PING" frames to keep the connection alive.
NOTE 6: the TCP layer will handle a possible fragmentation and reassembly of large messages.
The security related clause 6 shall also apply for the HTTP connection that is upgraded to Websocket.
5.2.6 Error handling
Table 5.2.6-1 lists response bodies that are applicable to all APIs and as responses for all requests in the present specification unless otherwise specified. The HTTP client shall mandatorily support the processing of the status code for all the applicable methods, when received in a HTTP response message. In such cases the HTTP client shall also support the handling of the "ProblemDetails" JSON object with the Content-Type header field set to the value "application/problem+json", if the corresponding API definition in the current specification does not specify another response body for the corresponding status code.
Table 5.2.6-1: Response bodies supported for responses to all requests.
Response body |
Data type |
Cardinality |
Response Codes (NOTE 1) |
Remarks (NOTE 2, NOTE 4) |
Applied Methods |
ProblemDetails |
1 |
400 Bad Request |
Incorrect parameters were passed in the request. |
GET, POST PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
401 Unauthorized |
The client is not authorized as described in IETF RFC 7235 [21]. |
GET, POST, PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
403 Forbidden |
This represents the case when the server is able to understand the request but unable to fulfil the request due to errors (e.g. the requested parameters are out of range). More information may be provided in the "invalidParams" attribute of the "ProblemDetails" structure. (NOTE 3) |
GET, POST, PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
404 Not Found |
The resource URI was incorrect, for instance because of a wrong "scsAsId" field. |
GET, POST, PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
406 Not Acceptable |
The content format provided in the "Accept" header is not acceptable by the server. |
GET |
|
ProblemDetails |
1 |
411 Length Required |
The code indicates that the server refuses to accept the request without a Content-Length header field. |
POST, PUT, PATCH |
|
ProblemDetails |
1 |
413 Payload Too Large |
If the received HTTP request contains payload body larger than the server is able to process, the NF shall reject the HTTP request with the HTTP status code "413 Payload Too Large". |
POST, PUT, PATCH |
|
ProblemDetails |
1 |
415 Unsupported Media Type |
The code indicates that the resource is in a format which is not supported by the server for the method. |
POST, PUT, PATCH |
|
ProblemDetails |
1 |
429 Too Many Requests |
The code indicates that due to excessive traffic which, if continued over time, may lead to (or may increase) an overload situation. The HTTP header field "Retry-After" may be added in the response to indicate how long the client has to wait before making a new request. |
GET, POST, PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
500 Internal Server Error |
The server encountered an unexpected condition that prevented it from fulfilling the request. |
GET, POST, PUT, PATCH, DELETE |
|
ProblemDetails |
1 |
503 Service Unavailable |
The server is unable to handle the request. |
GET, POST, PUT, PATCH, DELETE |
|
NOTE 1: In addition to the above response codes, the SCEF can also send other valid HTTP response codes, if applicable. The list of all valid HTTP response codes can be found in HTTP Status Code Registry at IANA [6]. NOTE 2: The MIME media type that shall be used within the related Content-Type header field is "application/problem+json", as defined in IETF RFC 7807 [8]. NOTE 3: The information about which provided parameters are out of range shall be provided in the "invalidParams" attribute of the "ProblemDetails" structure for the API of network parameter configuration. NOTE 4: More information may be provided in the "detail" attribute of the "ProblemDetails" structure. |
The protocol and application errors in clause 5.2.7.2 of 3GPP TS 29.500 [44] are applicable for above status codes for the APIs defined in the present specification. Specific errors are contained in the related API definition for each API.
5.2.7 Feature negotiation
The procedures in clause 6.6.2 of 3GPP TS 29.500 [44] shall be applicable for the APIs defined in the present specification with the difference that the SCEF should not register any feature for northbound APIs in the NRF.
The supported features are negotiated separately for each API. For each of the APIs defined in the present specification, the applicable list of features is contained in the related API definition.
5.2.8 HTTP custom headers
5.2.8.1 General
This clause lists reused HTTP custom headers and defines any new HTTP custom headers introduced by this specification.
5.2.8.2 Reused HTTP custom headers
Table 5.2.8.2-1: Reused HTTP custom headers
Name |
Reference |
Description |
5.2.8.3 Optional HTTP custom headers
5.2.8.3.1 General
The Northbound APIs defined in this specification may support the HTTP custom headers specified in Table 5.2.8.3.1-1 below. A description of each custom header and the normative requirements related to when to include them are also provided in Table 5.2.8.3.1-1.
Table 5.2.8.3.1-1: Optional HTTP custom headers
Name |
Reference |
Description |
Nb-Api-Sender-Timestamp |
clause 5.2.8.3.2 |
This header may be used to indicate the date and time (with a millisecond granularity) at which an HTTP request or response is originated. This may be used e.g. for measuring signalling delays in Northbound interfaces. |
Nb-Api-Max-Rsp-Time |
clause 5.2.8.3.3 |
This header may be used in a HTTP request to indicate the duration during which the HTTP client waits for a response. |
Nb-Api-Lci |
clause 5.2.8.3.4 |
This header may be used by a SCEF to send Load Control Information (LCI) to the sending entity (e.g. SCS/AS, AF). |
Nb-Api-Oci |
clause 5.2.8.3.5 |
This header may be used by an overloaded SCEF in an API response message, or in a notification request message to signal Overload Control Information (OCI) to the sending entity (e.g. SCS/AS, AF). This header may also be used by an overloaded sending entity (e.g. SCS/AS, AF) in a notification response or in an API request to signal Overload Control Information (OCI) to the SCEF. |
5.2.8.3.2 Nbi-Api-Sender-Timestamp
The provisions of clause 5.2.3.3.2 of 3GPP TS 29.500 [44] also apply to this header.
NOTE: Any provisions that are specific to 5G SBI APIs (e.g. related to the support of Indirect Communication models) are however not applicable for Northbound APIs.
5.2.8.3.3 Nb-Api-Max-Rsp-Time
The provisions of clause 5.2.3.3.3 of 3GPP TS 29.500 [44] also apply to this header.
NOTE: Any provisions that are specific to 5G SBI APIs (e.g. related to the support of Indirect Communication models) are however not applicable for Northbound APIs.
5.2.8.3.4 Nbi-Api-Lci
The header contains a comma-delimited list (see IETF RFC 7230 [16]) of Load Control Information (LCI). See clause 5.2.11.
The encoding of the header follows the ABNF as defined in IETF RFC 7230 [16].
Nb-Api-Lci = "Nb-Api-Lci:" 1#(RWS timestamp ";" RWS lcMetric ")
timestamp = "Timestamp:" RWS DQUOTE date-time DQUOTE
Mandatory parameter. The date-time type is specified in IETF RFC 5322 [66] and clause 7.1.1.1 of IETF RFC 7231 [17]. It indicates the timestamp associated with the load control information.
lcMetric = "Load-Metric:" RWS (DIGIT / %x31-39 DIGIT / "100") "%"
Mandatory parameter. Load-Metric is up to 3 digits long decimal string and the value range shall be from 0 to 100.
EXAMPLE: Load Control Information:
Nbi-Api-Lci: Timestamp: "Tue, 04 Feb 2021 08:50:28 GMT"; Load-Metric: 50%
5.2.8.3.5 Nb-Api-Oci
The header contains a comma-delimited list of Overload Control Information (OCI). See clause 5.2.11.
The encoding of the header follows the ABNF as defined in IETF RFC 7230 [16].
Nb-Api-Oci = "Nb-Api-Oci:" 1#(RWS timestamp ";" RWS validityPeriod ";" RWS olcMetric ")
timestamp = "Timestamp:" RWS DQUOTE date-time DQUOTE
Mandatory parameter. The date-time type is specified in IETF RFC 5322 [66] and clause 7.1.1.1 of IETF RFC 7231 [17]. It indicates the timestamp at which the overload control information was generated.
validityPeriod = "Period-of-Validity:" RWS 1*DIGIT "s"
Mandatory parameter. Period of validity is a timer that is measured in seconds. Once the timer expires, the OCI becomes invalid.
olcMetric = "Overload-Reduction-Metric:" RWS (DIGIT / %x31-39 DIGIT / "100") "%"
Mandatory parameter. Overload-Reduction-Metric up to 3 digits long decimal string and the value range shall be from 0 to 100.
EXAMPLE: Overload Control Information:
Nbi-Api-Oci: Timestamp: "Tue, 04 Feb 2021 08:50:28 GMT"; Period-of-Validity: 90s; Overload-Reduction-Metric: 25%
5.2.9 Conventions for Open API specification files
5.2.9.1 General
T8 Open API specification files shall comply with the OpenAPI specification [27] and with the present clause.
Each API shall be described in one Open API specification file. In addition, 3GPP specifications may contain Open API specification file with common data types.
For the purpose of referencing (see clause 5.2.9.6), it is assumed that each Open API specification file contained in a 3GPP specification is stored as separate physical, that all Open API specification files are stored in the same directory on the local server, and that the files are named according to the conventions in clause 5.2.9.6.
5.2.9.2 Formatting of OpenAPI files
The following guidelines shall be used when documenting OpenAPI files:
– OpenAPI specifications shall be documented using YAML format (see YAML 1.2 [41]). For specific restrictions on the usage of YAML in OpenAPI, see OpenAPI Specification [27].
– The style used for the specification shall be "PL" (Programming Language).
– The different scopes in the YAML data structures representing collections (objects, arrays…) shall use an indentation of two white spaces.
– Comments may be added by following the standard YAML syntax ("#").
– Tabs shall not be used in OpenAPI specification files (e.g. within description fields).
– "Unbreakable" spaces (UTF-8 ‘NO-BREAK SPACE’ (U+00A0)) shall not be used in OpenAPI specification files (e.g. within description fields). Only "normal" spaces (UTF-8 ‘SPACE’ (U+0020)) shall be allowed.
– Trailing spaces (i.e. white spaces at the end of a line) should not be used in OpenAPI specification files.
5.2.9.3 Structured data types
The OpenAPI file shall contain a definition in the components/schemas section defining a schema with the name of the structured data type as key.
The schema shall contain:
– "type: object";
– "description: <description>", where <description> is the description of the data type in the table defining the structured data type. The "description" attribute should be provided for all data types, specially if they are frequently reused from the same or other OpenAPI specification files; the "description" attribute shall always be provided for data types defined as maps, with a clear indication of the values (strings) used as key of the map;
– if any attributes in the structured data type are marked as mandatory via a minimum cardinality greater than "0", a "required" keyword listing those attributes; and
– a "properties" keyword containing for each attribute in the structured data type an entry with the attribute name as key and:
1. if the data type is "<type>":
a. if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or
b. otherwise a reference to the data type schema for the data type <data type> of the attribute, i.e. "$ref: ‘#/components/schemas/<data type>‘" if that data type schema is contained in the same OpenAPI file and "$ref: ‘<filename>#/components/schemas/<data type>‘" if that data type schema is contained in file <filename> in the same directory on the same server;
2. if the data type is "array(<type>)":
a. a type definition "type: array";
b. an "items:" definition containing:
i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or
ii). otherwise a reference to the data type schema for the data type <data type> of the attribute, i.e. "$ref: ‘#/components/schemas/<data type>‘" if that data type schema is contained in the same OpenAPI file and "$ref: ‘<filename>#/components/schemas/<data type>‘" if that data type schema is contained in file <filename> in the same directory on the same server;
c. if the cardinality contained an integer value <m> as lower boundary, "minItems: <m>"; and
d. if the cardinality contained an integer value <n> as upper boundary, "maxItems: <n>";
3. if the data type is "map(<type>)":
a. a type definition "type: object";
b. an "additionalProperties:" definition containing:
i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or
ii). otherwise a reference to the data type schema for the data type <data type> of the attribute, i.e. "$ref: ‘#/components/schemas/<data type>‘" if that data type schema is contained in the same OpenAPI file and "$ref: ‘<filename>#/components/schemas/<data type>‘" if that data type schema is contained in file <filename> in the same directory on the same server;
c. if the cardinality contained an integer value <m> as lower boundary, "min Properties: <m>"; and
d. if the cardinality contained an integer value <n> as upper boundary, "max Properties: <n>"; and
4. "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; the "description" attribute shall always be provided for attributes defined as maps, with a clear indication of the values (strings) used as key of the map.
NOTE 1: An omission of the "minProperties", and "maxProperties" keywords indicates that no lower or upper boundaries respectively, for the number of properties in an object are defined. An omission of the "minItems", and "maxItems" keywords indicates that no lower or upper boundaries, respectively, for the number of items in an array are defined.
NOTE 2: The "0..N" implies the array or map type of the attribute may be optional. If the attribute is present, the minimum number of elements is described in openAPI file.
Example:
Table 5.2.9.3-1: Definition of type ExampleStructuredType
Attribute name |
Data type |
Cardinality |
Description |
exSimple |
ExSimple |
1 |
exSimple attribute description |
exArrayElements |
array(string) |
1..10 |
exArrayElements attribute description |
exMapElements |
map(ExStructure) |
1..N |
exMapElements attribute description, indicating the values of the map key |
The data structure in table 5.2.9.3-1 is described in an OpenAPI file as follows:
components:
schemas:
ExampleStructuredType:
type: object
description: ExampleStructuredType data type description
required:
– exSimple
– exMapElements
properties:
exSimple:
$ref: ‘#/components/schemas/ExSimple’
exArrayElements:
type: array
items:
type: string
minItems: 1
maxItems: 10
description: exArrayElements attribute description
exMapElements:
type: object
additionalProperties:
$ref: ‘#/components/schemas/ExStructure’
minProperties: 1
description: exMapElements attribute description, indicating the values of the map key
NOTE 3: Object schema definitions should not have property names in the "required" attribute for which a corresponding property definition does not exist.
5.2.9.4 Info
The Open API specification file of an API shall contain an "info" field with the title and version as defined in clause 4.3 of 3GPP TS 29.501 [49].
5.2.9.5 Servers
As defined in clause 5.2.4, the base URI of an API consists of {apiRoot}/<apiName>/<apiVersion>. It shall be encoded in the corresponding Open API specification file as "servers" field with {apiRoot} as variable.
Example:
servers:
– url: ‘{apiRoot}/3gpp-yyyy/v1’
variables:
apiRoot:
default: https://demohost.com
description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.
5.2.9.6 References to other 3GPP-defined Open API specification files
For the purpose of referencing, it shall be assumed that each Open API specification file contained in a 3GPP specification is stored as separate physical file, that all Open API specification files are stored in the same directory on the local server, and that the files are named according to the following convention: The file name shall consist of (in the order below):
– the 3GPP specification number in the format "Tsxxyyy";
– an "_" character;
– if the OpenAPI specification file contains an API definition, the API name as defined for corresponding base URL parts (see clause 4.4) of that API.
– if the OpenAPI specification file contains a definition of CommonData, the string "CommonData"; and
– the string ".yaml".
Examples:
Reference to Data Type "Xxx" defined in the same file
$ref: ‘#/components/schemas/Xxx’
Reference to Data Type "Xxx" defined as Common Data in 3GPP TS 29.122:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/Xxx’
Reference to Data Type "Xxx" defined within API "Nxxx_Yyy" in 3GPP TS ab.cde:
$ref: ‘Tsabcde_Nxxx_Yyy.yaml#/components/schemas/Xxx’
5.2.9.7 Server-initiated communication
If an API contains notifications as described in clause 5.2.5, it should be described as "callback" in Open API specification files.
Example:
paths:
/subscriptions:
post:
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
callbackUrl: # Callback URL
type: string
format: uri
responses:
‘201’:
description: Success
callbacks:
myNotification: # arbitrary name
‘{$request.body#/callbackUrl}’: # refers The callback URL in the POST
post:
requestBody: # Contents of the callback message
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/NotificationBody’
responses: # Expected responses to the callback message
‘200’:
description: xxx
5.2.9.8 Describing the body of HTTP PATCH requests
5.2.9.8.1 General
As described in clause 5.2.2.2, the bodies of HTTP PATCH requests either use a "JSON Merge Patch" encoding as defined in IETF RFC 7396 [39], or a "JSON Patch" encoding as defined in IETF RFC 6902 [67].
It is possible to allow both encodings in an OpenAPI Specification [27] offering both schemas as alternative contents.
5.2.9.8.2 JSON Merge Patch
In the OpenAPI file, the content field key of the Request Body Object shall contain "application/merge-patch+json". The content field value is a Media Type Object identifying the applicable patch body Schema Object. The patch body Schema Object may contain structured data types derived from the data types used in the schema to describe a complete representation of the resource in such a manner that attributes that are allowed to be modified are listed in the "properties" validation keyword.
NOTE 1: A derived structured data type is beneficial if the data types used to describe a complete representation of the resource contains mandatory attributes, if attributes are allowed to be removed by the PATCH operation, or if a checking by the OpenAPI tooling that only allowed modifications are done via the "additionalProperties: false" keyword is desired. It also provides a clear description in the OpenAPI file to developers which modifications need to be supported.
As an alternative, the data types used in the schema to describe a complete representation of the resource may be used if any attributes that are allowed to be removed are marked as "nullable: true" in that schema.
Any attributes that are allowed to be removed shall be marked as "nullable: true" in the patch body Schema Object.
The "additionalProperties: false" keyword may be set.
NOTE 2: The "additionalProperties: false" keyword enables the OpenAPI tooling to check that only allowed modifications are done. Extensions of the object in future releases are still possible under the assumption that the supported features mechanism is used to negotiate the usage of any new attribute prior to the PATCH invocation. If new optional attributes are expected to be introduced without corresponding supported feature or if PATCH can be used as first operation in an API, the usage of the "additionalProperties: false" keyword is not appropriate.
5.2.9.8.3 JSON PATCH
In the OpenAPI file, the content field key of the Request Body Object shall contain "application/json-patch+json". The content field value is a Media Type Object identifying the applicable patch body. It may contain a mutually exclusive list (using the "oneOf" keyword) of all allowed modifications as <path, op, value> tuples, where "path" is a string containing a JSON Pointer value referring to a JSON object that is allowed to be modified, "op" is an enumeration of allowed JSON PATCH operations on the JSON object identified by "path" and "value" representing the schema/type of the value that will be updated or added at the JSON object identified by "path". In addition, an open alternative containing an object with no properties may be added using the "anyOf" keyword.
NOTE 1: A mutually exclusive list provides a clear description in the OpenAPI specification file to developers which modifications need to be supported. This is of particular interest if only a limited number of modifications need to be supported. If no open alternative is included, the OpenAPI tooling will also check that only allowed modifications are done.
NOTE 2: The open alternative allows for extensions of the PATCH in scenarios where new optional attributes are expected to be introduced without corresponding supported feature or if PATCH can be used as first operation in an API.
5.2.9.9 Error Responses
As described in clause 5.2.6, T8 APIs use valid HTTP response codes as error codes in HTTP responses and may include a "ProblemDetails" data structure specified in clause 5.2.1.2.12 or an application-specific data structure.
Clause 5.2.6 specifies HTTP status code per HTTP method. OpenAPI files should include at least the status codes in that table.
For the purpose of referencing, HTTP error responses with "ProblemDetails" data structure are specified as part of the CommonData OpenAPI file in Annex A.2.
Example:
In the example below, the 400, and 500 and default error response descriptions are referenced.
Paths:
/users:
get:
responses:
‘200’:
content:
application/json
schema:
$ref: ‘#/components/schemas/ExampleGetBody’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
The following definitions provided in Annex A.2 are used in that example:
components:
responses:
‘400’:
description: Bad request
content:
application/problem+json:
schema:
$ref: ‘#/components/schemas/ProblemDetails’
‘500’:
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: ‘#/components/schemas/ProblemDetails’
default:
description: Generic Error
5.2.9.10 Enumerations
For enumerations, the OpenAPI file shall contain a definition in the components/schemas section defining a schema with the name of the enumeration as key.
The naming conventions defined in clause 5.1.4 of 3GPP TS 29.501 [49] shall apply.
The schema:
– shall contain the "anyOf" keyword listing as alternatives:
1. the "type: string" keyword and the "enum" keyword with a list of all defined values for the enumeration; and
2. the "type: string" keyword and the "description" keyword with a description stating that the string is only provided for extensibility and is not used to encode contents defined in the present version of the specification, and
– may contain a description listing the defined values of the enumeration together with explanations of those values.
NOTE: The "enum" keyword restricts the permissible values of the string to the enumerated ones. This can lead to extensibility problems when new values need to be introduced.
Example:
Table 5.2.9.10-1: Enumeration ExampleEnumeration
Enumeration value |
Description |
Applicability |
ONE |
Value ONE description |
|
TWO |
Value TWO description |
The data structure in table 5.2.9.10-1 is described in an OpenAPI file as follows:
components:
schemas:
ExampleEnumeration:
anyOf:
– type: string
enum:
– ONE
– TWO
– 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:
– ONE: Value ONE description
– TWO: Value TWO description
5.2.9.11 Read only attribute
Each OpenAPI specification should include "readOnly: true" for those attributes that are only provided by the SCEF in the HTTP response message to prevent the SCS/AS from provisioning those attributes which is not expected, if the write and read operations (e.g. POST request and response) share the same data type which contains those attributes.
Example:
NiddStatus:
anyOf:
– type: string
enum:
– ACTIVE
– TERMINATED_UE_NOT_AUTHORIZED
– TERMINATED
– type: string
description: >
This string provides forward-compatibility with future
extensions to the enumeration but is not used to encode
content defined in the present version of this API.
Description: >
Possible values are
– ACTIVE: The NIDD configuration is active.
– TERMINATED_UE_NOT_AUTHORIZED: The NIDD configuration was terminated because the UE´s authorisation was revoked.
– TERMINATED: The NIDD configuration was terminated.
readOnly: true
5.2.9.12 externalDocs
Each OpenAPI specification shall provide in an "externalDoc" field the reference to the 3GPP TS describing the API, as illustrated below.
Example:
externalDocs
description: 3GPP TS 29.122 V15.1.0 T8 reference point for Northbound APIs
url: http://www.3gpp.org/ftp/Specs/archive/29_series/29.122/
5.2.9.13 Operation identifiers
Service operations defined in an OpenAPI specification file should be assigned an Operation ID.
EXAMPLE:
get:
operationId: ReadInfo
summary: Read Information.
tags:
– Information (Document)
parameters:
– name: infoType
in: path
description: Requested information Type
required: true
schema:
type: string
(…)
5.2.9.14 Usage of the "tags" field
In an OpenAPI specification, all HTTP operations belonging to the same resource should include a "tags" field containing a same value, briefly describing that resource (e.g. using the name of the resource and its archetype). This results in all operations being grouped by the User Interface of OpenAPI tools, which helps with readability of the API documentation.
EXAMPLE:
openapi: 3.0.0
(…)
paths:
/subscriptions/{subscriptionId}:
get:
summary: Retrieve an existing Individual subscription resource.
operationId: GetIndSubsc
tags:
– Individual Subscription (Document)
(…)
put:
summary: Request the update of an existing Individual Subscription resource.
operationId: UpdateIndSubsc
tags:
– Individual Subscription (Document)
(…)
patch:
summary: Request the modification of an existing Individual Subscription resource.
operationId: ModifyIndSubsc
tags:
– Individual Subscription (Document)
(…)
5.2.10 Redirection handling
An HTTP request may be redirected to a different target entity.
Upon receipt of an HTTP request from the SCS/AS, when the SCEF redirects the HTTP request to a different target SCEF, the URI of the target SCEF towards which the request is redirected shall be given by the Location header field of the "307 Temporary Redirect" or "308 Permanent Redirect" response. The SCS/AS should then send the HTTP request towards the new target SCEF.
Upon receipt of a notification/callback request from the SCEF, when the SCS/AS redirects the notification/callback request to a different target SCS/AS, the URI of the target SCS/AS towards which the notification/callback request is redirected shall be given by the Location header field of the "307 Temporary Redirect" or "308 Permanent Redirect" response. The SCEF should then send the HTTP request towards the new target SCS/AS.
5.2.11 Support of Load and Overload Control
The Load Control mechanisms defined in clause 6.3 of 3GPP TS 29.500 [44] may be supported by T8 APIs with the following differences:
– The "Load Control based on load signalled via the NRF" mechanism defined in clause 6.3.2 of 3GPP TS 29.500 [44] shall not be supported; and
– The "Load Control based on LCI Header" mechanism defined in clause 6.3.3 of 3GPP TS 29.500 [44] may be supported with the following differences:
– The Load Control "scope" and all the related provisions are not applicable;
– The "NF Service Consumer" corresponds to the sending entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs and the "NF Service Producer" corresponds to the receiving entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs;
– The provisions related to the SCP (Service Communication Proxy) and SEPP (Security Edge Protection Proxy) entities are not applicable; and
– The "3gpp-Sbi-Lci" custom HTTP header corresponds to the "Nbi-Api-Lci" custom HTTP header defined in clause 5.2.8.3.4 for T8 APIs.
– The provisions and mechanisms using the NRF (i.e. 5GC NF Repository Function) are not applicable.
The Overload Control mechanisms defined in clause 6.4 of 3GPP TS 29.500 [44] may be supported by T8 APIs with the following differences:
– The "Overload Control based on HTTP status codes" mechanism defined in clause 6.4.2 of 3GPP TS 29.500 [44] may be supported with the following differences:
– The "NF Service Consumer" corresponds to the sending entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs and the "NF Service Producer" corresponds to the receiving entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs;
and
– The "Overload Control based on OCI Header" mechanism defined in clause 6.4.3 of 3GPP TS 29.500 [44] may be supported with the following differences:
– The Overload Control "scope" and all the related provisions are not applicable;
– The "NF Service Consumer" corresponds to the sending entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs and the "NF Service Producer" corresponds to the receiving entity (e.g. SCEF, SCS/AS, AF) of the message in T8 APIs;
– The provisions related to the SCP (Service Communication Proxy) and SEPP (Security Edge Protection Proxy) entities are not applicable; and
– The "3gpp-Sbi-Oci" custom HTTP header corresponds to the "Nbi-Api-Oci" custom HTTP header defined in clause 5.2.8.3.5 for T8 APIs.
– The provisions and mechanisms using the NRF (i.e. 5GC NF Repository Function) are not applicable.
Editor’s Note: How the support of these mechanisms is exchanged between the concerned entities is FFS.
Editor’s Note: How reslection is performed is FFS.
5.2.12 Query parameters
The query component in a URI contains non-hierarchical data that, along with data in the path component, enables to filter the resources identified within the scope of the URI’s scheme to a subset of the resources matching the query parameters. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI. The syntax of the query component is specified in IETF RFC 3986 [7].
When a server receives a request with a query component, it shall parse the query string in order to identify the filters. The first question mark is used to be a separator and is not part of the query string. A query string is composed of a series of "key=value" pairs, separated by "&". If one query parameter contains more than one value, i.e. an array of data elements, then the values shall be separated by comma (",").
The behaviour of the server when receiving an HTTP/2 method with a query parameter which is of type array, and only some of the members in the array can be matched, depends on each API and the behaviour shall be clearly described.
When multiple query parameters are defined for a method on the resource, the logical ‘AND’ is the default logical relationship between the query parameters for this resource. If a different logical relationship between multiple query parameters is specified for a method on a resource in an API, then this logical relationship override the default logical relationship for this specific method on the concerned resource in that API. If multiple query parameters are defined for a method on a resource in an API, but there is no need to specify any logical relationship between these query parameters, the concerned API shall explicitly state how to handle multiple query parameters.