Treat every API response as untrusted until its status, type, size, and schema are validated. Transform it into a small internal contract instead of passing a vendor payload through the whole workflow.
Define the Internal Schema
Vendor input:
{
"data": [{ "id": "A14", "attributes": { "price": "2490.00", "active": true } }],
"next": null
}
Internal output:
{
"product_ref": "A14",
"price_minor_pkr": 249000,
"availability": "ACTIVE",
"source_version": "vendor-v1"
}
Validate required fields and allowed values. Convert money with decimal-safe logic and explicit unit; do not use casual floating-point arithmetic. Preserve provenance and timestamps.
Use the Clearest Node
Use expressions or Edit Fields for simple mapping. Use Code for multi-field validation/transformation when native nodes become less clear, but keep code small, tested, and free of secrets/network calls. For complex domain validation, call a versioned service rather than duplicating logic in many workflows.
Handle missing versus null versus empty distinctly. Cap arrays and nesting. Quarantine unknown schema versions instead of guessing.
Keep transformation fixtures in version control with expected internal output. When the upstream API version changes, diff the real authorized sample against the recorded schema, update the adapter, and rerun every downstream consumer test before activation. This isolates vendor changes at one boundary instead of spreading conditional expressions throughout the workflow.
Worked Example
An order API returns 25 records. The workflow validates each ID, status, currency, and total, then emits VALID, INVALID, or REVIEW. One record has currency USD while the workflow expects PKR; it does not convert silently. Another lacks ID and stops from downstream processing.
The output retains order reference and source response version, but drops internal notes and customer fields that the next stage does not require.
Failure Cases to Diagnose
- Optional chaining hides required absence: validate explicitly.
- String amount parsed loosely: use exact decimal rules.
- Unknown enum mapped to closest status: route REVIEW.
- Entire payload carried forward: select minimum fields.
- Model transforms financial JSON: use deterministic schemas/code.
- Array size explodes memory: enforce caps and pagination.
🇵🇰 Pakistan Angle
Always validate currency before displaying PKR. A value 2490 may mean rupees or minor units depending on the provider; document the contract. Do not convert exchange rates without a dated authoritative source and business approval.
Redact CNIC, phone, address, bank, and private note fields unless the next authorized step needs them. Analytics can usually use internal references rather than identity data.
Hands-On Exercise
- Save three synthetic API fixtures.
- define the internal schema.
- transform with native nodes or small tested code.
- test missing/null/unknown/currency/large-array cases.
- inspect final output for unnecessary fields.
Completion Rubric
- Status/type/size/schema are checked.
- Internal contract is minimal and versioned.
- Money/currency transformations are exact.
- Unknown data routes safely.
- Provenance survives transformation.
- Sensitive fields are removed.
Sources
Key takeaway: transform external JSON into a small, validated, versioned internal schema and make unknown, financial, and private fields fail visibly.