JSON in SAP Integration

JSON stands for JavaScript Object Notation. It is a lightweight, text-based format for storing and exchanging data. JSON uses curly braces and square brackets to structure data, making it very readable for humans and easy for machines to parse.

JSON has become the default format for modern REST APIs, including the OData APIs that SAP S/4HANA exposes. As SAP shifts towards cloud and API-first architecture, JSON appears more and more in integration scenarios alongside — and sometimes instead of — the traditional XML format.

JSON vs XML: The Same Data Compared

Here is the same purchase order from the previous topic, written in JSON instead of XML:

{
  "PurchaseOrder": {
    "OrderNumber": "PO-12345",
    "Supplier": "ABC Supplies Ltd",
    "OrderDate": "2024-05-01",
    "LineItems": [
      {
        "Material": "Steel Rod 10mm",
        "Quantity": 500,
        "Unit": "KG",
        "Price": 2.50
      },
      {
        "Material": "Bolt M12",
        "Quantity": 1000,
        "Unit": "EA",
        "Price": 0.15
      }
    ]
  }
}

Compare this to the XML version. JSON has no opening/closing tags, which means less text for the same data — smaller messages, faster transmission. The square brackets [ ] represent arrays (lists), and curly braces { } represent objects (grouped data). Numbers do not need quotes; strings do.

JSON Data Types

JSON supports six data types:

• String – Text in double quotes: "Hello World"
• Number – Integer or decimal: 42, 3.14
• Boolean – True or false: true, false
• Null – No value: null
• Object – Key-value pairs inside { }: { "name": "John" }
• Array – Ordered list inside [ ]: ["red", "green", "blue"]

JSONPath: Navigating JSON

Just as XPath navigates XML, JSONPath navigates JSON. In CPI, you use JSONPath expressions in routing conditions and content modifiers to extract values from JSON payloads.

JSON:
{
  "order": {
    "id": "ORD-999",
    "status": "Approved",
    "items": [
      { "sku": "A001", "qty": 10 },
      { "sku": "B002", "qty": 5 }
    ]
  }
}

JSONPath expressions:
$.order.id               → "ORD-999"
$.order.status           → "Approved"
$.order.items[0].sku     → "A001"  (first item)
$.order.items[*].qty     → [10, 5] (all quantities)
$.order.items.length()   → 2

The dollar sign ($) represents the root of the JSON document. Dots navigate into nested objects. Square brackets with an index access array elements. The asterisk (*) matches all elements in an array.

JSON in SAP S/4HANA OData APIs

SAP S/4HANA exposes its business data through OData APIs. These APIs return JSON by default (though they also support XML when requested). When you call an S/4HANA OData API from CPI, you typically work with JSON responses like this:

OData response for a sales order query:
{
  "d": {
    "results": [
      {
        "SalesOrder": "100001",
        "SoldToParty": "CUST-001",
        "SalesOrderType": "OR",
        "NetAmount": "15000.00",
        "TransactionCurrency": "USD",
        "to_Item": {
          "results": [
            {
              "SalesOrderItem": "10",
              "Material": "MAT-X100",
              "OrderQuantity": "50.000"
            }
          ]
        }
      }
    ]
  }
}

Notice the "d" and "results" wrapper — this is the OData v2 response envelope. OData v4 uses a different structure ("@odata.context", "value" array). When you map OData responses in CPI, you must account for these envelope structures to reach the actual business data.

Converting Between JSON and XML in CPI

CPI processes messages in XML internally. When a message arrives in JSON format, CPI can automatically convert it to XML for processing. When the result needs to go out as JSON, CPI converts back.

Incoming JSON → [JSON to XML Converter] → XML processed in iFlow
                                              ↓
Outgoing JSON ← [XML to JSON Converter] ← XML result

CPI provides built-in JSON to XML Converter and XML to JSON Converter steps. You drag them into your iFlow at the appropriate points. The conversion is automatic — you configure whether to use a specific namespace and how to handle JSON arrays, and CPI does the rest.

Handling JSON Arrays in Mappings

JSON arrays present a special challenge in mappings. An order with five line items contains a JSON array with five objects. When mapping this to an SAP IDoc or SOAP request, each array element must become a separate IDoc segment or SOAP line item element.

CPI handles arrays through the loop concept in message mapping. You map the array element once, and the mapping engine repeats it for every element in the source array. This is one of the most important concepts in JSON-to-SAP mapping and receives detailed coverage in the message mapping topic.

JSON Schema

Just as XSD validates XML structure, JSON Schema validates JSON structure. A JSON Schema document defines which fields are required, what type each field must be, and what values are allowed.

JSON Schema snippet:
{
  "type": "object",
  "required": ["OrderNumber", "Supplier"],
  "properties": {
    "OrderNumber": { "type": "string" },
    "Supplier":    { "type": "string" },
    "Quantity":    { "type": "integer", "minimum": 1 }
  }
}

Valid message:                   Invalid message:
{                                {
  "OrderNumber": "PO-001",         "Supplier": "ABC Ltd",
  "Supplier": "ABC Ltd",           "Quantity": -5     ← negative
  "Quantity": 10                 }
}                                Missing OrderNumber ← required

In CPI, you can attach JSON Schemas to message endpoints for automatic validation. Messages that fail schema validation get rejected with a clear error before any business processing occurs, preventing bad data from reaching SAP.

Common JSON Integration Patterns in SAP

• REST API to SAP – External system sends JSON via REST, CPI converts to XML/IDoc and posts to SAP
• SAP OData to External – CPI calls SAP OData API, receives JSON response, transforms and delivers to target
• Webhook Processing – External app (Shopify, Salesforce) sends JSON webhook, CPI receives and routes to SAP
• API Response Enrichment – CPI calls SAP for customer data (JSON), merges with incoming order (JSON), sends combined result downstream