json-learner

Infer and merge JSON Schemas (draft-07) from JSON data — like Python's genson, for Node.js.

Features

• Infer JSON Schema from one or more JSON files or stdin
• Merge/refine an existing schema with new data
• Strict mode: read-only linter — validates JSON against a schema, exits with code 1 on violations (CI-friendly)
• Moderate mode: validates JSON, reports violations as JSON Lines, and updates the schema — exits 0 always
• Generate markdown documentation via @adobe/jsonschema2md
• Usable as a library (npm install json-learner)

Installation

npm install -g json-learner
# or use via npx
npx json-learner --help

CLI usage

json-learner [options] [files...]

Options:
  --schema <file>     Existing schema to refine or validate against
  --output <file>     Write output schema to file (default: stdout)
  --strict            Validate only (read-only); exit 1 on violations [requires --schema]
  --moderate          Validate and refine; emit violations as JSON Lines to stdout [requires --schema]
  --document [dir]    Generate markdown docs into directory (default: ./docs)
  --format            Pretty-print output JSON
  -V, --version       Show version
  -h, --help          Show help

Generate a schema from data

# From stdin
echo '{"name":"Alice","age":30}' | json-learner

# From file(s)
json-learner users.json

# Multiple files are merged into one schema
json-learner users-jan.json users-feb.json --output schema.json --format

Refine an existing schema with new data

If a field is missing in any new record, it becomes optional:

json-learner --schema schema.json new-records.json --output schema.json

Strict mode (linter / CI)

Exits with code 1 if any record violates the schema. Violations go to stderr.

json-learner --schema schema.json --strict data.json
echo $?  # 1 if violations, 0 if valid

Moderate mode (reporter + learner)

Reports violations as JSON Lines to stdout and refines the schema with new data. Always exits 0.

json-learner --schema schema.json --moderate data.json --output schema.json

# Pipe violations to jq
json-learner --schema schema.json --moderate data.json | grep '"keyword"' | jq .

Generate documentation

json-learner --schema schema.json --document ./docs
# Writes ./docs/schema.md

The --document flag is independent and can be combined with any other mode.

Library usage

import { inferSchema, inferFromMany, mergeSchemas, validate } from 'json-learner'

// Infer from a single value
const schema = inferSchema({ name: 'Alice', age: 30 })

// Infer from multiple values (required = intersection)
const schema2 = inferFromMany([
  { name: 'Alice', age: 30 },
  { name: 'Bob' },            // age missing → becomes optional
])

// Refine existing schema with new data
const updated = mergeSchemas(existingSchema, { name: 'Carol' })

// Validate
const result = validate(schema, { name: 42 })
if (!result.valid) {
  console.log(result.violations)
}

How it works

json-learner uses a strategy pattern inspired by genson:

• Each JSON type (null, boolean, integer, number, string, array, object) has a dedicated strategy
• A SchemaNode accumulates strategies and merges them
• required fields are computed as the intersection across all observed objects — a field is only required if it appears in every single record
• Integer values are promoted to number when a float is encountered

Requirements

• Node.js >= 20

License

MIT