Using Dyalog’s ⎕JSON for Reliable Data Interchange

Problem: exchanging data without external dependencies

When a Dyalog APL application needs to talk to a REST service, read a configuration file, or store state, developers often reach for third‑party JSON libraries or write custom parsers. Those approaches add installation steps, version‑matching concerns, and potential bugs. Dyalog provides a built‑in alternative that works out of the box.

Thesis: ⎕JSON gives a simple, version‑safe way to round‑trip APL arrays to JSON text

Starting with Dyalog version 14.0 (both Classic and Unicode editions), the system function ⎕JSON encodes any APL array into a UTF‑8 JSON string and decodes valid JSON back into an APL array. It handles numbers, strings, booleans, nulls, and nested structures without extra code.

Basic usage example

Assume you want to send a table of user records to a web service. In a Dyalog session you can:

1. Create the APL data (a nested vector of vectors).
2. Encode it with ⎕JSON.
3. Send the resulting string (e.g., via ⎕HTTP or a socket).
4. On the receiving side, decode with ⎕JSON to recover the original APL array.

The following code shows the encode‑decode round‑trip. Run it in a Dyalog session (no special permissions required).

⍝ Sample data: a 2‑row table with name and age
data ← 2 2⍴'name' 'age' ; 'Alice' 30 ; 'Bob' 25
⍝ Encode to JSON
json ← ⎕JSON data
⍝ json now holds a character vector, e.g.: "[{"name":"Alice","age":30},{"name":"Bob","age":25}]"
⍝ Decode back
back ← ⎕JSON json
⍝ Verify equality – should return 1 (true)
⎕≡ data back

If you are reading JSON from a file, replace the literal assignment with ⎕NGET:

raw ← ⎕NGET 'users.json'  ⍝ read file as raw bytes
jsonTxt ← ⎕UCS 8 ⎕DR raw   ⍝ convert UTF‑8 bytes to character vector
back ← ⎕JSON jsonTxt

Error handling and performance considerations

⎕JSON signals a DOMAIN ERROR when the input is not valid JSON. Wrap calls in a :Try/:Catch block to keep the application running:

:Try
    result ← ⎕JSON userInput
:Catch e
    ⎕← 'Invalid JSON received: ', e
:EndTry

For typical payloads (a few kilobytes) the throughput of ⎕JSON matches hand‑written parsers. Very large documents (tens of megabytes) may show noticeable overhead because APL copies the entire array during encoding/decoding. If you anticipate such sizes, consider streaming the data or compressing it before transmission.

Limitations and how to verify the result

⎕JSON only preserves plain data. APL‑specific metadata such as namespaces, class instances, or function attributes are lost; the round‑trip yields a plain array of numbers, strings, booleans, and nulls. To confirm that your data survived intact:

1. Encode your original APL variable.
2. Decode the JSON string.
3. Compare the original and the decoded variable with ⎕≡ (deep equality). A result of 1 means they are identical.

This check works for any nesting depth and is the recommended verification step after each encode/decode pair.

Actionable closing

If you are building a Dyalog APL component that needs to exchange JSON:

• Ensure you are on Dyalog 14.0 or later.
• Use ⎕JSON for both encoding and decoding.
• Guard the calls with :Try/:Catch to handle malformed input.
• Validate the round‑trip with ⎕≡ in unit tests or during development.
• Monitor payload size; for very large JSON consider alternative strategies.

By relying on the built‑in ⎕JSON you remove external dependencies, simplify deployment, and gain a reliable, standards‑compliant JSON path for your APL applications.