Mapping JSON Messages to MDCs

SBA Gateway uses OpenAPI (Swagger) specifications to check the format of incoming JSON requests. After validation, these JSON messages are mapped to MATRIXX Data Container (MDC) structures using the Dynamic Message Mapper. This uses Mapping configuration files to map fields in the incoming JSON request to and from MDCs before sending them to and from MATRIXX Engine.

The OpenAPI specifications used are provided by 3GPP for the 5G core. These specification releases are asynchronous with MATRIXX releases, and MATRIXX releases support more than one OpenAPI specification and associated mapping per release.

OpenAPI Specification Support shows the supported versions and defaults:

Table 1. OpenAPI Specification Support
OpenAPI Specification	Supporting MATRIXX Versions
R15 March 2019	5120, 5121, 5122, 5123 (Default for those releases)
R15 December 2019	52xx, 5230 (default)
R16 September 2021	5240

OpenAPI Specification and Mapping Files shows the files for each 3GPP 5G version:

Table 2. OpenAPI Specification and Mapping Files
3GPP 5G Version	Specification Version Value	OpenAPI Specification Files	Mapping Configuration Files
R15 March 2019	R15-2019-03	/data/5GC/specs/R15-2019-03	/data/5GC/mappings/R15-2019-03
R15 December 2019	R15-2019-12	/data/5GC/specs/R15-2019-12	/data/5GC/mappings/R15-2019-12
R16 September 2021	R16-2021-09	/data/5GC/specs/R16-2021-09	/data/5GC/mappings/R16-2021-09

Use the gateway.specification property to specify which 3GPP Specification to use, where the property value indicates the folder name under the specs directory:

gateway:
  specifications:
    version: "R15-2019-12"

There must also be a corresponding sub-directory of the mapping directory.

You can edit mapping files and OpenAPI specifications to update or specify new MDC mappings. The new MDC mappings are loaded when SBA Gateway is restarted.

The following sections configure specifications and mapping. The following example shows a configuration that combines the common and CHF configurations in one file. The custom CHF nf.yaml file only overrides the specification names field and leaves the rest as default values.

# Message Specification Settings
gateway:
  specifications:
    version: "R15-2019-12"
    directory: /opt/mtx/conf/specs
    names: TS32291_Nchf_ConvergedCharging.yaml,TS29594_Nchf_SpendingLimitControl.yaml
 
  # Message Mapper Settings
  mapping:
    directory: /opt/mtx/conf/mappings
    trace: false

It is unlikely that you must change these properties (other than gateway.specifications.version and gateway.mapping.trace) unless you are implementing a new API or network function.

How Mapping Works

The following code excerpt from TS32291_Nchf_ConvergedCharging.yaml shows the POST /chargingdata API:

/chargingdata:
   post:
     requestBody:
       required: true
       content:
         application/json:
           schema:
             $ref: 'http://localhost:8080/rsgateway/data/json/openapi3/schema/ChargingDataRequest'
     responses:
       '201':
         description: Created
         content:
           application/json:
             schema:
               $ref: 'http://localhost:8080/rsgateway/data/json/openapi3/schema/ChargingDataResponse'

The CHF network function defines this URI in the endpoint configuration. When a request is received, it validates this request with the ChargingDataRequest schema. This schema is found by looking in the files listed in specifications.names. In this case, the definition of ChargingDataRequest is found in TS32291_Nchf_ConvergedCharging.yaml. If required, this file can be modified or replaced with a different version of the specification.

The ChargingDataRequest must be mapped to an MDC before sending to the engine, and the response MDC must be mapped to a ChargingDataResponse.

The following is an excerpt from the ChargingDataRequest mapping file:

source:
  type: "openapi"
  name: "ChargingDataRequest"
 
target:
  type: "mdc"
  name: "Mtx5GMsg"
 
validation:
  enabled: true
  outputIssuesToLog: true
  failOnIssue: false
 
fieldMappings:
  Mtx5GMsg:
    Request!Mtx5GChargingDataRequest:
      InvocationSequenceNumber: "ChargingDataRequest.invocationSequenceNumber"

The excerpt shows that the source type is expected to be ChargingDataRequest, the target is an Mtx5GMsg MDC, and validation is enabled. Disabling validation reduces CPU usage, but also allows messages that do not match the specification, which can cause issues, such as expected fields not being present.

The fieldMappings section maps each field in the ChargingDataRequest JSON, for example, ChargingDataRequest.invocationSequenceNumber, to the relevant field in the MDC (InvocationSequenceNumber).

For details about configuring mapping files, see the discussion about creating a mapping configuration in MATRIXX 5G Integration.

Further Mapping Information

For more information about configuring mapping files, see the discussion about creating a mapping configuration.

For a list of REST URIs and the associated mapping files for incoming messages, or for a list of MDCs and their associated mapping files for outgoing messages, see the discussion about APIs for 5G integration in MATRIXX 5G Integration.

MATRIXX Engine 5G Message Processing

When receiving messages from MATRIXX Engine, the Dynamic Message Mapper maps MDCs to JSON messages, which are then validated by SBA Gateway.

Note: The Charging Server removes request message data from the response that MATRIXX Engine sends to SBA Gateway. To persist request message data, you must apply selective updates to the response message at the Charging Server output interface. For information about selective updates, see the discussion about selective updates in MATRIXX Integration.