{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://huggingface.co/datasets/szl-holdings/uds-observability/schemas/span_schema.json",
  "title": "UDS Span",
  "description": "A single UDS (Unified Data Substrate) observability span, shaped to the OpenTelemetry Trace Data Model (https://opentelemetry.io/docs/specs/otel/trace/api/) and extended with SZL governance fields for SLSA attestation linkage.",
  "type": "object",
  "required": [
    "trace_id",
    "span_id",
    "component",
    "kind",
    "timestamp_utc",
    "duration_ms",
    "status",
    "synthetic"
  ],
  "properties": {
    "trace_id": {
      "type": "string",
      "description": "128-bit globally unique trace identifier, hex-encoded (32 chars). Conforms to W3C Trace Context (https://www.w3.org/TR/trace-context/#trace-id). Groups all spans belonging to a single end-to-end request.",
      "pattern": "^[0-9a-f]{32}$",
      "examples": ["4bf92f3577b34da6a3ce929d0e0e4736"]
    },
    "span_id": {
      "type": "string",
      "description": "64-bit unique span identifier within the trace, hex-encoded (16 chars). Conforms to the OpenTelemetry SpanContext spec (https://opentelemetry.io/docs/specs/otel/trace/api/#spancontext).",
      "pattern": "^[0-9a-f]{16}$",
      "examples": ["00f067aa0ba902b7"]
    },
    "parent_span_id": {
      "type": ["string", "null"],
      "description": "Span ID of the parent span, or null for a root span. Used to reconstruct the directed-acyclic-graph (DAG) of spans within a trace per the OpenTelemetry Traces spec (https://opentelemetry.io/docs/concepts/signals/traces/).",
      "pattern": "^([0-9a-f]{16})?$",
      "examples": ["5e8b6c0d1a4f2e9d", null]
    },
    "component": {
      "type": "string",
      "description": "The SZL mesh component that emitted the span. One of the four UDS mesh components versioned at commit 25a7e53 (uds-v0.2.0).",
      "enum": ["a11oy", "amaru", "rosie", "sentra"],
      "examples": ["a11oy"]
    },
    "component_commit": {
      "type": "string",
      "description": "Short-form commit SHA of the specific component release that emitted the span. Used for supply-chain traceability per SLSA provenance requirements (https://slsa.dev/spec/v1.0/provenance).",
      "examples": ["cbf10510", "1ceefeb9", "29982b68", "ed6bca8f"]
    },
    "attestation_id": {
      "type": ["string", "null"],
      "description": "Opaque string identifier linking this span to a governance receipt in the DSSE-wrapped receipts file. Null when the span has not yet been attested. A non-null value indicates the span is 'well-attested' for the binary classification task defined in eval_starter.ipynb.",
      "examples": ["att-a11oy-001", null]
    },
    "dsse_envelope_b64": {
      "type": ["string", "null"],
      "description": "Base64url-encoded DSSE (Dead Simple Signing Envelope, https://github.com/secure-systems-lab/dsse) payload. Contains the in-toto attestation predicate for this span when present. Null for unattested spans. The PAE (Pre-Authentication Encoding) format follows the DSSE v1 spec: 'DSSEv1 SP LEN(type) SP type SP LEN(payload) SP payload'.",
      "contentEncoding": "base64url",
      "examples": [null]
    },
    "kind": {
      "type": "string",
      "description": "UDS span kind. Extends the OpenTelemetry SpanKind vocabulary (https://opentelemetry.io/docs/specs/otel/trace/api/#spankind) with UDS-specific governance and agent operation kinds. Core OTel kinds: CLIENT, SERVER, INTERNAL, PRODUCER, CONSUMER.",
      "enum": [
        "agent_call",
        "tool_invocation",
        "attestation_emit",
        "receipt_verify",
        "sbom_probe",
        "policy_eval",
        "sensor_ingest",
        "model_inference",
        "data_fetch",
        "receipt_chain_append",
        "CLIENT",
        "SERVER",
        "INTERNAL",
        "PRODUCER",
        "CONSUMER"
      ],
      "examples": ["agent_call", "attestation_emit"]
    },
    "timestamp_utc": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 / RFC 3339 UTC timestamp marking the start of the span. Aligns with OTel Span start_time_unix_nano semantics (https://opentelemetry.io/docs/specs/otel/trace/api/#span-start).",
      "examples": ["2026-01-15T10:23:45.123456Z"]
    },
    "duration_ms": {
      "type": "number",
      "description": "Span duration in milliseconds (float). Derived from OTel start_time_unix_nano and end_time_unix_nano. Must be >= 0.",
      "minimum": 0,
      "examples": [42.7, 1023.1]
    },
    "status": {
      "type": "string",
      "description": "Span status per the OpenTelemetry Status spec (https://opentelemetry.io/docs/specs/otel/trace/api/#set-status). Unset = operation completed without error; Error = error occurred; Ok = explicitly marked error-free by the developer.",
      "enum": ["Unset", "Ok", "Error"],
      "examples": ["Ok"]
    },
    "status_message": {
      "type": ["string", "null"],
      "description": "Human-readable description of the status, populated when status is Error.",
      "examples": [null, "Policy check failed: missing required field 'subject_sha256'"]
    },
    "attributes": {
      "type": "object",
      "description": "Key-value pairs carrying span-specific metadata. Values must be string, boolean, number, or homogeneous arrays thereof per the OTel Attributes spec (https://opentelemetry.io/docs/specs/otel/common/). SZL-specific keys are prefixed 'szl.'.",
      "additionalProperties": {
        "oneOf": [
          {"type": "string"},
          {"type": "boolean"},
          {"type": "number"},
          {"type": "array", "items": {"type": "string"}},
          {"type": "array", "items": {"type": "number"}},
          {"type": "array", "items": {"type": "boolean"}}
        ]
      },
      "examples": [{"szl.component_version": "0.2.0", "szl.slsa_level": 2, "http.method": "POST"}]
    },
    "events": {
      "type": "array",
      "description": "Timestamped annotations on the span, per the OTel SpanEvent spec (https://opentelemetry.io/docs/specs/otel/trace/api/#add-events). Useful for recording discrete governance checkpoints mid-span.",
      "items": {
        "type": "object",
        "required": ["name", "timestamp_utc"],
        "properties": {
          "name": {"type": "string"},
          "timestamp_utc": {"type": "string", "format": "date-time"},
          "attributes": {"type": "object"}
        }
      }
    },
    "slsa_level": {
      "type": ["integer", "null"],
      "description": "Observed SLSA level (https://slsa.dev/spec/v1.0/levels) at span emission time. Integer 0–3 per the SLSA v1.0 track taxonomy. Null when SLSA posture is unknown.",
      "minimum": 0,
      "maximum": 3,
      "examples": [2, null]
    },
    "mesh_commit": {
      "type": "string",
      "description": "The uds-mesh commit SHA at which this span was captured. Canonical anchor: github.com/szl-holdings/uds-mesh @ uds-v0.2.0 (commit 25a7e53).",
      "examples": ["25a7e53"]
    },
    "split": {
      "type": "string",
      "description": "Dataset split assignment: train, test, or validation.",
      "enum": ["train", "test", "validation"],
      "examples": ["train"]
    },
    "synthetic": {
      "type": "boolean",
      "description": "True for all records in this dataset release. All spans are synthetic-but-realistic examples generated to match the statistical distribution of production UDS mesh traffic. No live production data is included in v0.1.0.",
      "const": true
    }
  },
  "additionalProperties": false
}