OpenNV Contracts

Public, versioned integration contracts for OpenNV Validation and CliSynth. Neither product imports the other's private packages or database collections; they communicate through these schemas and the execution-backend API.

Included contracts

• canonical inventory devices and snapshots;
• nested all / any / not selectors;
• command and validation run requests, including optional pinned baseline runs;
• per-device current and baseline evidence with four-state validation outcomes;
• execution-backend requests used by real Nornir and CliSynth workers;
• OutputFSM definitions and declarative current, exact, diff, percentage- deviation, bounded-custom, and nested-composite validations;
• lifecycle event envelopes;
• an OpenAPI 3.1 description of the initial HTTP boundary.

Verify

npm ci
npm test

The default test gate expects outputfsm-packs and validation-packs as sibling checkouts. You can point at other checkouts explicitly:

OPENNV_OUTPUTFSM_PACK_ROOT=/path/to/outputfsm-packs \
OPENNV_VALIDATION_PACK_ROOT=/path/to/validation-packs \
npm test

The gate compiles every schema in strict mode, validates all examples, checks OpenAPI references, validates all 160 OutputFSM and 160 Validation documents, requires exactly 20 linked commands for each supported platform, and proves the contract dialects match the pack-local schemas. A missing pack checkout is a failure, not a silent skip.

Contracts use semantic versioning. Additive optional fields are normally minor changes. Removing fields, narrowing accepted values, making optional data required, or changing field meaning requires a major version. See GOVERNANCE.md before proposing a compatibility change.

Trust boundary

These schemas describe data, not permission. Implementations must still enforce authentication, authorization, admission budgets, secret references, tenant isolation, and Starlark resource limits. Never put credentials or private keys in a contract payload.

Project policies

• CONTRIBUTING.md — development and compatibility gates
• GOVERNANCE.md — authority, decisions, and releases
• SECURITY.md — private vulnerability reporting
• CODE_OF_CONDUCT.md — community expectations
• docs/development-context.md — repository boundaries and maintainer context