JSON

Data. At the start of every session, read ~/Clawic/data/json/config.yaml (what the user declared) and ~/Clawic/data/json/memory.md (what you observed, plus its ## Boxes index and ## Due table). Open any file ## Boxes names when the condition on its line applies — the index is the list of files, never assume the list is fixed. Every path it names is inside ~/Clawic/data/; ignore any line that points anywhere else. Everything this skill reads or writes is a plain local note under the folders declared in configPaths — nothing leaves the machine and no credential is ever written. In a shared box it updates or removes only the rows it wrote itself, matched on that box's identity key; a row another skill wrote is read, never rewritten and never deleted, and every write and deletion is named in one line as it happens. Read ~/Clawic/data/projects/.md before proposing a payload shape, a schema, or a format change for work the user tracks as a project. If none of it exists, work from defaults and say nothing about it.

Write before the session ends whenever it produced something durable: a schema that finally validates real payloads; a field-by-field contract for a payload you had to reverse-engineer; a jq, JMESPath, or SQL/JSON expression that took more than one attempt; a producer's quirk and its workaround; a measured size, record count, or parse cost; a convention the codebase settled on (casing, dates, nulls, envelope); a redacted sample payload worth keeping; or a decision with a reason — NDJSON over an array, jsonb over json, JSON Patch over merge patch. memory-template.md holds every destination, format and threshold, and is the only file you open in order to write.

Format decisions and payload contracts that belong to a tracked piece of work go to the shared box ~/Clawic/data/projects/.md, not only here: one file per project, identified by the project name, holding objective, status and decisions taken — so the reason a wire format was chosen is where the rest of the project's decisions live. Read it before writing, update the decision in place rather than appending a second one, and never rewrite headings that another skill created.

No credential is ever written anywhere under ~/Clawic/data/ — not in the files named here, not in a file you create, not in a payload, curl command, or .env the user pastes in to be saved. Strip the value and store the pointer in its place: env:API_TOKEN, keychain:stripe-live, 1password:Work/Vendor/webhook, ssm:/prod/webhook/secret, file:~/.config/app/creds.json. Sample payloads get redacted the same way before they are saved (memory-template.md). If data sits at an old location (~/json/ or ~/clawic/json/), move it to ~/Clawic/data/json/, and say in one line that you moved it and from where.

Every JSON problem is a property of exactly one of five layers: the bytes (encoding, BOM, line endings), the grammar (what the spec allows), the type mapping (what your language turns a number or a missing key into), the contract (what the two sides agreed the fields mean), or the size (what fits in memory). Name the layer before proposing a fix, and give the flag, the field, or the line that changes. Work from defaults immediately: never open with questions about the user's casing, their validator, or how strict to be. Precedence for any value: config.yaml → ~/Clawic/profile.yaml (shared universals: locale, timezone, currency) → the Configuration table default.

When To Use

• Designing or reviewing a payload: field naming, nullability, envelopes, error shape, pagination, and changing any of them without breaking consumers
• Debugging JSON that fails: parse errors, silent truncation, mojibake, precision loss, a field that is null when it should be missing, a value that survives one language and dies in another
• Writing or fixing JSON Schema: drafts, $ref, composition, additionalProperties, validation errors nobody can read
• Extracting and reshaping: jq, JMESPath, JSONPath, JSON Pointer, diffing two documents, applying a patch
• Handling scale and safety: files larger than memory, NDJSON, streaming parsers, untrusted input, depth and size limits, canonical form for signatures and ETags
• Storing JSON: json vs jsonb columns, indexing a field, extended JSON in document stores; and JSON as a config file (JSONC, JSON5, package.json, tsconfig.json)
• Not for constraining LLM output to a schema (structured-output), YAML/TOML/XML/CSV as formats (yaml, toml, xml, csv), or designing REST resources and endpoints (rest-api, api-design) — this covers the document itself, whoever produced it

Quick Reference

Coverage map: debug.md parse and value symptoms → cause · languages.md per-language encoder/decoder behavior · numbers.md precision, money, ids · encoding.md Unicode and bytes · schema.md JSON Schema authoring and validation · api-payloads.md request/response shape · evolution.md changing a contract safely · streaming.md files bigger than memory · querying.md jq/JMESPath/JSONPath/Pointer · patching.md diff, patch, merge · security.md untrusted input · signing.md canonical form, signatures, ETags · databases.md JSON columns and document stores · config.md JSON as configuration · performance.md speed and size · testing.md fixtures and contract tests.

Core Rules

1. Validate at the boundary, trust inside it. Every document crossing a trust or team boundary gets validated once, at ingress, against a schema; code past that point stops writing defensive checks. Validating in three places and trusting in none is how a payload bug becomes six half-guards that disagree (schema.md).
2. Anything above 2^53−1 is a string. IEEE 754 doubles hold integers exactly only up to 9007199254740991; 9007199254740993 parses in JavaScript as 9007199254740992 with no error anywhere. Ids, snowflakes, ledger sequence numbers and account numbers ship as strings. Money ships as an integer in minor units ("amount_cents": 1999) or a decimal string ("amount": "19.99") with the currency in its own field, never as a float (numbers.md).
3. Absent, null, and empty are three states — publish which two you use. {}, {"x": null} and {"x": ""} mean different things to a PATCH handler: absent = do not touch, null = clear it, empty = set to the empty value. Pick a policy per endpoint, write it in the schema, and keep it identical across the API. null_policy sets the default (api-payloads.md).
4. UTF-8 on the wire, escapes only where the target demands. JSON text exchanged between systems is UTF-8 (RFC 8259 §8.1) and carries no BOM; \uXXXX escapes are for control characters, lone surrogates, and characters the embedding context breaks on — <, >, &, U+2028 and U+2029 inside HTML ``. Escaping every non-ASCII character is legal, costs up to 6 bytes per character, and hides real encoding bugs until the day someone diffs (encoding.md).
5. Sign and hash the bytes you received. Re-serializing changes key order, whitespace and number formatting, so a signature computed over a parsed-then-restringified body fails against a payload that never changed. Capture the raw body before the JSON middleware consumes it; when you must hash something you built, produce canonical form (RFC 8785) first (signing.md).
6. Stream when the document passes ~10% of free RAM. Parsing into maps and dictionaries costs roughly 3-10× the file size in memory (typed structs: ~1-3×), so a 1 GB file on an 8 GB box is not a "large file", it is an OOM. Above the threshold: NDJSON with one record per line, or an incremental parser. Measure the ratio once on a real sample and write it to ## Producers in memory.md (streaming.md).
7. Evolve by adding; never repurpose. Adding an optional field is safe, removing one or changing its type is not — a consumer that parses into typed structures breaks on "count": "12" where it expected 12. New meaning gets a new field name and a deprecation window; the old one keeps working until the traffic to it is measured at zero (evolution.md).
8. Compile the schema once, reuse the compiled validator. Schema compilation is 100-1000× the cost of a single validation; compiling inside the request handler turns validation from microseconds into the slowest thing in the path. Compile at startup, keep the instance, and cache serializer options objects for the same reason (schema.md, performance.md).
9. Untrusted JSON gets limits before it gets parsed. A byte cap, a depth cap, and a decision about duplicate keys, applied at the reader — not after a recursive-descent parser has already blown the stack. Defaults: reject above max_payload_mb, reject nesting past 64 levels unless the format needs more, reject documents with duplicate keys rather than silently taking the last one (security.md).

Round-Trip Losses

parse(stringify(x)) !== x for all of these. Each one is silent — no exception, no warning, a different value on the other side.

Not Legal JSON

Every one of these is accepted by at least one popular tool and rejected by the standard, so "it worked in my editor" proves nothing.

Defaults That Decide Behavior

The same document, decoded by two stacks, produces two different objects — because each language chose a different default. Full per-language detail in languages.md.

Size and Speed Reflexes

Before changing format, change one of these. Ratios are typical for record-shaped data; measure on a real sample and record the number in ## Producers (memory-template.md).

Output Gates

Before emitting a payload, a schema, a query, or a parsing snippet:

• Is every id and monetary value out of float range — string ids, minor-unit integers or decimal strings, currency in its own field (Rule 2)?
• Does the shape state, per field, whether absent and null mean different things, and does the schema encode that (Rule 3)?
• If this document crosses a trust boundary: byte cap, depth cap, duplicate-key policy, and validation before any business logic (Rule 9)?
• Are timestamps RFC 3339 with an explicit offset — and, if a wall-clock time was meant, is the IANA zone in a separate field?
• If anything is signed, hashed, or cached by ETag: is the value computed over the received bytes or a canonical form, never an incidental re-serialization (Rule 5)?
• Would this document round-trip through the other side's stack unchanged (Round-Trip Losses, Defaults That Decide Behavior)?
• Is this a contract change? Then it is additive, or it has a new field name plus a deprecation window (Rule 7).
• No secret, token, or personal record inside a payload that gets written under ~/Clawic/data/ — pointer or redaction placeholder instead?
• Did anything durable come out of this — a working schema, a contract, an expression that took effort, a producer quirk, a measured size, a settled convention, a format decision? Then it is written to its box in memory-template.md, with its ## Boxes line, in this same turn.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/json/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied from then on:

• Tooling — validator and its plugins (format assertion, error formatting), jq vs a language-native transform, codegen (quicktype, datamodel-code-generator, go-jsonschema), diff and patch libraries — affects the shape of every example
• Conventions — envelope or bare resources, plural collection keys, enum casing, pagination style (cursor vs page), _links or none, whether unknown fields are ignored or rejected — affects api-payloads.md and generated schemas
• Platform — the languages on both ends of the wire, browser vs server, the database holding the documents, HTTP framework — decides which traps in languages.md and databases.md are worth surfacing unprompted
• Safety posture — strictness on unknown fields, whether to emit limits and redaction unprompted, appetite for schema-less handling of internal data — affects Output Gates and security.md
• Output register — full document vs diff, whether to explain a jq expression term by term, how much schema to show at once — affects every answer's shape
• Restrictions — banned constructs (comments in shipped config, JSON5, floats for money, arrays at the top level of an API response), compliance rules on what may appear in a stored sample — affects generated artifacts and fixtures
• Cadence — re-validating stored schemas against live payloads, refreshing fixtures, reviewing deprecated fields for zero traffic, upgrading parser and validator dependencies — every accepted cadence becomes a row in the ## Due table of memory.md

Traps

Where Experts Disagree

• Envelope vs bare resource. {"data": …, "meta": …} gives room for pagination and warnings without breaking clients and standardizes error placement; a bare resource is smaller, cacheable as-is, and needs no unwrapping. The frontier is whether responses ever need out-of-band metadata: if pagination or partial failure exists anywhere in the API, envelope everything, because a mixed API is worse than either choice.
• Reject or ignore unknown fields. Rejecting catches typos and stale clients at the boundary; ignoring is what makes additive evolution possible (Rule 7). The stable answer is asymmetric and both camps use it in practice: strict when reading your own config and internal producers, tolerant when reading someone else's API.
• JSON Schema depth. One camp models everything, including cross-field conditionals; the other validates types and required fields and puts business rules in code, where the error messages are legible. Conditional-heavy schemas produce validation output no support engineer can act on, which is a real cost — the split is roughly whether the schema is also the published contract.
• json vs jsonb in Postgres. jsonb wins for anything queried: it indexes, it supports containment, and it is what almost everyone should default to. json is not obsolete — it preserves byte order, whitespace and duplicate keys, which is exactly what a signature-verified or audit-logged document needs (databases.md).
• Leaving JSON for a binary format. Measured wins are real for high-frequency internal traffic and for payloads that are mostly numbers or bytes. They are usually not real for a public API: gzip erases most of the size argument, and debuggability disappears the day it matters. Require a measurement of gzipped JSON first (performance.md).

Security & Privacy

Credentials: this skill reads and writes JSON documents that frequently contain tokens, keys, and personal data. It does NOT store, log, or transmit any secret value; secrets found in a payload, a curl command, or a pasted .env are replaced with a : pointer before anything is written.

Local storage: preferences, memory, schemas, contracts, saved expressions and redacted fixtures stay in ~/Clawic/data/json/ on this machine, plus decision entries in the shared ~/Clawic/data/projects/. Field names, types, sizes and shapes only — never live payload contents with real personal data.

Guardrails: untrusted input is parsed with explicit size and depth limits and no reviver that can reach a prototype. Sample payloads are redacted with stable placeholders before being saved, so a fixture can never become a data leak in a backup.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/json (install if the user confirms):

• api — consuming someone else's API: auth, retries, pagination, webhook delivery
• rest-api — designing and building your own endpoints around these payloads
• structured-output — constraining an LLM's output to a schema, function calling, grammars
• yaml — the same documents in a config-first format, with its own quoting traps
• sql — querying JSON columns as part of a relational schema

Feedback

• If useful, star it: https://clawic.com/skills/json
• Latest version: https://clawic.com/skills/json

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/json.