What is JSON

What It Is

JSON (JavaScript Object Notation) is a text format for structured data exchange. It represents data as nested key-value pairs, arrays, and primitives. A JSON object is a map. A map has keys. Keys have values. Values are strings, numbers, booleans, null, arrays, or other maps. Nothing else. JSON is not a programming language. It is not a database. It is a contract written in plain text that any system can read, write, and validate without negotiation.

Why It Matters

Data moves. Systems talk. JSON is the lingua franca because it is unambiguous, inspectable, and stateless. No hidden schemas. No binary black boxes. A human can read it. A machine can parse it. An auditor can diff it. In an open protocol, this is not a convenience. It is a requirement. If you cannot read the payload, you cannot verify the action. If you cannot verify the action, you cannot audit the system. JSON makes the invisible visible.

How It Works

JSON has six types. Six. No more.

1. Object: {} — a map of string keys to values.
2. Array: [] — an ordered list of values.
3. String: "text" — UTF-8 text, always quoted.
4. Number: 42 or 3.14 — no quotes. Integer or float.
5. Boolean: true or false — lowercase. No quotes.
6. Null: null — the absence of value.

A key-value pair looks like this: "key": "value". Keys are always strings. Values are any of the six types. Arrays hold values in order. Objects hold keys without order. Nesting is free. An array of objects is normal. An object containing arrays is normal.

Parsing is deterministic. "42" is a string. 42 is a number. true is boolean. "true" is a string. These are not the same. JSON parsers enforce this. There is no silent coercion. There is no guesswork. The parser reads the token and returns the type. What you see is what you get.

The Contract

The JSON contract is explicit and unforgiving:

• Keys must be double-quoted strings. Single quotes are invalid.
• Trailing commas are forbidden. "a": 1, at the end of an object is a syntax error.
• Comments are forbidden. No //, no / /.
• Numbers are base-10. No hex. No octal. No Infinity. No NaN.
• Strings are UTF-8. Escape sequences are limited: \n, \\, \", \t, \b, \f, \r, \uXXXX.
• Whitespace outside of strings is ignored.

This rigidity is the feature. A strict contract means every parser produces the same structure from the same text. No vendor lock-in. No version skew. No "it works on my machine." The contract is the guarantee.

Real Examples

Example 1: A directory row in OIP

{
  "key": "LEDGER_READ",
  "type": "query",
  "target": "D1",
  "args": ["$1"],
  "description": "Read a single ledger row by ID"
}

This is a capability declaration. A machine reads it. A human audits it. The key is the handle. The type is the verb. The target is the system. The args are the contract. No ambiguity. No hidden state.

Example 2: An API dispatch envelope

{
  "key": "LEDGER_READ",
  "body": "inv_abc123"
}

This is an invocation. The key names the capability. The body carries the payload. The router receives this, looks up the row, and executes. The entire transaction is serializable, loggable, and replayable because it is JSON.

Example 3: A ledger receipt

{
  "request": { "key": "LEDGER_READ", "body": "inv_abc123" },
  "response": { "status": 200, "result": { "id": "inv_abc123", "actor": "router" } },
  "actor": "router",
  "ts": "2026-07-05T14:00:00Z",
  "trace_id": "t_xyz789"
}

This is proof. It records what was asked, what was returned, who did it, and when. An auditor can read this file and reconstruct the entire chain of events. No database required. No proprietary format. Just JSON.

Example 4: Configuration

{
  "build_version": "1.4.2",
  "features": ["dispatch", "ledger", "selftest"],
  "enabled": true,
  "metadata": null
}

Configuration as JSON means any tool can read it. Any editor can validate it. Any diff can show what changed. This is infrastructure as readable text.

Example 5: A batch of objects

[
  { "key": "ARTICLE_READ", "slug": "oip-what-is-json" },
  { "key": "ARTICLE_READ", "slug": "oip-what-is-oip" },
  { "key": "ARTICLE_READ", "slug": "oip-what-is-the-ledger" }
]

Batch operations in JSON are arrays of objects. Each object is self-contained. The array is ordered. This is how you process multiple items in one pass while keeping every item inspectable.

Common Mistakes

• Using single quotes for strings. JSON only accepts double quotes. 'key': 'value' is invalid. Every parser rejects it.
• Trailing commas. "a": 1, is fine inside an object. "a": 1,} is not. The last pair cannot have a trailing comma.
• Comments. JSON has no comments. Preprocessors strip them, but standard parsers do not. If you need comments, use a separate documentation field.
• Unquoted keys. { key: "value" } is invalid. Keys must be quoted: { "key": "value" }.
• Number precision. JSON numbers are IEEE 754 doubles. Integers above 2^53 lose precision. If you need exact large integers, store them as strings.
• Date confusion. JSON has no date type. Dates are strings. Choose ISO 8601 ("2026-07-05T14:00:00Z") and stick to it. Do not mix formats.
• Deep nesting. JSON supports arbitrary nesting, but humans do not. If your structure is more than five levels deep, flatten it. Readability is part of the contract.
• Mixing types in arrays. [1, "two", true] is valid JSON but usually a design error. Arrays should contain one type of thing. Mixed arrays are hard to validate and harder to reason about.

Connection to OIP

OIP (Object Invocation Protocol) is built on JSON because JSON is the only format that satisfies all three protocol requirements: open, deterministic, auditable.

Open means any system can participate without a proprietary license or secret decoder. JSON is an open standard (RFC 8259). Every language has a parser. No vendor controls it.

Deterministic means the same input produces the same output every time. JSON parsing is specified down to the byte. "42" is never 42. true is never "true". The parser does not guess. The contract does not bend.

Auditable means a human can inspect every message, every receipt, every configuration, and every capability declaration without special tools. A ledger entry in JSON is a complete record. An auditor can read it, diff it, and verify it. No binary blobs. No opaque state.

In OIP, directory rows are JSON. Dispatch envelopes are JSON. Ledger receipts are JSON. Configuration is JSON. The entire protocol is readable text because the protocol's purpose is to make action provable, and proof requires visibility. JSON is the visibility layer. Without it, OIP is a black box. With it, every invocation is a document, every document is evidence, and every piece of evidence is readable by anyone with a text editor.

That is the power of JSON. It is not the most compact format. It is not the fastest format. It is the most honest format. And in a protocol that lives or dies on honesty, that is the only metric that matters.

Latest clarity reviews (live)

Fresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.

• 2026-07-05 19:55 · model gemini/gemini-2.5-flash · NEEDS WORK · JSON 9/10 · English 10/10 · zero-context human 9/10
• 2026-07-03 00:16 · model @cf/meta/llama-3.3-70b-instruct-fp8-fast · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10

- gaps named: OIP build overview; OIP object model; Directory rows and dispatch; Ledger, receipts, replay, repair

How the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.

---

Where OIP does this differently (required edge)

OIP difference: JSON is the executable map (object, routes, proof loop) — not only a data interchange tutorial.