SER v1 JSON Schema

Level 300 (Advanced)

This page is advanced reference material intended for architects and integrators. You should be comfortable with pipelines and basic inspection before reading this (see Pipeline users and Architects & system designers).

The Semantic Execution Record (SER) captures the execution of each Node from a compiled Graph (GraphV1) run. This page summarizes the v1 JSON Schema shipped with Semantiva (semantiva.trace.schema.semantic_execution_record_v1.schema.json) and shows how each field relates to runtime behavior and glossary concepts.

The schema is consumed by the Trace pipeline and emitted by the JsonlTraceDriver. For a conceptual mapping between SER entries and the graph runtime, see Trace ↔ Graph Alignment.

Loading the Schema

from importlib import resources

schema = resources.files("semantiva.trace.schema") / "semantic_execution_record_v1.schema.json"

Top-Level Structure

Each SER JSON object has the following top-level fields:

Top-level SER fields

Field

Purpose

record_type

Constant "ser" identifying the document type.

schema_version

Constant 1 indicating the SER major version.

identity

Stable identifiers for the run, pipeline, and node being recorded.

dependencies

Upstream Node identifiers that fed this step.

processor

The Processor implementation, parameters, and parameter sources.

context_delta

Observation of Context Channel reads/writes captured at SER emission.

assertions

Structured checks with environment metadata and redaction policy.

timing

Start/end timestamps plus duration (wall and CPU milliseconds).

status

Final state of the step (succeeded/error/skipped/cancelled).

error (optional)

Structured information about failures when status is error.

tags (optional)

Arbitrary key/value labels for correlation and filtering.

summaries (optional)

Digests of inputs/outputs/context depending on trace policy.

Identity & Dependencies

identity contains run_id, pipeline_id, and node_id. These values correspond to the canonical IDs produced from the Graph (GraphV1) and are used to correlate SER entries with Canonical Graph Builder inspection outputs.

dependencies.upstream is an array of upstream node_id values. The runtime populates this list with the immediate predecessors that satisfied current node inputs, matching the dependency edges described in Trace ↔ Graph Alignment.

Processor Block

The processor object captures details about the executing Processor:

  • ref — fully-qualified class name (Processor Reference).

  • parameters — parameter map resolved for this invocation.

  • parameter_sources — origin of each parameter value. Permitted enums are: "context" (drawn from the Context Channel during parameter resolution), "node" (declared on the Node), and "default" (taken from processor defaults).

Because Semantiva separates data and context, processors may fetch values from both the Data Channel and Context Channel. The parameter source metadata documents which channel contributed values, enabling downstream replay or audits.

Context Delta

context_delta provides the structured observation of context mutations during SER emission:

  • read_keys — keys read from the Context Channel.

  • created_keys — keys introduced during execution.

  • updated_keys — existing keys whose values changed.

  • key_summaries — per-key digests of changed values (dtype, length, etc.).

This observation occurs during the second context observation phase (SER emission) described in Context Channel. Processors that interact with context outside of SER emission must do so via a Context Processor and should also update their declared read/write sets so the delta remains accurate.

Assertions

The assertions object records execution evidence:

  • preconditions and postconditions — arrays of structured checks that demonstrate expectations before and after the processor ran.

  • invariants — additional checks evaluated throughout execution.

  • environment — runtime metadata (Python version, platform, Semantiva build, etc.).

  • redaction_policy — declaration of any applied redactions.

Each check item follows the check definition in the schema, requiring a code and result (PASS/WARN/FAIL), with optional details. This mirrors the evidence captured by the orchestrator described in Semantic Execution Record (SER) v1.

Timing, Status, and Errors

timing captures start/finish instants plus duration metrics:

SER timing fields

Field

Required

Type

Notes

started_at | yes

string

RFC3339 timestamp (UTC Z) for processor start

finished_at | yes

string

RFC3339 timestamp (UTC Z) for processor end

wall_ms

yes

integer

Wall-clock duration in milliseconds

cpu_ms

no

integer

CPU time in milliseconds when available

These values measure the actual runtime of the Processor as scheduled by the orchestrator.

status enumerates the final outcome (succeeded, error, skipped, cancelled). When status is error, the optional error object may include serialized exception details captured by the runtime.

Tags & Summaries

Optional tags provide lightweight correlation metadata (for example, a processor family or dataset identifier). summaries contain digests of inputs and outputs when trace policy enables additional detail. Data summaries may include hashes or representations of the Data Channel, while context summaries capture structured snapshots of the Context Channel keys.

Driver Behavior

The JsonlTraceDriver serializes each SERRecord as one JSON line, appending to the configured destination file. Downstream tooling can stream the resulting Trace and validate entries by loading the same JSON Schema.