Schemas and Transformation

Module 5 of 6 in the chapter APIs, Contracts and Data Across the Wire, chapter 3 of the Integration Architect course. Each module stands on its own. Previous: Formats, Old to New · Next: AI in the Work

The question this module answers: How do two systems agree on the shape of data, check it, and turn one system’s shape into the other’s?

Remember the transporter. Steve Trucking sent a delivery, and Redrock rebuilt it as a shipment, with different names and a different shape. Two questions came out of that. How does each side know the data is the shape it expects? And who turns one shape into the other, and where?

The first is a schema. The second is transformation, done with a mapping.

A Schema Is the Shape, Written Down

In the contract, you met the schemas inside an OpenAPI file: a delivery has an id, a status, a recipient, a list of items. That’s a schema. It’s the shape of the data, written down, so both sides can read it and a machine can check it.

Why do you need it, when the payload is right there? Because a payload only tells you what’s there. It doesn’t tell you what should be there, or what’s missing. Here’s a delivery that arrives with only two fields:

{ "id": "D-1043", "status": "In transit" }

Is that a whole delivery, or is the weight missing? Is a recipient required? Could the status have been anything at all? The payload can’t say. The schema can, because it holds the rules for what’s expected.

And that’s on purpose. We want to send the minimal amount across the wire: that’s efficient serialization. The less that travels, the more the other side needs to know already, to rebuild it into something it can use. The schema is what it knows. It’s the shape, so the stream can be deserialized and mapped into a structure, instead of being read as raw text. Binary Avro, from module 4, takes this furthest: it doesn’t send the field names at all, because both sides have the schema.

Every format has its own way to write one:

• For JSON, JSON Schema. Its current version is 2020-12 (JSON Schema (opens in a new tab), checked 2026-11-01). The schemas in an OpenAPI file are written in it.
• For XML, XSD, the XML Schema Definition Language (XSD 1.1 (opens in a new tab), W3C).
• For binary Avro, the Avro schema, which both sides need before the bytes mean anything (module 4).

Here’s part of Steve Trucking’s delivery in JSON Schema:

{
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "id": { "type": "string", "maxLength": 20 },
    "status": { "type": "string", "enum": ["Planned", "In transit", "Delivered"] },
    "weightKg": { "type": "number", "minimum": 0 },
    "deliveredAt": { "type": "string", "format": "date-time" }
  }
}

Read it like the five questions. It’s an object. It must have an id and a status. The id is text, up to 20 characters. The status can only be one of three values. The weight is a number, never below zero. And the delivery time is text in a date and time format.

Checking Against the Schema

In the client–server tango, the server examines the payload and makes sure it’s a valid request. A schema is how it checks. The client can do the same with what comes back.

A schema is good at catching the wrong shape: a missing id, text where a number should be, a status that isn’t on the list, a date that isn’t a date, a name too long for the field. Catch those at the door, and the error goes back to the client as a 400, with a message it can act on, instead of failing somewhere deep inside.

But a schema can’t catch the right shape with the wrong meaning. A real time in the wrong time zone passes. A weight in pounds where the contract says kilograms passes: it’s still a number above zero. A valid id for the wrong delivery passes. That’s the transporter dropping atoms from module 3, and no schema will see it.

Click to enlarge

What a schema catches, and what it can’t.

So check the shape with a schema, and check the meaning with the contract: which units, which time zone, which id is which. And when it matters, with people.

Two Shapes, One Delivery

Now the second question. Two systems almost never shape the same thing the same way.

Here’s the example I use in class. You send data out of Salesforce, and it’s called an account. In the ERP, it’s called a customer. And Salesforce has one billing address and one shipping address, as fields on the account. The ERP might have an address table instead: a list of addresses, each with a type. Same customer, two shapes. Something has to turn one into the other. That’s a data transformation.

The rules for that are a mapping: for each field on one side, where it goes on the other, and what happens to it on the way. Most rules are one of four kinds:

• Rename. The same value under a different name: id becomes shipmentId.
• Convert. The same meaning written differently: Delivered becomes DELIVERED; a time moves to another time zone; kilograms become pounds.
• Reshape. A different structure: a recipient’s name becomes a consignee object; two address fields become one entry in a list of stops.
• Look up. A value that means something different on each side: Steve Trucking’s depot North is Redrock’s depot code N01, found in a table both sides agree on.

Click to enlarge

Two shapes, one delivery. A mapping is a list of rules, one field at a time.

Sometimes the change isn’t the data at all, but the protocol: Salesforce sends REST, and the other system only takes SOAP, or a file. That’s a protocol transformation, and it’s another reason a mapping might sit in the middle.

For XML, there’s a standard language just for transformation: XSLT, which takes one XML document and writes another (XSLT 3.0 (opens in a new tab), W3C). You’ll meet it in older integrations and in some middleware. XSD describes the shape; XSLT changes it.

Where the Mapping Lives

So who does the transforming? There are three places, and each one decides who owns the mapping.

On your side, in Salesforce. There’s a whole ladder here, from no code to code:

• Flow. Create an HTTP callout, paste in some sample JSON, and Flow creates the structures and the mappings for you. That’s the superpower. But it can’t handle advanced, complicated schemas, and then you’ll still need Apex. Chapter 4 shows it.
• External Services. Bring in the OpenAPI file from the contract, and Salesforce builds the actions and their shapes from it. If the other side hosts the file, you can refresh it when it changes; if you uploaded a copy, you have to notice the change yourself.
• Apex. An Apex class that matches the payload exactly, and one line to deserialize it. With small, static, standard payloads, that’s beautiful: you can knock an integration out in no time. When the payload doesn’t fit a class, a parser that walks it piece by piece.
• Custom metadata. At one client, the payload kept changing, iteration after iteration. So I moved the mapping into custom metadata: which field in the payload goes to which field on the record. Then a mapping could change in production without changing code. That’s the far end of the ladder, the most complex, but it gives you the most flexibility.
• DataWeave in Apex. MuleSoft’s transformation language, run inside Salesforce: it reads data in one format, transforms it, and writes it in another, under the same limits as Apex. Salesforce documents it in the current Apex Developer Guide, and says you don’t need to be a MuleSoft customer to use it. One of its listed uses is JSON with field names that are reserved words in Apex, exactly the problem that breaks a one-line deserialize (DataWeave in Apex (opens in a new tab), Apex Developer Guide, Winter ‘27, checked 2026-11-01).

In the middle, in middleware. With many systems, the mapping can live in one place, between them all: data and protocol transformations both, with their own team and tools. That’s one of the strongest reasons for middleware, and chapter 5 does the math on how fast point-to-point grows.

On their side. The other system maps your shape to its own. That’s your shape and their work, on their release schedule. It works well when you own the contract and they agreed to follow it.

Click to enlarge

Where the mapping lives. Each place decides who owns it.

There’s no single right answer. But there is a wrong one: a mapping nobody owns. Every rule in a mapping is a decision, and when one side changes a field, somebody has to change the rule. That’s the boundary from Owners, Boundaries and Change again. Wherever the mapping lives, write down who owns it.

What an Architect Decides Here

• For every interface, where the schema lives, and whether the server checks what comes in against it.
• What the schema can’t check, and where the contract says it: units, time zones, which id is which.
• The mapping, field by field: rename, convert, reshape or look up, and the lookup tables both sides agree on.
• Where the mapping lives: on your side, in the middle, or on theirs, and who owns it.
• On Salesforce, which rung of the ladder: Flow, External Services, Apex, custom metadata, or DataWeave in Apex, for how often the payload changes and how complex it is.

Beyond the exam: what AI changes. Give AI two sample payloads, one from each side, and it will draft the whole mapping in seconds, and a schema for each. That’s real work saved. But a mapping is full of decisions AI can only guess at: is that weight in kilograms or pounds, is North the same depot as N01? Ask it to mark every rule it guessed, and check each one with the people who own the data. Module 6 does this on a real payload.

Explore

• JSON Schema (opens in a new tab) (2020-12); W3C, XSD 1.1 (opens in a new tab) and XSLT 3.0 (opens in a new tab).
• Salesforce Developers, DataWeave in Apex (opens in a new tab), Apex Developer Guide, checked 2026-11-01.
• The next module, AI in the Work: a sample payload, a spec drafted by AI, and a person checking it.