open-cap-table-coalition/open-cap-format-ocf

Open Cap Format (OCF) - The Open Source Company Capitalization Data Standard. OCF can be used to structure and track the complex data structures necessary to build and maintain accurate capitalization (cap) tables.

Open Cap Table Format (OCF)

What is OCF?

OCF (or Open Cap Table Format) is an open source data standard for company capitalization data developed by the Open Cap Table Coalition to enable the easy and accurate exchange and use of company capitalization information through a standardized format.

OCF is a JSON-based format, wherein individual objects required to describe a company cap table are stored in JSONs that match our OCF JSON Schemas. Our reference implementation suggests storing these JSONs in a specific set of files in a zip archive, but OCF-compatible data could be provided via API as well. Please see our documentation for more details on JSON Schema, OCF's schemas or how to use them.

Useful links
Primary Website	Sharable landing site for OCF and the Coalition
Medium Page	Past announcements related to OCF and the Coalition
PROJECTS.md	Collection of public projects in the OCF ecosystem listed in

Documentation

We have extensive, auto-generated documentation available on our documentation page. The documents are automatically updated with every update to OCF.

You an find samples in our repo in the samples folder, or, check out our tutorials (again, through the documentation) to see how to get started with OCF and download complete, sample OCF cap tables.

OCF Schema

OCF's schema is defined in our JSON Schemas, which can be found in the /schema folder of our repository. All of our documentation is automatically generated from these source files, so they should remain in sync.

Contributors (alphabetical)

Please see the Open Cap Table Coalition Website or our GitHub Code Contributors List.

open-cap-format-ocf's Issues

Automate document generation -- integrated with github?

Select a Test Framework and Build Basic Tests for Example Files

Re-write the Security object examples as Issuance object examples

Add copyright notices as a `$comment` field in all schema files.

Let's add the copyright notices as a $Comment field in all schema files.

Originally posted by @JSv4 in #111 (comment)

additionalProperties:false on each leaf object

Model Transfer Transaction Obj(s) in JSON Schema

Use regex pattern matching for numeric string_value, and possibly remove nested structure for this type

From PJ's PR, regarding the Numeric type:

I understand that we used strings here because these values are decimal values, so we can't rely on JS number type. Might we want to eliminate the nested object by using string format regexes? https://json-schema.org/understanding-json-schema/reference/string.html#id16

Turn ids and refs into URIs at https://opencaptablecoalition.com

Model Split Transaction Obj(s) in JSON Schema

Which arrays on which objects should have uniqueItems or minItems enforced?

Model Acceptance Transaction Obj(s) in JSON Schema

Create percentage type to use for numeric fields that should be 0-100%

See #63 (comment) and
#63 (comment)

We should standardized on 0.0 to 1.0 or 0.0 to 100.0

Model Exercise Transaction Obj(s) in JSON Schema

GitHub Missing Issue Templates

Couple issues with the GitHub issue template need to be corrected.

Run the test_snapshot.py as a github action

Should we add regex patterns for Email and Phone types?

Just putting this thought down before I forget. These are currently unvalidated free-text fields

Define "Security" formally

Most transaction objects reference something, called "security id" (defined as "Identifier for the security which the transaction applies to"). For example: Stock Issuance Transaction. However, I can't find the formal definition of what this "Security" is or what fields it consists of. I'd find it useful to have some kind of pointer to the definition of "Security" in the descriptions of fields, referencing it.

Have examples of ALL 30 types of transactions in the test file

Model Cancellation Transaction Obj(s) in JSON Schema

The `anyOf` block related to the `compensation_type` field in `PlanSecurityIssuance.schema.json` is not working

The following anyOf block found in the PlanSecurityIssuance.schema.json file is trying to impose:

• if the compensation_type is "OPTION", then the option_grant_type field must be set
• otherwise, if the compensation_type is "RSU", then no additional requirements are needed

Open-Cap-Format-OCF/schema/objects/transactions/issuance/PlanSecurityIssuance.schema.json

Lines 69 to 85 in 9fbaa83

	"anyOf": [
	{
	"properties": {
	"compensation_type": {
	"const": "OPTION"
	}
	},
	"required": ["option_grant_type"]
	},
	{
	"properties": {
	"compensation_type": {
	"const": "RSU"
	}
	}
	}
	],

This doesn't seem to work as intended. In #66, I tried adding an example TX_PLAN_SECURITY_ISSUANCE transaction object that had "compensation_type" : "OPTION" and "option_grant_type": "ISO" but this failed validation.

Evaluate Multi-File Format Options and Implement If Desired

Add License

We should have a license, at least for when we go public?

[Enhancement]: Remove required field "comments" from OCFManifestFile.schema.json

Description of Enhancement :

Remove "comments" from the list of required fields on the OCF Manifest File.

Why is this Needed?

This is an inconsistency with the remainder of the spec.

Anything else we need to know?

Model Issuance Transaction Type(s) in JSON Schema

NOTE: This requires rolling the existing Stock, Plan Security, Convertible and Warrant schemas into the issuance transactions per our discussion on 11/23/21.

All Public Comments from Google Doc Incorporated to GitHub Discussions and/or Issues

We have received some comments from members on the original "snapshot" spec. Once we finish the release with the transactions, we should take a look at these and create either issues or discussion items for substantive points of feedback.

The structure of the Money object should not be amount.amount.stringValue, could just be amount.stringValue

Add Transaction Examples Back in New Style OCF Format

We need to add back the examples that Tyler and Patrick put in, into the new multi-file structure. Right now the example transactions file (Transactions.ocf.json) does not have a TX_CONVERTIBLE_ISSUANCE to verify this.

Model Acceptance Transaction Obj(s) in JSON Schema

In TX_CONVERTIBLE_ISSUANCE, should conversion_discount and conversion_fixed_ownership be mutually exclusive?

Unclear if this should be a oneof relationship. Need to create issue for this.

Originally posted by @tmccnnll in #63 (comment)

Should we use regex pattern for ratio type?

Jake's question in issue #58 got me thinking we might want to use a regex pattern or ratios too? Our regex string types are very easy work with, and, right now, ratio requires a JSON with two properties - antecedent and consequent. Do we just want to have a regex that's essentially two numeric strings with a dividing slash?

Use ISO 3166 alpha-2 for all country codes

From: #66 (comment)

Standardize on ISO 3166 alpha-2 for all country codes used in the OCF. Add maximum length == 2 to all country code fields.

Better Docs

The current jsonschema2md output is verbose and therefore less useful. @JSv4 has some ideas for how to make simpler that are formulaic in nature. We can explore a post-process of jsonschema2md output to conform to his ideas.

Refactor Python-based Document Generator to JavaScript

Rather than reverse engineer JsonSchema2Md, which is designed to handle any possible, valid JSONSchema, it turns out it's a lot easier to just build our documentation by traversing our schemas. We know how our schemas are constructed, so we can just build a purpose-built crawler to extract schema features and create documentation exactly as we want it. Need to refactor to JS, however.

Model Retraction Transaction Obj(s) in JSON Schema

Explore Composition-based Approach

Due to how JSONSchema validates schemas, we need to repeat all of the "inherited" properties. We want to explore flattening this so that intermediate objects would also repeat all of the properties incorporated via allOf. Also, we'd like to look at listing all of the primitives incorporated at each level rather than just the immediately preceding parent.

Model Repurchase Release Transaction Obj(s) in JSON Schema

Please refer to the group google doc for more details on the schema.

Model Reissuance Transaction Obj(s) in JSON Schema

Add Github issues templates and other repo niceties

• issues templates for:
  • bugs
  • enhancements
  • discussions
• PR template
• CODEOWNERS file

Add validations against ISO enumerations?

Where we specify certain ISO formats, do we want to preload an enum type with all matching values (or, if possible, reference a remote schema so we don't have to update the list) so that we can make sure valid values are provided?

Create inheritance structure for objects and transactions to avoid duplication of common properties

Switch to built-in json date and date-time string formats instead of our DateTime type using epoch_millis

Repeat the required properties from all incorporated primitives for readability

Change the naming convention for $id to match file names

Discussed in #117

^{Originally posted by pjohnmeyer March 8, 2022}
Some schema loaders support loading schemas from a "prefix":

https://opis.io/json-schema/2.x/php-loader.html#registerprefix-method

Currently, our IDs and our filenames don't match, e.g.:

file: .../schema/enums/CompensationType.schema.json
$id: https://opencaptablecoalition.com/schema/enums/compensation_type

If we make the $id values match the file path, in this case https://opencaptablecoalition.com/schema/enums/CompensationType.schema.json, it will enable simpler schema loading.

Regenerate Documentation

Model Repurchase Transaction Obj(s) in JSON Schema

Run prettier pre-commit

Aumni team to look into basic GitHub action for this.

Model Conversion Transaction Obj(s) in JSON Schema

Rewrite old sample security objects as issuances.

Our old sample cap table file had arrays of sample warrants, plan issuances, convertibles and stock. These are no longer valid OCF, so the sample wouldn't validate. I removed these for now, but we'll want to go in and rewrite these as issuance transaction objects.

Fix Typos in Base Issuance

There are a couple references to "convertibles" in the base schema that are being carried through all of the documentation as a result. Please fix.

Add ObjectType enumeration so we can tell which objects represent which transaction