Serialize Dyalog APL Namespaces with ⎕JSON at Integration Boundaries

The problem: serialization leaks into business logic

You have a Dyalog APL namespace holding customer data, configuration, or calculation results. A downstream service expects JSON. It is tempting to call ⎕JSON wherever the data is prepared, then pass the text around. That couples your business logic to a wire format and hides type loss until a consumer complains a field is missing or a number arrived as text.

What ⎕JSON does at the boundary

⎕JSON is Dyalog APL's built-in system function for converting between APL arrays and JSON text. JSON objects map to APL namespaces, JSON arrays map to vectors, and JSON scalars map to APL numbers or character vectors. Options control formatting and whether type information is emitted as tags. The sound engineering pattern is to keep this conversion in one place: the integration layer that emits HTTP responses, writes files, or calls external services.

Where to run the example

Run the following in a Dyalog APL session. No special operating-system permissions are required; the session only needs to start and evaluate APL expressions. Replace placeholders with your own namespace names and field values.

⍝ Build a sample namespace at the integration boundary
payload ← ⎕NS ''
payload.customerId ← 12345
payload.name ← 'A. Example'
payload.scores ← 10 20 30
payload.active ← 1

⍝ Serialize to JSON text
jsonText ← ⎕JSON payload

⍝ Parse back into APL for a round-trip check
roundTrip ← ⎕JSON jsonText

After evaluating these lines, inspect jsonText and roundTrip in the session. Check that roundTrip.customerId is numeric, roundTrip.name is character, and ⍴roundTrip.scores matches ⍴payload.scores. If any field changed type or shape, the boundary contract needs an explicit conversion step before serialization.

Diagnostic decision: compare before and after

A practical check is to compare the original namespace with the parsed result field by field:

⍝ Example field-by-field check (adjust field names to your payload)
checks ← (payload.customerId = roundTrip.customerId)
checks ← checks , (payload.name ≡ roundTrip.name)
checks ← checks , ∧/ (payload.scores = roundTrip.scores)
checks ← checks , (payload.active = roundTrip.active)
∧/ checks

If the final expression does not return 1, do not assume the mismatch is harmless. Empty arrays, nested namespaces, and Boolean-like values are common failure points at integration boundaries.

Limitations and version assumptions

Round-trip fidelity is not universal. APL-specific values such as dates, locked namespaces, or objects encoded with ⎕OR may not survive serialization and parsing without explicit conversion. Behavior and available ⎕JSON options can differ between Dyalog releases, so code written for one version should be reviewed after an upgrade. Treat the options and type-tag behavior as version-dependent until you confirm them against your installed release.

Closing: confine ⎕JSON, verify the payload

Keep ⎕JSON out of core business logic. Serialize only when crossing into HTTP, files, or external services, and deserialize only at the receiving edge. Before deploying, run a round-trip test with a real sample payload from your target API and review the ⎕JSON section of the Dyalog documentation for your installed version.