commented

JSON with comments and trailing commas — what editors and their configuration files have settled on, tsconfig.json being the best-known.

dump

The same, as UTF-8 bytes — the form a body goes onto a wire in.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero, the default, writes the compact form with no space anywhere; anything larger writes one line per member with that many spaces a level, and a space after each colon.

A number that came in as text goes back out as that text, so a document read and written again is unchanged. Only a number with no such text is formatted, and a number that is not finite — which JSON5 can produce and JSON cannot write — becomes null, as every JavaScript implementation does.

load

Read one document from bytes, which is how one arrives over a wire. A leading byte-order mark is skipped by default. RFC 8259 §8.1 forbids writing one and says nothing about refusing to read one, and refusing would mean rejecting half the files Windows tooling produces.

loads

Read one document in the given dialect.

The whole input must be one value: anything after it, other than whitespace and — where the dialect allows them — comments, is Trailing, not silently ignored. A parser that stops at the first value turns a truncated file into a plausible one.

relaxed

JSON5: everything ECMAScript 5 would have accepted.

strict

RFC 8259 and nothing more.

At

Where something went wrong in a document that arrived as text.

The offset is in UTF-16 code units from the start, which is what a StringView indexes by; line and column are one-based, because that is how every editor counts and an error a person cannot find in their file is half an error.

Duplicates

What a repeated member name means.

A reader that fills a map keeps the last one, because that is what a map does, so that is the default. The other two are here because a document with two "id" members is usually a mistake, and a reader that wants to hear about it should not have to write its own parser.

Flavor

How to read a document: what syntax to accept, and what to do at the edges.

The dialects in this family differ only in their syntax — the tree they produce is the same — so the scanner is written once and each dialect is a set of switches. A dialect outside this repository can be described the same way without forking anything.

The last three fields are not syntax but policy. They are here rather than as arguments because they are set once for a deployment and because this family has sixteen entry points: a policy added here costs one line, and a policy added to every signature costs sixteen.

Refused

Why a document was refused, and where.

One error type for the whole family — reading text, reading bytes, walking a pointer, applying a patch, writing a value a format cannot carry — so that a caller has one thing to catch and one place to look. A variant that has a position carries the At it was found at; a variant about a pointer or a patch names the pointer itself, because a move and a copy each carry two and an error that did not say which one would be half an error.

dump

The same, as the UTF-8 bytes a body goes out as.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

load

The same, from the UTF-8 bytes a body arrives as.

loads

Read one JSON document.

Strictly RFC 8259: a leading zero, a trailing comma, a comment or a control character inside a string is an error naming the line and column it is on, not something quietly accepted.

dump

The same, as the UTF-8 bytes a body goes out as.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

load

The same, from the UTF-8 bytes a body arrives as.

loads

Read one JSONC document: JSON, plus comments and a trailing comma.

This is what tsconfig.json and settings.json are written in. Comments are discarded — the tree has nowhere to put them — so writing the result back out loses them.

dump

The same, as the UTF-8 bytes a body goes out as.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

load

The same, from the UTF-8 bytes a body arrives as.

loads

Read one JSON5 document.

JSON5 admits values JSON cannot write — Infinity, NaN, a hexadecimal integer — so a document read here and written as strict JSON is not always the same document. write says what becomes of each.

dump_all

The same, as UTF-8 bytes.

dumps_all

Write documents one to a line, each ending in a line feed.

Every line ends in one, including the last: a file that ends without it cannot be appended to safely, which is the format's whole purpose.

load_all

The same, from bytes.

loads_all

Read a stream of documents, one to a line.

A blank line is skipped rather than refused: files grown by appending end up with one, and refusing it would make a reader fail on its own writer's output. A carriage return before the line feed is also tolerated, because half the tools that produce these files run on Windows.

escape

Write a name so it can go into a pointer: ~ first, then /.

get

Follow a pointer and return what is there.

- as an array index is refused here even though RFC 6901 §4 names it: it means "one past the last element", which exists only for JSON Patch's add, and returning something for it would be inventing a value.

has

Whether a pointer leads anywhere. A malformed pointer is not an exception here — it simply does not lead anywhere.

join

Join names into a pointer, escaping each.

remove

Take away whatever pointer leads to, and answer the document that results.

RFC 6902's remove: the member or the element must be there, because taking away what was never there is a request nobody can have meant. The root cannot be removed — an empty pointer names the whole document, and there would be nothing left to answer with.

set

Put value where pointer leads, and answer the document that results.

The semantics are RFC 6902's add and replace taken together: a member or an element that is already there is replaced, one that is not is created, and - as an array index appends — which is the one place RFC 6901 §4 says that token means something, and the reason get refuses it.

It answers a new document rather than changing the one it was given. A tree is shared: a value reached through two pointers is one value, and editing it in place would change both. Only the path from the root to the edit is rebuilt; everything else is the same value it was.

let cfg = @pointer.set(cfg, "/spec/replicas", Json::number(5))

tokens

Split a pointer into the names it walks through, undoing the escapes.

The empty pointer names the whole document and yields no tokens; "/" names the member whose name is empty and yields one.

apply

Apply a patch to a document, and answer the document that results.

The operations are applied in order, each to the result of the one before it. A patch that fails partway applies nothing: the document it was given is never changed, and the answer is the error rather than half a document — RFC 6902 §5 says that if any operation is unsuccessful, application of the entire patch document is not deemed successful.

It answers a new document rather than changing the one it was given, for the same reason @pointer.set does: a tree is shared, and a value reached through two pointers is one value.

dump

The same, as the UTF-8 bytes a body goes out as.

dumps

Write a patch document: the operations as the array of objects RFC 6902 §4 prints them, op first and from before path where a move or a copy has both.

load

The same, from the UTF-8 bytes a body arrives as.

loads

Read a patch document: the array of operations it names.

The document itself is read as strict JSON — a patch is a protocol message rather than a settings file — and the dialect can still be named for a caller whose patches arrive from a JSONC source.

Operation

One operation in a patch document, as RFC 6902 §4 names the six.

merge

Apply a merge patch to a document, and answer the document that results.

A merge patch looks like the document it changes rather than like a list of instructions: a member that is not there is added, one that is there is replaced, and a member whose value is null is taken away — a null in the patch is an instruction, while a null already in the target is data and stays. A patch that is not an object replaces the whole document, null itself among them, and a target that is not an object is ignored and started again from an empty one.

It answers a new document rather than changing the one it was given, for the same reason @pointer.set does: a tree is shared, and a value reached through two pointers is one value.

let cfg = @json.loads("{\"host\":\"localhost\",\"port\":8080,\"tls\":false}")
@merge.merge(cfg, @json.loads("{\"port\":9090,\"tls\":null}"))
// {"host":"localhost","port":9090}

alike

Equality of values: numbers by value — 1 and 1.0 are one number — and everything else structurally.

compile

Compile a query.

The grammar is RFC 9535 §2.2's, and a query that does not parse is refused with the offset it stopped at rather than run as something else. Nothing around the query is whitespace: " $" and "$ " are not queries.

finds

Whether the pattern matches any part of the text.

matches

Whether the pattern matches the whole of the text.

The dialect is I-Regexp (RFC 9485): ., the classes [...], \p{...} for the Unicode general categories, the four quantifiers, alternation and groups. \d, \w and \s and their negations are accepted as well, which I-Regexp itself leaves out; they are what a pattern written for another dialect reaches for first, and refusing them would be a surprise rather than a service.

select

Run a query against a document, answering the nodes it selects in document order.

Op

A comparable operator.

Operand

One side of a comparison, or the thing a test asks about.

Path

A compiled query.

Segment

One step of a query.

Selector

One way of choosing from a node.

Test

What a filter asks.

dump

The same, as the UTF-8 bytes a signature is taken over.

dumps

The canonical form of a tree, as RFC 8785 writes it.

Members are ordered by their names compared as UTF-16 code units — not as code points, which differ for anything above U+FFFF — numbers are written the way ECMAScript writes them, and nothing is escaped that does not have to be. Two trees that hold the same values therefore come out as the same bytes, which is the whole point: a signature over these bytes is a signature over the document.

A number that is not finite cannot be written, because the RFC's number serialisation is ECMAScript's and ECMAScript has no syntax for it. It is refused rather than replaced with null or 0, either of which would sign something the document does not say.

dump

Write a tree as CBOR.

load

What a tree becomes when a CBOR value has no JSON counterpart.

JSON has no byte strings, no tags, no undefined and no map keys that are not strings, so those four are carried as objects with one reserved member each. They are the same markers every other binary package in this family uses, so a value read from CBOR and written to MessagePack keeps its bytes:

A map whose keys are all strings is written as a plain object, and a plain object is read back as a map. A document that means {"$bytes": "00"} as data has to be written in the $map form, because the marker is reserved — the same bargain MongoDB's Extended JSON makes, and for the same reason: a tree with one object type needs one reserved name.

Writing also accepts these markers: an object with exactly one $bytes member becomes a byte string, and so on for the rest. What was read from CBOR is therefore written back as the same CBOR, and MessagePack's byte strings, BSON's binary and CBOR's are one thing in the tree.

policy

The defaults: deterministic, five hundred levels deep.

Policy

How CBOR is read and written.

Two knobs, both of them things the RFC leaves open rather than things we invented: whether to write the deterministic form, and how deep a document may nest before it is refused.

dump

Write a tree as MessagePack.

load

Read one MessagePack document.

What JSON cannot hold comes back as the family's markers:

The same markers are read back as extensions and byte strings, so a document survives a round trip through this package.

policy

The defaults: doubles, five hundred levels.

Floats

How wide a float is written.

Policy

How MessagePack is read and written.

dump

Write a tree as a BSON document.

load

Read one BSON document.

A BSON document is always an object at the top, and the types JSON has no syntax for come back as markers:

Writing reads the same markers back, so a document that goes through the tree comes out as it went in. A marker is a reserved name: an object whose only member is $oid is an ObjectId, not a document that happens to have that member.

policy

The defaults: five hundred levels.

Policy

How BSON is read and written.

dump

Write a tree as UBJSON, in the simple (no length-prefix) form.

load

What a tree becomes when a UBJSON value has no JSON counterpart.

UBJSON *is* JSON's data model — null, true, false, numbers, strings, arrays and objects, with no byte strings, no tags, no undefined and no non-string map keys — so most of the markers the rest of this family uses have no UBJSON form. They are documented here, and what UBJSON cannot carry is either written as the closest plain thing or, for bytes, as an array:

A document that means {"$bytes": "00"} as data therefore has to be written in the $map form, because the marker is reserved — the same bargain every other package in this family makes, here reduced to a single marker that has only a one-way encoding. The other four markers ($tag, $map, $simple, $undefined) are written as plain objects with those member names, because UBJSON has no native form for them at all.

Writing also accepts these markers: an object with exactly one $bytes member becomes a UBJSON array of uint8, so a byte string read elsewhere and written here is carried as closely as UBJSON allows. What a real UBJSON document needs — numbers, strings, arrays, objects — needs no marker in the tree at all, and the non-JSON markers above are only round-tripped between the other packages of this family, never through UBJSON itself.

Encoding is the canonical, length-free "simple" form of the spec: containers are opened with [/{ and closed with ]/} with a per-element type marker, never the optimized # (count) or $ (type) prefixes. It is spec-based and is not byte-validated against an external UBJSON library, because none is available in this workspace.

policy

The default: five hundred levels deep.

Policy

How UBJSON is read and written.

The one knob the format leaves open is how deep a document may nest before it is refused, because a document of a hundred thousand open brackets is a denial of service rather than a document.

dump

Write a tree as Smile.

load

What a tree becomes when a Smile value has no JSON counterpart.

JSON has no byte string and no notion of a tag, undefined or a non-string key, so those four are carried as objects with one reserved member each, the same markers every other binary package in this family uses, so a value read from Smile and written to CBOR keeps its meaning:

Of these, only $bytes has a native Smile form: Smile's binary value. So the encoder turns a single-member {"$bytes": "hex"} object into a Smile binary, and the decoder turns a Smile binary back into {"$bytes": "hex"}. The remaining four markers ($tag, $map, $simple, $undefined) have no native Smile encoding; they are written as the plain objects they are and read back as plain objects, so a tree that already carries one round-trips without it being mistaken for something else.

policy

The default: five hundred levels deep.

Policy

How Smile is read and written.

The byte layout itself is fixed by the spec; the one knob is how deep a document may nest before it is refused, because a document of a hundred thousand open brackets is a denial of service rather than a document.

dump

Write a tree as bjson.

A value of any shape is accepted at the top level. The types JSON has no syntax for are written through the $bytes and $undefined markers documented on load, so a tree read from another binary package survives the round trip.

load

Read one bjson document from its bytes.

bjson is binary JSON, so the one type JSON has no syntax for — raw bytes — comes back through the same markers every binary package in this family uses, so a value read here and written to CBOR or BSON keeps its bytes:

(The full marker set used across the family is $bytes, $tag, $map, $simple, $undefined; this minimal reader accepts $bytes and $undefined, which are the ones a binary-JSON round trip needs.)

policy

The default: five hundred levels deep.

Policy

How bjson is read and written.

dump

Write a Json tree as a KRSON schemaless document.

See load for the design note and the fidelity warning. The writer builds the string-interning table from every object key and string value in the tree, writes the KR header with a zero schema id, the table, then the value tree using the tags below. A value the format cannot carry as JSON — there is none in the JSON-native model — would raise @moonjson.Unwritable.

load

Read a KRSON document and turn it into a Json tree.

KRSON is a real, schema-first binary serialization format (Rust core krson-core, JS SDK krson-js). Its schema-first form carries a 4-byte schema id and needs the originating schema runtime to interpret — a thing the shared Json tree here cannot host, and one that is not portable on its own. This package therefore implements the self-describing schemaless record, which the SDK also emits (encode/decode with no schema): magic KR, a version and flags byte, a schema id of 0, a string-interning table (every object key and string value is written once and referred to by index), then the value tree.

WARNING ON FIDELITY — the authoritative SPEC.md referenced by the KRSON project was not publicly retrievable at the time of writing, and the authors state the wire format "may still change between minor versions". This codec follows the primitives the SDK documents (magic KR, a length-prefixed string table, varint + zigzag integers, big-endian float64, and the value tags below). It is a genuine, self-consistent encoder/decoder of that subset; byte-exact interop with upstream KRSON is best-effort.

The value model is JSON-native, so this reader never produces the $bytes, $tag, $map, $simple or $undefined markers the other binary packages in this family use: a KRSON document has no byte strings, tags, maps with non-string keys, undefined or simple values to carry.

policy

The defaults: keys in source order, five hundred levels deep.

Policy

How KRSON is read and written.

Two knobs, both things the format leaves to the caller rather than things we invented: whether object members are written in sorted key order, and how deep a document may nest before it is refused.

dump

Write a tree as CBD.

The dictionary is built in the order keys are first met, matching the specification's "order of first appearance".

load

Read one CBD document.

The header is magic 0xCB 0xD1, version 0x01, then the dictionary size. A byte string has no type of its own in CBD v0.1.0, so it stays an ordinary object {"$bytes": "…"} — the marker every package in this family shares — and a trip through CBD leaves it exactly as it was.

policy

The default: five hundred levels deep.

Policy

How CBD is read and written.

The byte layout is fixed; the one knob is how deep a document may nest before it is refused, because a document of a hundred thousand open brackets is a denial of service rather than a document.

dump

Write a tree as SQLite jsonb.

load

What a tree becomes when a SQLite jsonb value has no JSON counterpart.

JSON has no byte string, so a SQLite blob is carried as an object with one reserved member:

SQLite jsonb is JSON's data model plus that one addition, so a blob reads into the same tree the rest of this family already understands, and what the tree cannot hold outright is carried in the markers documented here. A blob read here is written as a blob again, and the byte strings of CBOR, MessagePack and BSON are the one $bytes in the tree.

An object that happens to have a single $bytes member as its *data* has to be written through the $map form, because the marker is reserved — the same bargain every other package in this family makes.

policy

The default: five hundred levels deep.

Policy

How SQLite jsonb is read and written.

The byte layout itself is fixed by SQLite; the one knob is how deep a document may nest before it is refused, because a document of a hundred thousand open brackets is a denial of service rather than a document.

dump

Write a tree as PostgreSQL jsonb.

load

What a tree becomes when a jsonb value has no JSON counterpart.

A byte string survives a trip through this format the same way it does through SQLite jsonb, so the byte strings of CBOR, MessagePack and BSON are one $bytes in the tree whatever format carried them. A number is kept as PostgreSQL's NumericVar, an exact base-10000 decimal, so it round-trips digit for digit.

policy

The default: five hundred levels deep.

Policy

How PostgreSQL jsonb is read and written.

The byte layout is fixed; the one knob is how deep a document may nest before it is refused, because a document of a hundred thousand open brackets is a denial of service rather than a document.

dump

The same, as the UTF-8 bytes a body goes out as.

Writes the tree — including any superjson json/meta envelope — as ordinary JSON, delegating to @moonjson.dump.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

A superjson payload is JSON, so writing one is just ordinary JSON output (delegating to @moonjson.dumps). The envelope — json and meta — is emitted exactly as read. indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

load

The same, from the UTF-8 bytes a body arrives as.

Reads the superjson envelope as ordinary JSON, preserving both the json payload and the meta type table verbatim. See loads for why this package does not itself reconstruct JavaScript types: the Json tree has none to reconstruct into, and the wire form is plain JSON regardless.

loads

Read one superjson document.

Superjson's wire form is plain JSON shaped as {"json": <value>, "meta": { "values": { "<path>": "<type>" }, ... }}. The Json tree in this library has no Date, BigInt, Map or Set type, so there is nothing here to rebuild a JavaScript value into — and inventing one would not be faithful, because the whole point of the envelope is that those types live in JavaScript, not on the wire. The honest thing to do is therefore the simplest: parse the envelope as an ordinary JSON object (delegating to @moonjson.loads) and keep json and meta verbatim. The typed values survive as the plain JSON they decode to; the type table survives as the preserved meta object.

Full JavaScript-type reconstruction is out of scope for this Json tree. A caller that needs real Date/BigInt/Map/Set objects must rebuild them from the meta on the JavaScript side, where those types exist.

dump

The same, as the UTF-8 bytes a body goes out as.

See dumps for the design note: a tagged value is written back as the JSON object with its name:type key intact.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

A JSON-NTV value leaves here still a JSON object with a name:type key, because this delegates to @moonjson.dumps and does not rewrite keys.

load

The same, from the UTF-8 bytes a body arrives as.

See loads for the design note: a JSON-NTV document is valid JSON, so the bytes are read with the shared reader and any name:type key is preserved as a plain object key.

loads

Read one JSON-NTV document.

DESIGN — JSON-NTV is JSON. A tagged value such as {"paris:point": [2.35, 48.85]} is a perfectly ordinary JSON object with one member whose key happens to read name:type. There is therefore no separate tree to parse into: this call delegates to @moonjson.loads, so the name:type key is kept verbatim as the member key it is.

LIMITATION — because the shared Json tree has no notion of a typed name, the name and type parts of the key are not split apart or interpreted; they survive only as a plain object key. A reader that needs the name or the type must read the key string and divide it on the last :. This is the faithful and honest reading: a tagged value is valid JSON, and nothing here pretends otherwise.

dump

The same, as the UTF-8 bytes a body goes out as.

Writes the tree as ordinary JSON, delegating to @moonjson.dump; an rjson payload is standard JSON on the wire.

dumps

Write a tree as standard JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean. sort writes members in order of name instead of the order they were read in, which is what a diff wants. An rjson payload IS standard JSON, so this is ordinary output.

load

The same, from the UTF-8 bytes a body arrives as.

Reads rjson as ordinary JSON, delegating to @moonjson.load; an rjson payload is standard JSON regardless of how it is transported.

loads

Read one rjson document.

The Ruby json library emits and accepts standard JSON (RFC 8259), so this delegates to @moonjson.loads; an rjson payload is ordinary JSON.

dump

The same, as the UTF-8 bytes a body goes out as.

Writes the tree as ordinary JSON, delegating to @moonjson.dump; a json11 payload is standard JSON on the wire.

dumps

Write a tree as standard JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean. sort writes members in order of name instead of the order they were read in, which is what a diff wants. A json11 payload IS standard JSON, so this is ordinary output.

load

The same, from the UTF-8 bytes a body arrives as.

Reads json11 as ordinary JSON, delegating to @moonjson.load; a json11 payload is standard JSON regardless of how it is transported.

loads

Read one json11 document.

json11 emits and parses standard JSON, so this delegates to @moonjson.loads; a json11 payload is ordinary JSON.

dump

The same, as the UTF-8 bytes a body goes out as.

Writes the tree as ordinary JSON, delegating to @moonjson.dump; a value read from JSON-Z's representable subset is written back as JSON.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean. sort writes members in order of name instead of the order they were read in, which is what a diff wants. The JSON-Z representable subset round-trips as JSON here; the JSON-Z-exclusive numeric and container extensions cannot be reconstructed.

load

The same, from the UTF-8 bytes a body arrives as.

Reads JSON-Z as ordinary JSON-Z (the JSON5-compatible subset), delegating to @moonjson.load; see loads for the JSON-Z features this package keeps and the ones it cannot represent in a Json tree.

loads

Read one JSON-Z document.

JSON-Z shares its JSON5-compatible surface — comments, single and backtick quotes, unquoted object keys, trailing commas, hexadecimal and signed numbers, Infinity and NaN — with the relaxed reader, so those are parsed here by delegating to @moonjson.loads with flavor = relaxed.

LIMITATION — JSON-Z adds values the shared Json tree cannot hold: BigInt (the n suffix), arbitrary-precision decimals (m) and IEEE-754 Decimal128 (d), sparse arrays, undefined, and extended typed containers (Date, Map, Set, RegExp, Uint8Array). These are out of scope for a Json tree that has none of those types, exactly as superjson and ntv are out of scope for the types they cannot rebuild. A document that uses them is not accepted here.

dump

The same, as the UTF-8 bytes a body goes out as.

See dumps for the design note: the output is plain JSON ready to be stored into (or sent to) a ZSON column, which then compresses it with its trained dictionary.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

The result is the JSON a ZSON column accepts: the compression step that follows is PostgreSQL's, not this package's.

load

The same, from the UTF-8 bytes a body arrives as.

See loads for the design note: a ZSON value is jsonb — that is, JSON — so the bytes are read with the shared reader and the compression itself is out of scope for a portable library.

loads

Read one ZSON document.

ZSON is a PostgreSQL extension that compresses jsonb transparently, using a shared dictionary trained on the data a deployment actually stores. That makes it a *server-side* compression, not a portable wire format: the bytes on disk depend on a per-database dictionary that is not part of the document, so no standalone decoder can turn them back into a value. What travels between systems — the jsonb a column holds, the text a client sends or receives — is ordinary JSON, and that is the only part this library can faithfully handle. The honest reading is therefore a delegation: parse the value as JSON with the shared reader. A caller that needs real ZSON storage must use PostgreSQL with the extension installed; this package only understands the JSON a ZSON column carries.

(Do not confuse this with *ZJSON*, the Zed JSON encoding — a different format, implemented in moonbitstack/moonjson/zjson.)

dump

The same, as the UTF-8 bytes a body goes out as.

See dumps for the design note: the type/value envelope is written back as the JSON object it is, delegating to @moonjson.dump.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

indent of zero is the compact form. ascii escapes everything above U+007E, for a transport that is not eight-bit clean — what is sometimes called ensure_ascii, except that it is off by default here, because a UTF-8 body is the normal case now. sort writes members in order of name instead of the order they were read in, which is what a diff wants.

A ZJSON value leaves here still a JSON object carrying type and value, because this delegates to @moonjson.dumps and does not rewrite members.

load

The same, from the UTF-8 bytes a body arrives as.

See loads for the design note: a ZJSON document is valid JSON, so the bytes are read with the shared reader and the type/value members are kept exactly as written.

loads

Read one ZJSON document.

ZJSON is the JSON encoding of the Zed data model: a stream of JSON objects, each of the form {"type": <zed-type>, "value": <json-value>}, where type describes the rich Zed type (a primitive name like "int64", or a complex type built from record/array/map/union/enum/error/ref nodes) and value is the value rendered in plain JSON. It is, underneath, valid JSON — the type lives in a member alongside the value.

That is the same situation as superjson's envelope: the Json tree in this library has no Zed type system to rebuild into, so the faithful, honest reading is a delegation. This call parses the document as ordinary JSON with the shared reader, keeping type and value verbatim. A caller that needs real Zed typed values must interpret type against the Zed type model in a Zed-aware client — there is nothing here to lose by reading it as JSON, only the type annotation, which survives as the preserved type member.

(Do not confuse this with *ZSON*, the PostgreSQL JSONB-compression extension — a different format, implemented in moonbitstack/moonjson/zson.)

dump

The same, as the UTF-8 bytes a body goes out as.

Like dumps, the text produced is strict JSON written by @moonjson; CSON itself has no faithful textual rendering.

dumps

Write a tree as strict JSON.

CSON has no canonical text form — nothing the writer could print would be CSON a reader recognises as the same document — so this delegates to @moonjson.dumps, which already knows how to emit strict JSON for any Json.

load

Read one CSON document from the UTF-8 bytes a body arrives as.

A leading byte-order mark is skipped by default. If the bytes are not valid UTF-8 the document is refused rather than silently mangled.

loads

Read one CSON document.

The root is an object whose members sit at the first indentation level (or an array, if the first line is a - bullet). CSON is indentation-based, so the document is first reduced to structural lines and then walked recursively; what comes back is the same Json tree every dialect in this family reads into.

dump

The same, as the UTF-8 bytes a body goes out as.

dumps

Write a tree as strict JSON, whatever dialect it was read from.

Hjson has no canonical text form of its own — the same tree can be written many ways — so the writer emits strict JSON by delegating to @moonjson.

load

Read one Hjson document from the UTF-8 bytes a body arrives as.

A leading byte-order mark is skipped by default. Decoding that fails is a Bad refusal.

loads

Read one Hjson document from text.

Hjson is a superset of JSON as far as the tree is concerned, so whatever comes back here can be written out again as strict JSON with dumps. The flavor argument is accepted for the family's common signature; Hjson is always read leniently.

Sink

A sink that accumulates a sequence of JSON documents, one to a line.

The documents are buffered in memory; the value of the type is that it is written one document at a time, so a caller that produces them lazily never builds the whole array first.

Source

A source that hands back a sequence of JSON documents, one at a time.

format

Write a tree in the chosen shape.

The core writer does the work; this only bends its output where the core's signature cannot — a tab for each level, a carriage return before each line feed. A JSON string never contains a raw line feed (it is escaped), so rewriting line endings cannot touch a value.

pretty

The default: two spaces a level, LF line endings, the order the tree keeps.

reformat

Read a document and write it back in the chosen shape — the text-to-text entry point, what python -m json.tool does.

reformat_bytes

The same, from the UTF-8 bytes of a document.

Format

How to lay a document out.

The defaults are the ones a formatter is usually asked for — two spaces a level, LF line endings — and every field can be changed independently.