Contracts v1

This page lists the versioned JSON Schema contracts (draft 2020-12) of the Navin Platform, explains their versioning rules and shows how to validate a document with the API, each SDK and the CLI. The schemas are stored in contracts/v1/, indexed by contracts/index.json, with one example per contract in contracts/examples/. The Control Plane, the portal, every SDK and the CLI use the same files: models are generated from them and documents are validated against them.

Version française : contracts.fr.md

Catalog

28 contracts, plus common.schema.json for the shared definitions. Type manifest documents are applied through the Control Plane (GitOps or API) and carry a kind; document and event types are exchanged by the services.

Contract	Type	Purpose
common	definitions	Shared building blocks reused by every v1 contract: ids, timestamps, money, classification.
agent-manifest	manifest (Agent)	Identity, version, tools, models, permissions, autonomy and budgets of an agent.
model-manifest	manifest (Model)	Model Registry entry: provider, modalities, limits, reasoning, prices and policies.
tool-manifest	manifest (Tool)	Schema, action, scopes and classification of a tool executed through the Tool Gateway.
skill-manifest	manifest (Skill)	Versioned, signed skill: instructions, dependencies and permissions.
plugin-manifest	manifest (Plugin)	Sandboxed OCI plugin or complete business pack installed through the Marketplace.
connector-manifest	manifest (Connector)	Integration with a business system: authentication, scopes, resources and synchronization.
channel-manifest	manifest (Channel)	Exposure channel (web, mobile, e-mail, messaging, voice): auth, transport, limits and sessions.
managed-component	manifest (ManagedComponent)	One component of the distribution: pinned version, licence, dependencies, secrets by reference, health.
execution-contract	document	State of an agent run: states, steps, budgets, errors and resume strategy.
context-contract	document	Context assembled for one model call: sources, classification, token budget and provenance.
memory-contract	document	A memory item: ACL, TTL, write provenance and deletion rules.
evaluation-contract	document	Dataset, metrics, thresholds and results of an evaluation; a blocking gate prevents promotion.
policy-contract	document	Input (resource, action, subject, context) and decision of a policy evaluation.
multimodal-contract	document	Media handled by the Multimodal Gateway: type, duration, resolution, storage, classification, DLP, costs.
license-entitlement	document	Payload of a platform licence signed by the publisher (annual or triennial term).
execution-context	document	Identity, delegation and governance context of an execution, signed by the Context Authority.
action-context	document	One governed action: request, subject, target, argument digest, decisions, obligations, approval.
delegation-context	document	A delegation of rights to an agent, an application or a sub-agent, always covered by its parent.
approval-request	document	A human approval with four eyes and separation of duties.
security-incident	document	A SOC incident: correlated detections, risk verdict and response.
containment-order	document	One typed reaction on one typed target with a controlled blast radius and the kill switch states.
storage-profile	document	Client object storage (S3, Azure Blob, GCS, IBM COS, SeaweedFS): target, credential reference, purposes.
usage-event	event	One consumption event: units, model, price at call time, currency, estimated, measured and billed cost.
audit-event	event	Who did what on which resource, the policy decision and the evidence; hash chained per tenant.
policy-decision	event	One authorization decision: relationship check, policy decision and effective permission.
tool-invocation	event	A tool or MCP call under an execution context: tool, argument digest, authorization, result.
llm-invocation	event	A model call through the Model Gateway: model, provider, region, classification, usage and cost.
data-access-context	event	A data or RAG access: source, tenant filter, ACL, classification ceiling, documents returned.

Versioning rules

• Every document carries schema_version (1.0, 1.1...). The folder v1 is the major version.
• Minor versions only add optional fields or enum values; objects with additionalProperties: false never get new fields in a minor version.
• Removing or renaming a field, changing a type or making a field required is a major change: a new contracts/v2/ folder, and the API keeps serving v1 for at least 12 months.
• Enum additions (for example a new usage_type) are minor; consumers must handle unknown values gracefully.
• Money is always a decimal string plus an ISO 4217 currency; timestamps are RFC 3339 UTC.
• Changes go through review, CI validation of every example and a changelog entry.

Validation

1. On the server. GET /v1/contracts lists the schemas, GET /v1/contracts/{name} returns one and POST /v1/contracts/{name}/validate answers {valid, errors[]}; POST /v1/manifests/apply validates before any registry change.

2. With the CLI, before a commit or in CI. Exit code 1 when a document is invalid.

   enterprise-ai validate -f ./manifests/agent.yaml --output json

3. Offline, in each SDK, with the schemas bundled in the package (no network, same result as the server).

SDK	Server call	Offline validation	Result
Python	client.contracts.validate(name, document)	enterprise_ai.contracts.validate(document, name=None)	ValidationResult (valid, errors, raise_for_errors())
TypeScript	client.contracts.validate(name, document)	validateContract(name, doc, locale), validateManifest(doc)	{ valid, errors: { path, message, keyword }[] }
Go	client.Contracts.ValidateRemote(ctx, name, body)	client.Contracts.Validate(name, doc), eai.ValidateContract(lang, name, doc)	eai.ValidationResult (Contract, Valid, Errors)
Java	client.contracts().validateRemote(name, body)	client.contracts().validate(name, document), validateManifest(manifest)	ValidationResult record (contract, valid, errors)

from enterprise_ai.contracts import validate

document = {"schema_version": "1.0", "event_id": "use_01J"}
remote = client.contracts.validate("usage-event", document)  # the server answers {valid, errors}
local = validate(document, "usage-event")  # offline, bundled schemas
print(local.valid, [str(issue) for issue in local.errors])

import { validateContract } from "@enterprise-ai/sdk";

const local = validateContract("multimodal-contract", doc);
if (!local.valid) console.log(local.errors.map((e) => `${e.path}: ${e.message}`));

res, err := client.Contracts.Validate("usage-event", doc)
if err != nil {
	return err
}
fmt.Println(res.Valid, res.Errors)

ValidationResult r = client.contracts().validate("evaluation-contract", doc);
if (!r.valid()) { r.errors().forEach(System.out::println); }

Without a name, the Python and TypeScript manifest validators detect the contract from the kind of the document.

Example: Usage Event

{
  "schema_version": "1.0",
  "event_id": "use_01J",
  "occurred_at": "2026-10-29T10:00:01Z",
  "tenant_id": "8f0c2a4e-1b7d-4c55-9a51-2f3e6d7c9b10",
  "agent_id": "agt_ap",
  "session_id": "ses_9",
  "task_id": "tsk_3",
  "usage_type": "llm",
  "provider": "openai",
  "model_id": "gpt-4o-mini",
  "region": "eu-west",
  "units": {"input_tokens": 812, "cached_input_tokens": 512, "output_tokens": 240, "reasoning_tokens": 120},
  "pricing": {"pricing_version": "openai-2026-10-01", "currency": "USD", "effective_at": "2026-10-01T00:00:00Z", "reasoning_billing": "included_in_output"},
  "cost": {"estimated": {"amount": "0.000310", "currency": "USD"}, "measured": null, "billed": null},
  "source": "litellm"
}

FinOps rule: input_tokens includes the cached tokens and output_tokens includes the reasoning tokens.

Reference

• Schemas: contracts/v1/, index contracts/index.json, examples contracts/examples/.
• API v1 of the Control Plane and the SDK guides (overview).