@axsept/event-schema

The open-standard JSON Schema for the HumanAIEvent wire format used by SkillChain-compatible integration wrappers.

This package is part of the SkillChain integration protocol. It contains only the schema and its TypeScript types — no business logic, no anonymization rules, no API client. Wrappers that need anonymization use @axsept/anonymizer; wrappers that need an MCP-server runtime use @axsept/mcp-server.

Install

npm install @axsept/event-schema

Use

Validating an event in TypeScript

import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { HumanAIEventSchema, type HumanAIEvent, PROTOCOL_VERSION } from "@axsept/event-schema";

const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);
const validate = ajv.compile(HumanAIEventSchema);

const event: HumanAIEvent = {
  protocol_version: PROTOCOL_VERSION,
  event_id: "evt_01HFG2X7K8Q9P0R1S2T3U4V5W6",
  timestamp: new Date().toISOString(),
  source: {
    provenance: "claude-mcp",
    session_id: "sess_01HFG2X7K8Q9P0R1S2T3U4V5XY",
    wrapper_version: "0.1.0",
    client: "claude-code",
  },
  description: "Designed a fraud-defense architecture and recorded the rationale.",
  skills: [
    {
      name: "system design",
      proficiency: 0.85,
      evidence_snippet: "Reframed the fraud model as 'screen, not proof'.",
    },
  ],
};

if (!validate(event)) {
  throw new Error("invalid event: " + JSON.stringify(validate.errors));
}

Loading the schema directly (e.g., in Python or another language)

The raw JSON Schema is shipped at node_modules/@axsept/event-schema/schema/HumanAIEvent.v1.json (or via the package export @axsept/event-schema/schema/HumanAIEvent.v1.json). Any JSON Schema 2020-12-compliant validator can load it.

What HumanAIEvent is for

It is the wire format every SkillChain-compatible wrapper emits to the SkillChain BFF. A wrapper observes a user working with an AI agent, extracts the skill-relevant content (locally, with PII / secrets stripped), and posts one or more HumanAIEvent payloads. The BFF deduplicates, ingests, and feeds the events into the engine's skill-extraction and verification pipeline.

The schema is versioned with semver:

• Major version changes (e.g., 1.x → 2.0) are reserved for breaking changes. The BFF accepts events from the current and previous major version for at least 12 months after a major bump.
• Minor version changes (1.0 → 1.1) are additive only — new optional fields or new enum values that older consumers can safely ignore.
• Patch version changes are clarifications and bugfixes; no functional changes.

What about the rest of the protocol?

The full integration protocol — attribution model, anonymization rules, auth model, runtime contracts, conformance suite, scaffold, versioning policy — lives at:

• The public protocol spec (TBD URL — see specs/architecture/skillchain-integration-protocol.md in the SkillChain monorepo today)

License

Apache-2.0