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.

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 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.