Canonical Data and Event Model

Draft 0.1 — 2 August 2026
This document defines shared information contracts. It does not require that every product store identical internal tables or disclose private records to the network.

Objective

ANUKA needs a common language for people, products, contributions, evidence, money, governance, and AI actions.

Without canonical contracts, each product invents incompatible fields, events become ambiguous, agents guess at semantics, and reputation cannot remain portable.

The rule is:

Products may model internally as they choose, but network-facing records must be explicit, versioned, attributable, and testable.

Contract families

ANUKA maintains four contract families.

Entity schemas

Long-lived objects such as:

participant;
organization;
product;
project environment;
opportunity;
assignment;
contribution;
evidence package;
credential;
consent grant;
stewardship grant;
proposal;
dispute case.

Command schemas

Requests to perform an action.

Commands use imperative names such as:

CreateOpportunity;
SubmitContribution;
ApproveRelease;
RequestEvidencePresentation;
RevokeConsentGrant;
AuthorizeAgentTask.

Event schemas

Facts that have already occurred.

Events use past-tense names such as:

OpportunityPublished;
ContributionSubmitted;
ContributionAccepted;
ReleaseDeployed;
ConsentGrantRevoked;
AgentTaskCompleted.

Presentation schemas

Audience-specific views such as:

participant Passport presentation;
traction Passport;
investor data-room summary;
public product card;
reviewer evidence bundle;
capability proof.

A presentation may omit or derive information, but must declare its source records and policy.

Schema baseline

Canonical JSON schemas use JSON Schema Draft 2020-12 unless a ratified decision adopts a newer stable baseline.

Every schema must include:

$schema;
stable $id under an ANUKA-controlled domain;
title and description;
semantic version;
owner;
status;
privacy classification;
compatibility notes;
examples;
test vectors.

Example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.anuka.network/contribution/1.0.0/schema.json",
  "title": "ANUKA Contribution",
  "type": "object"
}

Schema URLs must remain immutable after release.

Identifier model

Identifiers are opaque strings. Consumers must not derive authority, location, creation time, or product type from an identifier unless the specification explicitly says so.

Recommended prefixes improve human debugging without creating hidden semantics:

par_ participant;
org_ organization;
prd_ product;
opp_ opportunity;
asn_ assignment;
ctr_ contribution;
evd_ evidence package;
cns_ consent grant;
stg_ stewardship grant;
prp_ governance proposal;
evt_ event;
tsk_ agent task.

Identifiers must be globally unique within their namespace and safe for logs and URLs.

Secrets, emails, database keys, and personal attributes must not be embedded in identifiers.

Resource identity and aliases

A resource may have:

one stable network identifier;
multiple human-readable slugs;
external provider identifiers;
historical aliases;
environment-specific identifiers.

Aliases can change. Stable identifiers should not.

External IDs must always be namespaced by provider and account scope.

Bad:

{ "customer_id": "cus_123" }

Better:

{
  "external_reference": {
    "provider": "stripe",
    "account_scope": "acct_456",
    "type": "customer",
    "id": "cus_123"
  }
}

Common record metadata

Canonical records should use a common metadata block where relevant:

{
  "id": "ctr_...",
  "schema_version": "1.0.0",
  "created_at": "2026-08-02T12:00:00Z",
  "created_by": "par_...",
  "updated_at": "2026-08-02T12:05:00Z",
  "revision": 3,
  "product_id": "prd_...",
  "organization_id": "org_...",
  "environment": "production",
  "classification": "restricted",
  "provenance": []
}

Timestamps must be RFC 3339 UTC unless a field explicitly carries a local date or timezone.

Temporal semantics

Different times must not be collapsed into one timestamp.

Possible fields include:

occurred_at — when the real-world event happened;
observed_at — when a system observed it;
recorded_at — when ANUKA persisted it;
effective_at — when a rule or grant begins;
expires_at — when it stops being valid;
published_at — when it became visible to an audience;
revoked_at — when status changed to revoked.

Clock uncertainty and late-arriving data should be recorded when material.

Money and quantity types

Money must never use binary floating-point values.

Represent monetary amounts with:

integer minor units and currency; or
decimal string and currency where minor units are insufficient.

{
  "amount_minor": 12500,
  "currency": "USD"
}

A value must distinguish:

gross charge;
tax;
platform fee;
processor fee;
allocation;
reserve;
earnings;
payout;
refund;
loss.

Percentages, rates, and confidence values require explicit units, range, and rounding policy.

Privacy classification

Every schema and field should declare or inherit a data class.

Recommended classes:

public;
participant_private;
organization_private;
permissioned;
restricted;
secret.

A record may contain mixed classifications. Presentations must filter fields according to the current authorization and purpose.

Public status must be deliberate, not inferred from the absence of an access-control entry.

Provenance model

Claims and derived values require provenance.

A provenance entry may contain:

source type;
source identifier;
controller;
collection method;
transformation version;
observation time;
integrity hash;
reviewer;
limitations;
disclosure policy.

Example:

{
  "source_type": "stripe_balance_transaction",
  "source_reference": "stripe:acct_...:txn_...",
  "observed_at": "2026-08-02T11:30:00Z",
  "transform": "anuka.revenue.normalization@1.2.0",
  "limitations": ["excludes cash payments"]
}

A derived metric must reference the exact source window and transformation.

CloudEvents envelope

Network events use CloudEvents 1.0-compatible envelopes unless a transport profile states otherwise.

Required attributes:

specversion;
id;
source;
type;
time;
subject where applicable;
datacontenttype;
dataschema;
data.

ANUKA extensions may include:

anukaproduct;
anukaorganization;
anukacorrelation;
anukacausation;
anukaclassification;
anukatraceparent.

Example:

{
  "specversion": "1.0",
  "id": "evt_01...",
  "source": "https://api.anuka.network/products/prd_123",
  "type": "network.anuka.contribution.accepted.v1",
  "subject": "ctr_456",
  "time": "2026-08-02T12:00:00Z",
  "datacontenttype": "application/json",
  "dataschema": "https://schemas.anuka.network/events/contribution-accepted/1.0.0/schema.json",
  "data": {}
}

Event type naming

Event types use reverse-domain namespaces and major-version suffixes.

Pattern:

network.anuka.<domain>.<fact>.v<major>

Examples:

network.anuka.opportunity.published.v1;
network.anuka.contribution.accepted.v1;
network.anuka.payment.payout-failed.v1;
network.anuka.agent.task-completed.v1.

Minor and patch-compatible changes are expressed through the referenced schema version, not a new event type.

Correlation and causation

Every multi-step workflow should propagate:

correlation ID — groups one business workflow;
causation ID — identifies the immediate command or event that caused this event;
trace context — connects distributed telemetry.

These identifiers serve different purposes and should not be merged.

Event delivery semantics

ANUKA assumes at-least-once delivery unless a transport profile states otherwise.

Consumers must:

deduplicate using event ID;
tolerate reordered events where declared;
validate schema before processing;
reject or quarantine unknown major versions;
preserve raw envelopes for incident analysis where policy permits;
avoid non-idempotent side effects without protection.

“Exactly once” may be approximated within a bounded system but must not be promised across arbitrary networks without a precise mechanism.

Ordering

Global ordering is not required.

Ordering may be defined per:

resource;
product;
ledger account;
assignment;
workflow;
partition key.

When order matters, events should include a monotonic resource revision or sequence number.

State transitions

Important entities should define explicit state machines.

Example opportunity states:

draft → published → assigned → in_progress → submitted → accepted → measured → closed

Alternative transitions such as cancellation, expiry, dispute, rejection, and reopening must be declared.

A state transition record includes:

prior state;
new state;
actor;
authority;
reason;
time;
related evidence;
idempotency key.

Deletion, correction, and revocation

These are distinct operations.

Deletion removes data when legally and technically appropriate.
Correction replaces or contextualizes inaccurate information.
Revocation marks a grant, credential, or authority as no longer valid.
Supersession points to a newer authoritative record.
Redaction removes fields from a presentation while preserving a controlled source record.

Audit and public records may retain tombstones or hashes without retaining prohibited personal content.

Schema compatibility

Backward-compatible changes

Usually include:

adding optional fields;
adding enum values only when consumers are required to tolerate unknown values;
relaxing a non-security constraint;
clarifying descriptions;
adding new event types.

Breaking changes

Include:

removing or renaming fields;
changing field meaning;
changing required status;
narrowing accepted values;
changing units;
changing identity or authorization semantics;
altering default privacy classification;
changing event delivery guarantees.

Breaking changes require a new major schema version.

Unknown fields and enum values

Consumers should ignore unknown optional fields unless security policy requires rejection.

Security-sensitive schemas may set unevaluatedProperties: false and require explicit extension points.

Enums that may grow should define consumer behavior for unknown values. Never assume all future values are safe equivalents of the current values.

Extension fields

ANUKA extension fields use namespaced containers rather than arbitrary top-level prefixes where practical.

{
  "extensions": {
    "com.example.feature": {
      "value": true
    }
  }
}

Extension owners must document:

namespace control;
schema;
privacy class;
compatibility policy;
whether the extension affects conformance.

API and event documentation

OpenAPI describes synchronous HTTP interfaces.
AsyncAPI describes event channels, operations, messages, and bindings.
JSON Schema remains the canonical payload contract.
CloudEvents provides the shared event envelope.

Generated documentation must not replace human explanation of business semantics.

Conformance testing

Each schema package should include:

valid examples;
invalid examples;
compatibility fixtures;
migration fixtures;
privacy filtering tests;
event deduplication tests;
idempotency tests;
signature or integrity tests where relevant.

Producers and consumers should be tested independently.

Schema registry

The registry must expose:

canonical schema ID;
version;
status: draft, candidate, stable, deprecated, retired;
owner;
changelog;
compatibility class;
privacy classification;
references to OpenAPI or AsyncAPI documents;
release artifact digest;
deprecation and retirement dates.

Draft schemas must not be silently used as production stable contracts.

Data minimization

A shared schema should not include a field merely because one product might find it convenient.

Before adding a field, ask:

is it necessary for the shared contract;
who controls it;
who may see it;
how long is it retained;
can a derived claim replace raw data;
does it create discrimination or surveillance risk;
can it be removed later without breaking consumers.

Canonical MVP vocabularies

The initial registry should prioritize:

principal and organization references;
product and environment references;
opportunity and assignment;
contribution and review;
evidence package and claim;
consent and authorization grant;
stewardship grant;
payment and ledger references;
governance proposal and decision;
agent task and tool invocation.

Acceptance criteria

The model is ready for implementation when:

every schema has an immutable ID and version;
money and time semantics are explicit;
privacy classes are machine-readable;
canonical records and presentations are separate;
events use a common envelope;
delivery and ordering assumptions are documented;
breaking-change tests exist;
provenance accompanies derived metrics;
deletion, correction, revocation, and supersession are distinct;
unknown enum and extension behavior is defined;
the registry can generate current documentation and artifacts.

Sources

Verification record

Sources opened and checked: 2 August 2026
JSON Schema baseline: Draft 2020-12
CloudEvents baseline: 1.0.2-compatible
Registry implementation: Not yet selected