Skip to content

CLI.md

Latest commit

 

History

History
331 lines (247 loc) · 7.14 KB

CLI.md

File metadata and controls

331 lines (247 loc) · 7.14 KB

jstruct - JSON Structure CLI

A command-line tool for validating JSON Structure schemas and instances.

Installation

From Cargo (Rust)

cargo install json-structure --features cli

From Source

git clone https://github.com/json-structure/sdk.git
cd sdk/rust
cargo build --release --features cli
# Binary at: target/release/jstruct

Pre-built Binaries

Download from GitHub Releases:

Platform Architecture File
Linux x86_64 jstruct-x86_64-unknown-linux-gnu.tar.gz
Linux ARM64 jstruct-aarch64-unknown-linux-gnu.tar.gz
Windows x86_64 jstruct-x86_64-pc-windows-msvc.zip
Windows ARM64 jstruct-aarch64-pc-windows-msvc.zip
macOS Intel jstruct-x86_64-apple-darwin.tar.gz
macOS Apple Silicon jstruct-aarch64-apple-darwin.tar.gz

Package Managers

Homebrew (macOS/Linux):

brew tap json-structure/tap
brew install jstruct

Chocolatey (Windows):

choco install jstruct

Debian/Ubuntu:

sudo dpkg -i jstruct_*.deb

RHEL/Fedora:

sudo rpm -i jstruct-*.rpm

One-liner Installers

Linux/macOS:

curl -fsSL https://json-structure.org/install.sh | sh

Windows PowerShell:

iwr -useb https://json-structure.org/install.ps1 | iex

Commands

jstruct check - Validate Schema(s)

Validate one or more JSON Structure schema files for correctness.

jstruct check [OPTIONS] <FILES>...

Arguments:

  • <FILES>... - Schema file(s) to check. Use - for stdin.

Options:

  • -b, --bundle <FILE> - Bundle file(s) containing schemas for $import resolution. Can be specified multiple times.
  • -f, --format <FORMAT> - Output format: text (default), json, tap
  • -q, --quiet - Suppress output, use exit code only
  • -v, --verbose - Show detailed validation information

Examples:

# Check a single schema
jstruct check person.struct.json

# Check multiple schemas
jstruct check schemas/*.struct.json

# Check schema with external dependencies
jstruct check --bundle common-types.json --bundle address.json order.struct.json

# Read from stdin
cat schema.json | jstruct check -

# JSON output for CI integration
jstruct check --format json schema.json

# Quiet mode for scripts
jstruct check -q schema.json && echo "Valid"

jstruct validate - Validate Instance(s)

Validate JSON instance files against a schema.

jstruct validate [OPTIONS] --schema <SCHEMA> <FILES>...

Arguments:

  • <FILES>... - Instance file(s) to validate. Use - for stdin.

Options:

  • -s, --schema <SCHEMA> - Schema file to validate against (required)
  • -b, --bundle <FILE> - Bundle file(s) containing schemas for $import resolution in the schema. Can be specified multiple times.
  • -f, --format <FORMAT> - Output format: text (default), json, tap
  • -q, --quiet - Suppress output, use exit code only
  • -v, --verbose - Show detailed validation information

Examples:

# Validate a single instance
jstruct validate --schema person.struct.json alice.json

# Validate multiple instances
jstruct validate -s schema.json data/*.json

# Validate with schema that uses $import
jstruct validate -s order.struct.json -b common-types.json -b address.json order.json

# Read instance from stdin
cat data.json | jstruct validate -s schema.json -

# JSON output
jstruct validate -s schema.json --format json data.json

Exit Codes

Code Meaning
0 All files valid
1 One or more files invalid
2 Error (file not found, JSON parse error, etc.)

Output Formats

Text (Default)

Human-readable output with symbols:

✓ person.struct.json: valid
✗ bad-schema.struct.json: invalid
  - /$id: Missing required property "$id"
  - /type: Unknown type "invalid_type"

JSON

Machine-readable JSON array:

[
  {
    "file": "person.struct.json",
    "valid": true,
    "errors": []
  },
  {
    "file": "bad-schema.struct.json",
    "valid": false,
    "errors": [
      {
        "path": "/$id",
        "code": "SCHEMA_MISSING_ID",
        "message": "Missing required property \"$id\""
      }
    ]
  }
]

TAP (Test Anything Protocol)

Compatible with TAP consumers for CI/CD:

1..2
ok 1 - person.struct.json
not ok 2 - bad-schema.struct.json
  - /$id: Missing required property "$id"
  - /type: Unknown type "invalid_type"

Schema Bundles for $import Resolution

JSON Structure schemas can use $import and $importdefs to reference definitions from external schemas. When validating schemas that use these keywords, you need to provide the referenced schemas as a bundle.

How Bundles Work

  1. Each bundle schema must have a $id property with a URI
  2. When the main schema uses $import: "https://example.com/types.json", the validator looks for a bundled schema with $id: "https://example.com/types.json"
  3. If found, the definitions from the bundled schema are available for resolution

Example

Given these files:

common-types.json:

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://example.com/common-types",
  "definitions": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  }
}

order.struct.json:

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://example.com/order",
  "$import": "https://example.com/common-types",
  "type": "object",
  "properties": {
    "orderId": { "type": "string" },
    "shippingAddress": { "type": { "$ref": "#/definitions/Address" } }
  }
}

Validate with bundle:

jstruct check --bundle common-types.json order.struct.json

CI/CD Integration

GitHub Actions

- name: Validate schemas
  run: |
    jstruct check --format tap schemas/*.struct.json

GitLab CI

validate:
  script:
    - jstruct check --format json schemas/ > schema-results.json
  artifacts:
    reports:
      dotenv: schema-results.json

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit

SCHEMAS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.struct\.json$')
if [ -n "$SCHEMAS" ]; then
    jstruct check $SCHEMAS || exit 1
fi

Examples

Validate All Schemas in a Directory

find . -name "*.struct.json" -exec jstruct check {} +

Validate API Request/Response

# Validate request body
echo '{"name": "Alice", "age": 30}' | jstruct validate -s person.struct.json -

# Validate API response
curl -s https://api.example.com/person/1 | jstruct validate -s person.struct.json -

Batch Validation with Summary

jstruct check --format json schemas/*.json | jq '.[] | select(.valid == false)'

Watch Mode (with external tool)

# Using entr
ls schemas/*.json | entr -c jstruct check schemas/*.json

Related

License

MIT License - see LICENSE for details.