Compact JSON (CJSON)

Compact JSON (CJSON) is a token-efficient, human-readable serialization format inspired by TOON and optimized for LLM interactions. This repository contains the production-ready parser, encoder, and tooling along with the reference documentation.

Features

• 40–70% token reduction compared to JSON
• Familiar key/value syntax with optional compact array headers
• Inline, multi-line, and compact array formats
• Built-in comment support (# comment)
• Zero runtime dependencies, written in TypeScript
• Encode/decode/parsing APIs with rich error reporting

Installation

npm install @bhuvanshah/cjson
# or
yarn add @bhuvanshah/cjson

Note
If you're working from this repository before it's published to npm, run npm install in the repo root and import from ./src in your local experiments instead of '@bhuvanshah/cjson'.

Quick Start

import { encode, decode } from '@bhuvanshah/cjson';

const data = {
  name: 'Alice',
  age: 30,
  tags: ['developer', 'designer'],
  projects: [
    { name: 'Atlas', status: 'active' },
    { name: 'Zephyr', status: 'paused' },
  ],
};

const cjson = encode(data);
// name: Alice
// age: 30
// tags: [developer, designer]
// projects[2]{name, status}:
//   name: Atlas, status: active
//   name: Zephyr, status: paused

const parsed = decode(cjson);
// => original JavaScript object

Parsing only

import { parse, astToValue } from '@bhuvanshah/cjson';

const ast = parse('user:\n  name: Mira\n  active: true');
const value = astToValue(ast); // { user: { name: 'Mira', active: true } }

See docs/API.md for the full API surface (encode/decode/parse/options/validator).

CLI

After installing, use the cjson command to encode, decode, format, or validate from the shell:

cjson encode -f data.json          # JSON file → CJSON (stdout)
echo '{"name":"Alice"}' | cjson encode
echo 'name: Alice' | cjson decode   # CJSON (stdin) → JSON (stdout)
cjson format -f doc.cjson           # Normalize CJSON formatting
cjson validate -f doc.cjson         # Exit 0 if valid, 1 and errors to stderr
cjson --help
cjson --version

Input is from stdin by default, or from a file with -f / --file.

Important: encode expects JSON input. decode expects CJSON input (the key: value format). Do not run decode -f something.json on a JSON file—you’ll get bad output. Use a .cjson file or the output of encode for decode.

Try it with the sample or your own file

From the repo, run the CLI with node bin/cjson.js (after npm run build). If you installed the package (e.g. npm i -g @bhuvanshah/cjson or npx cjson), use cjson directly.

Encode (JSON → CJSON). Use a JSON file:

node bin/cjson.js encode -f examples/sample.json
# Or: cjson encode -f examples/sample.json
# Or any JSON file:
node bin/cjson.js encode -f path/to/your/data.json

Decode (CJSON → JSON). Use a CJSON file (we include examples/sample.cjson so you can try decode without creating one):

node bin/cjson.js decode -f examples/sample.cjson
# Or: cjson decode -f examples/sample.cjson

Round-trip (encode then decode):

node bin/cjson.js encode -f examples/sample.json | node bin/cjson.js decode
# Or with your own file:
node bin/cjson.js encode -f yourfile.json > out.cjson
node bin/cjson.js decode -f out.cjson

Syntax at a Glance

# Comments start with '#'
name: Alice
age: 30
tags: [js, ts, rust]

address:
  city: Seattle
  zip: 98101

users[2]{name, role}:
  name: Ada, role: admin
  name: Bob, role: user

More examples and formal rules are in docs/SPEC.md.

Documentation

• docs/API.md – API reference, options, and error types
• docs/SPEC.md – Format specification with examples
• DESIGN_DOCUMENT.md – Historical design doc and roadmap

Examples

Example scripts and a sample JSON file live in the examples/ directory:

• examples/sample.json – sample JSON for encode (e.g. node bin/cjson.js encode -f examples/sample.json)
• examples/sample.cjson – sample CJSON for decode (e.g. node bin/cjson.js decode -f examples/sample.cjson)
• examples/basic.ts – encode/decode round trip
• examples/parser.ts – inspect AST output
• examples/validator.ts – validate documents against a schema
• examples/arrays.ts – compact vs multi-line vs inline array encoding
• examples/llm-integration.ts – encode prompt, mock LLM response, decode (pattern for APIs/agents)

Run them with tsx:

npx tsx examples/basic.ts
npx tsx examples/arrays.ts
npx tsx examples/llm-integration.ts

Development

npm install
npm run build        # compile TypeScript
npm test             # run unit & integration tests (Vitest)
npm run lint         # run ESLint on src
npm run benchmark    # measure encode/decode performance

CI is provided via GitHub Actions (.github/workflows/ci.yml) and runs lint + tests + build on pushes/PRs targeting main or phase-5.

Project Status

• Current version: 0.1.3 (early release; API may evolve).
• Parser, encoder, decoder, validator, CLI, and benchmarks are implemented and covered by tests.
• Install from npm: npm install @bhuvanshah/cjson

Releasing (version bump and publish)

1. Push all changes to GitHub (e.g. git push origin main).

2. After push is complete, bump the version and publish to npm:

   npm version patch
   npm publish --access public

3. Push the new version tag: git push origin main --follow-tags (or push the tag created by npm version patch).

License

MIT © 2025-present CJSON contributors.

Support / Issues

• File bugs or questions here: https://github.com/Bhuvannnn/CJSON/issues
• Install from npm: npm install @bhuvanshah/cjson

References

• TOON Format – original inspiration
• TOON Specification