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.

// concept

Define the Internal Schema

Vendor input:

// json4 lines

{
  "data": [{ "id": "A14", "attributes": { "price": "2490.00", "active": true } }],
  "next": null
}

Internal output:

// json6 lines

{
  "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.

// concept

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

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

Failure Cases to Diagnose

6 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

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

Hands-On Exercise

5 steps

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

Completion Rubric

6 checks — tick as you verify

0/6

// sources

Sources

3 official sources — check every claim yourself

// check_yourself

Check yourself

4 questions · answers and options are taken word-for-word from this course

0/4

1 / 4 · diagnose
Your work shows this failure mode: “Model transforms financial JSON.” What does the lesson tell you to do about it?