{"slug":"oip-what-is-json","title":"What is JSON","body":"## What It Is\n\n**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.\n\n## Why It Matters\n\nData 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.\n\n## How It Works\n\nJSON has six types. Six. No more.\n\n1. **Object**: `{}` — a map of string keys to values.\n2. **Array**: `[]` — an ordered list of values.\n3. **String**: `\"text\"` — UTF-8 text, always quoted.\n4. **Number**: `42` or `3.14` — no quotes. Integer or float.\n5. **Boolean**: `true` or `false` — lowercase. No quotes.\n6. **Null**: `null` — the absence of value.\n\nA 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.\n\nParsing 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.\n\n## The Contract\n\nThe JSON contract is explicit and unforgiving:\n\n- Keys must be double-quoted strings. Single quotes are invalid.\n- Trailing commas are forbidden. `\"a\": 1,` at the end of an object is a syntax error.\n- Comments are forbidden. No `//`, no `/* */`.\n- Numbers are base-10. No hex. No octal. No `Infinity`. No `NaN`.\n- Strings are UTF-8. Escape sequences are limited: `\\n`, `\\\\`, `\\\"`, `\\t`, `\\b`, `\\f`, `\\r`, `\\uXXXX`.\n- Whitespace outside of strings is ignored.\n\nThis 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.\n\n## Real Examples\n\n**Example 1: A directory row in OIP**\n```json\n{\n  \"key\": \"LEDGER_READ\",\n  \"type\": \"query\",\n  \"target\": \"D1\",\n  \"args\": [\"$1\"],\n  \"description\": \"Read a single ledger row by ID\"\n}\n```\nThis 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.\n\n**Example 2: An API dispatch envelope**\n```json\n{\n  \"key\": \"LEDGER_READ\",\n  \"body\": \"inv_abc123\"\n}\n```\nThis 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.\n\n**Example 3: A ledger receipt**\n```json\n{\n  \"request\": { \"key\": \"LEDGER_READ\", \"body\": \"inv_abc123\" },\n  \"response\": { \"status\": 200, \"result\": { \"id\": \"inv_abc123\", \"actor\": \"router\" } },\n  \"actor\": \"router\",\n  \"ts\": \"2026-07-05T14:00:00Z\",\n  \"trace_id\": \"t_xyz789\"\n}\n```\nThis 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.\n\n**Example 4: Configuration**\n```json\n{\n  \"build_version\": \"1.4.2\",\n  \"features\": [\"dispatch\", \"ledger\", \"selftest\"],\n  \"enabled\": true,\n  \"metadata\": null\n}\n```\nConfiguration 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.\n\n**Example 5: A batch of objects**\n```json\n[\n  { \"key\": \"ARTICLE_READ\", \"slug\": \"oip-what-is-json\" },\n  { \"key\": \"ARTICLE_READ\", \"slug\": \"oip-what-is-oip\" },\n  { \"key\": \"ARTICLE_READ\", \"slug\": \"oip-what-is-the-ledger\" }\n]\n```\nBatch 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.\n\n## Common Mistakes\n\n- **Using single quotes for strings.** JSON only accepts double quotes. `'key': 'value'` is invalid. Every parser rejects it.\n- **Trailing commas.** `\"a\": 1,` is fine inside an object. `\"a\": 1,}` is not. The last pair cannot have a trailing comma.\n- **Comments.** JSON has no comments. Preprocessors strip them, but standard parsers do not. If you need comments, use a separate documentation field.\n- **Unquoted keys.** `{ key: \"value\" }` is invalid. Keys must be quoted: `{ \"key\": \"value\" }`.\n- **Number precision.** JSON numbers are IEEE 754 doubles. Integers above 2^53 lose precision. If you need exact large integers, store them as strings.\n- **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.\n- **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.\n- **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.\n\n## Connection to OIP\n\nOIP (Object Invocation Protocol) is built on JSON because JSON is the only format that satisfies all three protocol requirements: **open, deterministic, auditable.**\n\n**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.\n\n**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.\n\n**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.\n\nIn 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.\n\nThat 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.\n\n## Latest clarity reviews (live)\n\nFresh 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.\n\n- 2026-07-05 19:55 · model `gemini/gemini-2.5-flash` · NEEDS WORK · JSON 9/10 · English 10/10 · zero-context human 9/10\n- 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\n  - gaps named: OIP build overview; OIP object model; Directory rows and dispatch; Ledger, receipts, replay, repair\n\nHow 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.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","dynamic"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"json-c1","tier":"system","text":"JSON (JavaScript Object Notation) is a text format for structured data exchange representing data as nested key-value pairs, arrays, and primitives.","who_claims":"system/oip_articles","source_ids":["json-s1","json-s2"],"evidence_basis":"provided_document","materiality":true,"weight":0.95,"status":"active","falsifier":"Demonstrate a JSON document that cannot be represented as nested key-value pairs, arrays, and primitives."},{"id":"json-c2","tier":"system","text":"JSON has exactly six types: object, array, string, number, boolean, and null. No more, no less.","who_claims":"system/oip_articles","source_ids":["json-s1","json-s2"],"evidence_basis":"provided_document","materiality":true,"weight":0.95,"status":"active","falsifier":"Show a valid JSON value that is not one of the six declared types."},{"id":"json-c3","tier":"system","text":"JSON parsing is deterministic with no silent coercion: \"42\" is a string, 42 is a number, true is boolean, and \"true\" is a string.","who_claims":"system/oip_articles","source_ids":["json-s1","json-s2"],"evidence_basis":"provided_document","materiality":true,"weight":0.9,"status":"active","falsifier":"Find a conformant JSON parser that silently coerces types against the spec."},{"id":"json-c4","tier":"system","text":"JSON's strict contract ensures every conformant parser produces the same structure from the same text: no trailing commas, no comments, no unquoted keys, no hex or NaN.","who_claims":"system/oip_articles","source_ids":["json-s1","json-s2"],"evidence_basis":"provided_document","materiality":true,"weight":0.9,"status":"active","falsifier":"Show two conformant JSON parsers that produce different structures from the same valid input."},{"id":"json-c5","tier":"system","text":"JSON is the lingua franca for data exchange because it is unambiguous, inspectable, and stateless — any system can read, write, and validate it without negotiation.","who_claims":"system/oip_articles","source_ids":["json-s1","json-s3"],"evidence_basis":"derived_inference","materiality":true,"weight":0.85,"status":"active","falsifier":"Demonstrate that JSON is ambiguous or requires hidden schemas to be interpreted consistently."},{"id":"json-c6","tier":"system","text":"In the OIP build, JSON is the executable map: directory rows, dispatch envelopes, ledger receipts, and configuration are all JSON, making every transaction serializable, loggable, and replayable.","who_claims":"system/oip_articles","source_ids":["json-s3","json-s4"],"evidence_basis":"provided_document","materiality":true,"weight":0.9,"status":"active","falsifier":"Show that OIP transactions cannot be serialized, logged, or replayed using JSON alone."}],"sources":[{"id":"json-s1","type":"protocol","url":"https://datatracker.ietf.org/doc/html/rfc8259","title":"RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format","quote":"JSON can represent four primitive types (strings, numbers, booleans, and null) and two structured types (objects and arrays).","summary":"The IETF standard defining JSON syntax, types, and parsing requirements.","author":"T. Bray","publisher":"IETF","date":"2017-12-01","claim_ids":["json-c1","json-c2","json-c3","json-c4"],"link_status":"ok","hash":"rfc8259json00001"},{"id":"json-s2","type":"protocol","url":"https://ecma-international.org/publications-and-standards/standards/ecma-404/","title":"ECMA-404: The JSON Data Interchange Format","quote":"A JSON value can be an object, array, number, string, true, false, or null.","summary":"The ECMA standard specifying JSON's exact grammar and data model.","author":"Ecma International","publisher":"Ecma International","date":"2017-01-01","claim_ids":["json-c1","json-c2","json-c3","json-c4"],"link_status":"ok","hash":"ecma404json00002"},{"id":"json-s3","type":"protocol","url":"https://www.json.org/json-en.html","title":"Introducing JSON","quote":"JSON is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.","summary":"The original JSON specification page by Douglas Crockford, describing JSON's design goals and simplicity.","author":"Douglas Crockford","publisher":"json.org","date":"2001-01-01","claim_ids":["json-c5","json-c6"],"link_status":"ok","hash":"jsonorg000000003"},{"id":"json-s4","type":"protocol","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","title":"OIP BUILD_SPEC — JSON as the executable map","quote":"The JSON is the structured operating map a model reads without guessing. It contains routes, object ids, invocation shapes, proof links, and repair paths.","summary":"The OIP build specification defining how JSON serves as the machine-native substrate for all invocations, receipts, and repairs.","claim_ids":["json-c6"],"link_status":"ok","hash":"oipbuildspecjson04"},{"id":"json-s5","type":"protocol","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","title":"Live OIP capability tree","quote":"root > shelf > system article > capability article > receipt","summary":"Public recursive capability tree showing OIP objects expressed as JSON.","claim_ids":["json-c6"],"link_status":"ok","hash":"oipmapjson000005"}],"prov":{"model":"system/oip_articles","action":"generate"}}