Conversation
…onformance Introduces the OCIP (Open Cap-Table Improvement Proposal) process and its first proposal: - OCIP/README.md — what an OCIP is, how to propose one, current proposals index - OCIP/proposals/0000-template.md — front-matter schema, lifecycle states, naming conventions - OCIP/proposals/0001-ocf-extension-architecture.md — the extension mechanism - OCIP/registry/profiles.json — empty seed for the profile registry OCIP-0001 defines a three-tier extension architecture for OCF: 1. Core (the kernel, cap-table-complete) 2. Profiles (named, versioned, coalition-governed extension packages) 3. Vendor extensions (reverse-DNS namespaced, unreviewed) Key design decisions: - Extensions live in separate files, cross-referencing Core records by ID (one-directional: extensions reference Core, never the reverse) - A Core-only consumer produces the identical cap table with or without extensions present (graceful blindness by construction) - Producer/consumer conformance split (a producer must emit valid data, a consumer must parse without breaking) - Standard validation mode: unknown profiles warn, known profiles validate strictly, namespace violations error - Profiles graduate to Core via a new OCIP (schema.org pending -> core model) - Registry lives in this repo as a machine-readable JSON file The proposal cites the TWG's own generated artifacts (core-lossy-inventory.md, core-unmapped-inventory.md, carta-schema-refresh-2026-06-22.md, Explainer.md) and draws on precedent from IETF RFCs, Kubernetes API groups, Schema.org extensions, JSON Schema vocabularies, and Ethereum EIPs. Co-authored-by: Cursor <cursoragent@cursor.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c4be906a3b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **Cross-reference rule:** extension records reference Core records by their Core ID (`stakeholder_id`, `security_id`, `transaction_id`). Core records never reference extensions. This guarantees the invariant: | ||
|
|
||
| > **A Core-only consumer parsing a document that contains extensions produces the identical Core cap table as if the extensions were absent.** |
There was a problem hiding this comment.
The graceful-blindness guarantee is unsafe for the profile scope defined here: the proposal explicitly treats splits as unmapped candidates and permits profiles to add transaction types, but a stock split changes quantities obtained by traversing the transaction stack. If that event exists only in a profile file, a Core-only consumer skips it and reports unsplit holdings, so Core is no longer cap-table-complete. Profiles must be restricted to non-economic metadata, or every economically effective event must also have a Core representation.
Useful? React with 👍 / 👎.
| "files": [ | ||
| { "path": "stakeholders.json", "sha256": "..." }, |
There was a problem hiding this comment.
This proposed files array is not additive to the current OCF v1 manifest as claimed later in the proposal. schema/files/OCFManifestFile.schema.json requires categorized fields such as transactions_files and stakeholders_files, represents entries as {filepath, md5}, and sets additionalProperties: false; consequently the documented files, profiles, and vendor_extensions fields cause the reference validator to reject a package. Define a versioned manifest-schema change or extend the existing categorized shape before presenting this as a conformant package.
Useful? React with 👍 / 👎.
| created: 2026-09-22 | ||
| type: Standards Track | ||
| area: core | ||
| requires: stable identifiers on transaction records (see "Prerequisite" section) |
There was a problem hiding this comment.
The template defines requires as an OCIP number, but this value is free text, so process tooling cannot resolve the dependency. The prerequisite section later calls the stable-identifiers proposal OCIP-0002, while the registry example assigns OCIP-0002 to holder identity, violating the new rule that proposal numbers are never reused. Assign the prerequisite a unique number and place that number in requires.
Useful? React with 👍 / 👎.
| - `status` — one of `draft`, `review`, `accepted`, `deprecated`, `superseded` | ||
| - `schema` — path to the JSON Schema for this profile's types | ||
| - `spec` — path to the OCIP that defines it | ||
| - `requires_core` — minimum Core version | ||
| - `owner` — `coalition` for ratified profiles; a vendor name for vendor extensions (vendor extensions appear in the registry with `status: "vendor"` and are not reviewed) |
There was a problem hiding this comment.
The registry contract limits status to five values here, but four lines later requires registered vendor extensions to use status: "vendor". Any registry schema or consumer implementing the stated enumeration will reject entries that the same specification requires for vendor discovery. Either add vendor to the allowed statuses or keep vendor extensions outside this registry.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Critical cap-table guarantees and multiple specification inconsistencies remain unresolved.
Get a fresh assessment by requesting another Copilot review.
Review effort: Balanced
Findings: 1
Open (7)
What changed in this PR
Introduces the OCIP proposal process and a draft OCF extension architecture for profiles, vendor extensions, registries, and conformance.
Changes:
- Adds OCIP lifecycle and authoring documentation.
- Defines extension, validation, dependency, and conformance models.
- Seeds an empty profile registry.
| File | Description |
|---|---|
OCIP/registry/profiles.json |
Initial empty profile registry |
OCIP/README.md |
OCIP process and proposal index |
OCIP/proposals/0001-ocf-extension-architecture.md |
Draft extension architecture specification |
OCIP/proposals/0000-template.md |
Proposal template and lifecycle rules |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| **Cross-reference rule:** extension records reference Core records by their Core ID (`stakeholder_id`, `security_id`, `transaction_id`). Core records never reference extensions. This guarantees the invariant: | ||
|
|
||
| > **A Core-only consumer parsing a document that contains extensions produces the identical Core cap table as if the extensions were absent.** | ||
|
|
||
| This is the graceful-blindness property. It holds by construction (separate files, one-directional references), not by discipline. |
| created: 2026-09-22 | ||
| type: Standards Track | ||
| area: core | ||
| requires: stable identifiers on transaction records (see "Prerequisite" section) |
|
|
||
| - `id` — the dotted profile ID | ||
| - `version` — semver | ||
| - `status` — one of `draft`, `review`, `accepted`, `deprecated`, `superseded` |
| "files": [ | ||
| { "path": "stakeholders.json", "sha256": "..." }, | ||
| { "path": "securities.json", "sha256": "..." }, | ||
| { "path": "transactions.json", "sha256": "..." }, | ||
| { "path": "profiles/ocf.holder-identity/holders.json", "sha256": "..." }, |
|
|
||
| 1. **Extensions reference Core by ID.** An extension record may reference `stakeholder_id`, `security_id`, or `transaction_id` from Core. Core never references an extension. | ||
| 2. **Extensions are additive.** An extension may not redefine, override, subtract, or rename a Core field or type. It may only add new records that reference Core records. | ||
| 3. **Extensions may depend on other extensions.** A profile may declare `requires_profiles` in its schema (e.g., `ocf.transfer-lineage` might require `ocf.holder-identity`). The validator checks that all declared dependencies are present in the manifest. |
| OCF standard. It follows the same conventions as IETF RFCs, Python PEPs, and Ethereum EIPs: | ||
|
|
||
| - Each proposal has a number (assigned sequentially, never reused). | ||
| - Each proposal has a status (`Draft` → `Review` → `Accepted` → `Superseded` / `Rejected`). |
| status: Accepted (template — not a normative proposal) | ||
| author: Thibauld Favre (thibauld@fairmint.com) | ||
| created: 2026-09-22 | ||
| type: Process |
What this adds
Introduces the OCIP (Open Cap-Table Improvement Proposal) process and its first proposal.
Files
OCIP/README.mdOCIP/proposals/0000-template.mdOCIP/proposals/0001-ocf-extension-architecture.mdOCIP/registry/profiles.jsonOCIP-0001 in one paragraph
Defines a three-tier extension architecture for OCF:
ocf.holder-identity,ocf.transfer-lineage,ocf.acceptance-events)com.fairmint.*), unreviewedKey design decisions:
Why now
The TWG's own gap analysis (
OCF-Composed-Schemas) shows 185 OCF properties with no destination in the proposed Core, and entire transaction categories (acceptances, splits, document references, exemptions) that land nowhere. The current "OCF Extended" layer has no schema, no namespacing, and no governance — the extension mechanism is the agreed next work item from the Sept 17 TWG call.Prerequisite
This proposal presupposes that Core transaction records carry stable identifiers (
id). If the proposed Core does not requireidon transaction types (as is currently the case in theOCF-Composed-Schemasbundle), the extension mechanism cannot function — extension records have nothing to reference. This is flagged in the proposal's "Prerequisite" section and is the subject of a companion proposal (stable identifiers on transaction records).Precedent
IETF RFCs (numbered, lifecycle states), Kubernetes API groups + CRDs (namespaced extensions with first-class validation), Schema.org (core / hosted extensions / pending → core graduation), JSON Schema
$vocabulary(unknown keywords ignored, not rejected), Ethereum EIPs/ERCs (composable interfaces, explicit declaration viasupportsInterface).Not in this proposal
This OCIP defines the mechanism only. Individual profiles (holder-identity, transfer-lineage, acceptance-events, corporate-actions, etc.) will be separate OCIPs (0002+), each specifying its schema, conformance tests, and profile-specific fields.
Note
Low Risk
Adds draft governance and specification markdown plus an empty JSON registry; no production code or breaking runtime behavior in this repository.
Overview
Introduces a new
OCIP/tree: a numbered proposal process (README +0000-template) and OCIP-0001 (Draft), which specifies how OCF extends beyond Core via coalition profiles (ocf.*), vendor extensions (com.vendor.*), aregistry/profiles.jsoncatalog, and optionalprofiles/vendor_extensionsentries in the package manifest.The proposal adds normative design rules: extension data in separate files under
profiles/, one-way references from extensions to Core IDs (graceful blindness for Core-only consumers), producer vs consumer conformance, three validator modes (lenient / standard / strict), profile lifecycle and graduation into Core, and dependency/DAG constraints. It seeds an empty registry (version0.1.0, no profiles yet) and explicitly depends on stable transactionids in Core (flagged as a companion OCIP). No schemas, validators, or concrete profiles are implemented in this PR—only the mechanism and process docs.Reviewed by Cursor Bugbot for commit c4be906. Bugbot is set up for automated code reviews on this repo. Configure here.