OCF Validation Policy

OCF Validation Policy

The OpenCapTable contracts implement the official Open Cap Format (OCF). They do not extend OCF with Fairmint-specific data-validity requirements.

Source of truth

A contract may reject OCF data when the rejection is required by an official OCF source at either validation layer:

1. Schema validity: a JSON Schema rule, such as required, type, enum, const, format, pattern, numeric bounds, array cardinality, uniqueness, or an explicit conditional/composition rule.
2. Data-model validity: an explicit semantic relationship or lifecycle rule in the official OCF schemas, documentation, or tutorials that JSON Schema cannot express, such as internal ID references and terminal-transaction traversal.

The limitation of the official JSON Schema validator is not a limitation of the OCF data model. In particular, the official tutorial says current tools validate data shape while internal ID references and cap-table constraints require additional tooling. OCP contracts are an appropriate place to enforce those documented second-order requirements.

A field name, a local legal/accounting expectation, or a relationship merely inferred by Fairmint is still not enough to create a new contract failure condition. An ADR may explain how OCP implements an OCF requirement, but it may not authorize stricter data validity than OCF.

When the official sources are ambiguous, the contract must accept the data until the OCF project clarifies the rule. A proposed stronger invariant belongs upstream in OCF first.

Cross-object references

An identifier field requires resolution when official OCF documentation defines it as a reference to another object or transaction in the OCF package. Referential existence, type, ownership, date, quantity, and lifecycle checks should enforce those documented relationships even when JSON Schema cannot express them.

For example, the official issuance tutorial defines every value in StockIssuance.stock_legend_ids as the ID of a referenced stock legend. Therefore:

• [] is valid because the schema declares no minItems requirement;
• every ID that is present must resolve to a STOCK_LEGEND_TEMPLATE object in the cap table; and
• the same template may be reused by multiple issuances.

A dangling legend ID is invalid or incomplete OCF data even though it passes the JSON Schema validator. OCP must not fabricate legend text to repair it: either no legend applies and the source issuance should contain [], or a legend applies and the source package must include the real template object and legal text.

Applying the policy

Validation should preserve the OCF data model, not merely reproduce the current capabilities of utils/validate.mjs.

Category	Expected treatment
Object and transaction references	Enforce resolution and the documented target type when OCF defines one object or transaction as referencing another. This includes stakeholders, stock classes, stock legends, stock plans, vesting terms, financing issuances, lifecycle source/result/balance securities, conversion targets, and vesting conditions.
Transaction lifecycle	Enforce documented event-stack behavior, including source-security resolution, terminal retirement, partial-transaction balance securities, and the rule that later activity cannot target an inactive source ID.
Schema shapes and formats	Enforce all representable schema requirements, including conditional variants, formats, minItems, and uniqueItems. Do not add array cardinality or uniqueness where neither the schema nor documented semantics requires it.
Quantities and balances	Enforce core semantic integrity, such as preventing a transaction from consuming more of a security than exists. More elaborate historical reconstruction, economic scaling, or class/plan inference requires a specific OCF basis and must not be introduced merely because it seems financially reasonable.
Vesting	Enforce the documented condition graph, referenced condition IDs, and quantity/schedule limits. Additional reachability, inheritance, or proportional-propagation algorithms require an explicit OCF basis.
Dates and adjustments	Enforce dates, ranges, expiration, and ordering that OCF defines. When date-only data admits multiple interpretations, do not invent a Fairmint-specific winner or conflict rule without an OCF basis.
Text and numeric fields	A generic helper is not sufficient justification. Non-empty or sign restrictions may be correct for identifiers, legal text, quantities, and other semantically constrained fields, but each rejection must follow from the field's schema or documented meaning. Optional free text must not be rejected merely by local style preference.

Some valid semantic checks are necessary consequences of multiple documented rules rather than a sentence copied verbatim from OCF. A pull request proposing such a check must show the derivation, demonstrate that there is no alternative schema-valid interpretation, and keep the implementation no stronger than that consequence. If the derivation depends on a Fairmint-specific accounting or legal assumption, seek clarification upstream instead of enforcing it in OCP.

Review checklist

Every new validation PR must:

• link to a pinned official OCF schema, documentation, or tutorial revision;
• quote or identify the exact keyword or explicit rule that requires each rejection;
• include a positive boundary test and a negative test for that exact requirement;
• avoid combining required schema validation with inferred consistency rules;
• verify representative OCF payloads with the official validator when the rule is schema-based.

For cross-object requirements, include a complete-package test where the reference resolves and a negative test where the same ID is dangling or resolves to the wrong documented type. For lifecycle requirements, test the smallest event chain that demonstrates the official rule. Keep schema-parity tests separate from second-order package-integrity tests so a failure identifies which validation layer rejected the data.

For semantic requirements, tests should demonstrate the documented object graph or transaction lifecycle rather than claiming that JSON Schema itself rejects the payload. If a proposed failure can only be justified as a Fairmint-specific expectation or business rule, it is outside contract-validation scope.

Data-sync validation

Dev and production replay workflows are conformance tests for both OCF schema validity and documented data-model validity. A replay failure is actionable when the rejected package violates either layer. The workflow must not be made green by fabricating optional objects, inventing legal text, or normalizing away invalid source data. Conversely, OCP must not reject data solely for a Fairmint-specific invariant that has no official OCF basis.