spanforge validate · Compliance Tool · In Development

Schema compliance. In CI.

SpanForge Validate is the reference validation CLI and Python SDK for the spanforge event standard. Validate JSON and JSONL event streams, verify HMAC signing chains, and catch non-compliance at build time — before it reaches production.

SpanForge SDK →Debug tooling →

Installation

One command to install.

pip install spanforge

Quickstart · CLI

Validate from the terminal.

Point spanforge-validate at any JSONL file produced by the SpanForge SDK. Pass a file path, pipe from stdin, or integrate it as a step in your CI workflow.

bash

# Validate a JSONL stream
spanforge validate events.jsonl

# Validate a JSON array
spanforge validate events.json

# JSON output for CI / downstream scripts
spanforge validate events.jsonl --json

# Read from STDIN
cat events.jsonl | spanforge validate

# OpenTelemetry compatibility: accept camelCase field names
spanforge validate events.jsonl --otel

# Pin to a specific schema version
spanforge validate events.jsonl --schema-version 0.1

# Cryptographic HMAC-SHA256 signature verification
spanforge validate events.jsonl --key-file signing.key

# Export the spanforge event JSON Schema (Draft 2020-12)
spanforge validate --export-schema > spanforge-schema.json

Exit codes

Code	Meaning
0	All events passed validation. Safe to proceed.
1	One or more events failed. Details printed to stdout.
2	Input could not be parsed (malformed JSON or unreadable file).

Quickstart · Python API

Programmatic validation.

Import spanforge_validate to validate individual events or entire streams in your test suite, CI scripts, or monitoring pipelines.

python

from spanforge.validate import validate_event, validate_stream
from spanforge.validate import iter_events
from spanforge.validate import ValidationContext

# Validate a single dict
result = validate_event(1, {
    "event_id": "01HZQSN7PQVR2K4M0BXJD3GSTA",
    "timestamp": "2026-03-06T10:00:00.000Z",
    "event_type": "agent.plan.created",
    "source": "spanforge@1.0.0",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7",
})
print(result.status)  # "pass"

# Validate a stream from a file
with open("events.jsonl") as f:
    for result in validate_stream(iter_events(f)):
        if result.status == "fail":
            print(f"Line {result.line}: {result.errors}")

CLI Reference

All options.

<file>Validate a JSONL stream or JSON array file.

--jsonJSON output for CI systems and downstream scripts.

cat file | spanforge validateRead from STDIN — pipe-friendly for CI step composition.

--otelOpenTelemetry compatibility mode — accept camelCase field names.

--schema-version <ver>Pin validation to a specific schema version, e.g. --schema-version 0.1.

--key-file <path>Cryptographic HMAC-SHA256 signature verification using a key file.

--export-schemaExport the spanforge event JSON Schema (Draft 2020-12) to stdout.

CI Integration

Add to your pipeline in two lines.

SpanForge Validate exits 0 on success and 1 on failure, making it a natural CI gate. Run it in any GitHub Actions, GitLab CI, or Jenkins pipeline step.

yaml

# GitHub Actions example
- name: Validate spanforge events
  run: |
    pip install spanforge
    spanforge validate tests/fixtures/events.jsonl --json

Use --json to get structured output for downstream processing, test-result reporting, or integration with your existing compliance pipeline.

The full stack

Standard. SDK. Debug. Validate.

Every layer of the spanforge compliance stack is open, documented, and ready to instrument your production AI systems.

Read the standard →SpanForge overview →

← SpanForge Debug SpanForge overview →