Dark Matter Docs

Position Object schema structure: canonical, conditional, and planned fields, vehicle class variations, and versioning.

The atomic unit of ownership

The Position Object is the atomic unit of ownership in DMTR. Every private position — SPV LLC interest, fund LP interest, direct holding — is represented as a single Position Object. It is the canonical, machine-readable encoding of rights, restrictions, obligations, and compliance state.

The Position Object is to DMTR what the charge object is to Stripe or the account object is to Plaid — the central primitive around which all operations are built.

Schema structure

The schema is organized into logical blocks:

Property	Type	Required	Description	Example
entity_id	string	Yes	Unique identifier for this position. Pattern: lowercase-alphanumeric with hyphens.	—
version	integer	No	Schema version number. Increments on every mutation.	—
status	enum	Yes	Lifecycle state: draft, registered, active, encumbered, transferred, exited, voided.	—
asset	object	Yes	Issuer identity, vehicle class, underlying company, vintage, terms hash, and governing document ID.	—
owner	string	Yes	Participant ID of the beneficial owner.	—
economic_rights	object	No	Preference, carry schedule, waterfall mechanics. Conditional on vehicle class.	—
transfer	object	Yes	Transferability flag, restrictions array, and consent chain.	—
compliance	object	No	KYC/AML status, accreditation requirements, ITAR/CFIUS flags, eligible jurisdictions.	—
valuation	object	No	Current mark, cost basis, provenance, and as-of date.	—
encumbrances	array	No	Active liens, pledges, security interests, UCC filings, and control agreements.	—
tokenization	object	No	On-chain representation status, contract address, token standard (ERC-3643, ERC-1400).	—
provenance	object	No	How the position was acquired: primary issuance, secondary transfer, or split.	—
metadata	object	No	Arbitrary key-value pairs for client-specific data.	—

Interactive schema explorer

Expand fields to browse the full Position Object schema. Fields are labeled by maturity level: Canonical (stable, safe for production), Conditional (present when conditions are met), and Planned (in design, do not depend on).

Position Object Schema

DMTR Position Object — the canonical representation of a private market position.

Canonical core fields

Canonical fields are stable and guaranteed across all vehicle classes:

entity_id — Unique identifier matching ^[a-z][a-z0-9\-]+$
status — One of: draft, registered, active, encumbered, transferred, exited, voided
owner — Participant ID of the beneficial owner
asset.issuer — Legal entity name, optional ref, LEI, and jurisdiction
asset.vehicle_class — One of: lp_interest, gp_interest, doiv_gp_interest, doiv_lp_interest, doiv_membership_interest, spv_llc, fund_lp, direct, feeder, other
asset.terms_hash / asset.governing_document_id — Cryptographic binding to the governing legal document
transfer.transferable — Boolean gate for all transfer operations
transfer.restrictions — Array of typed restrictions (lockup, ROFR, ITAR, CFIUS, Reg D, etc.)

Gotcha: entity_id is immutable after registration. If you need to correct an entity_id, void the original position and create a new one. The event log will link them via the void event's replacement_entity_id field. Lifecycle events are stored as separate PositionEvent records with hash chain integrity — not embedded on the position itself.

Conditional fields

Conditional fields appear when certain conditions are met:

economic_rights.carry — Present for fund positions with carry terms
economic_rights.waterfall — Present when waterfall logic is documented
valuation — Present when a mark has been recorded
encumbrances — Present when liens, pledges, security interests, UCC filings, or control agreements exist
compliance.itar_sensitive / compliance.cfius_covered — Present when the underlying asset involves controlled technology or covered transactions
compliance.eligible_jurisdictions — Present when jurisdictional restrictions apply
tokenization — Present when on-chain representation has been initiated or completed
provenance — Present for positions created via secondary transfer or split

Vehicle class variations

Vehicle Class	Key Differences
`lp_interest`	Limited partner interest in a fund vehicle
`gp_interest`	General partner interest with carry and control terms
`doiv_gp_interest`	GP interest in a Deal Originator Investment Vehicle (DOIV) LLC
`doiv_lp_interest`	LP interest in a DOIV LLC
`doiv_membership_interest`	Membership interest in a DOIV — the transferable unit layer
`spv_llc`	Single-asset SPV LLC, SPV-level consent, direct issuer
`fund_lp`	Capital account, distribution, carry, fund-level consent chain
`direct`	Simplest structure, direct equity or debt
`feeder`	References a master fund, may inherit restrictions
`other`	Catch-all for non-standard vehicle types

Versioning model

Position Objects are versioned. The version field increments on every mutation. Schema evolution follows semver:

Patch: New optional fields, description changes
Minor: New conditional fields, enum value additions
Major: Required field changes, type changes (with migration window)

Query the schema version via GET /v1/schema/position or check the X-Schema-Version response header on any position endpoint.

Example: SPV LLC position

{
  "entity_id": "meg-2026-047",
  "version": 3,
  "status": "active",
  "owner": "participant-gp-001",
  "asset": {
    "issuer": { "name": "Acme DOIV LLC", "ref": "acme-doiv", "jurisdiction": "US-DE" },
    "vehicle_class": "doiv_membership_interest",
    "underlying": { "company": "Acme Corp", "sector": "defense", "security_type": "preferred_equity" },
    "vintage": "2026-01-15",
    "terms_hash": "sha256:a1b2c3d4e5f6789012345678901234567890abcdef",
    "governing_document_id": "doc-oa-acme-001"
  },
  "economic_rights": {
    "preference": "pari_passu",
    "cost_basis": "4200000",
    "sharing_percentage": 0.25,
    "carry": { "rate": 0.20, "gp_rate": 0.05, "deal_originator_rate": 0.15, "schedule": "deal_by_deal", "adjudication": "deal_by_deal", "carry_on_transfer": "passthrough" }
  },
  "transfer": {
    "transferable": true,
    "restrictions": [
      { "type": "lockup", "expires": "2027-01-15T00:00:00Z" },
      { "type": "itar_restriction", "note": "ITAR-controlled underlying; buyer must be US person" },
      { "type": "reg_d_506b", "no_general_solicitation": true }
    ],
    "consent_chain": [{ "party": "GP Holdings LLC", "role": "general_partner", "required": true, "timeout_days": 10 }]
  },
  "compliance": {
    "kyc_status": "cleared",
    "aml_status": "cleared",
    "accreditation_required": true,
    "itar_sensitive": true,
    "eligible_jurisdictions": ["US"]
  },
  "valuation": {
    "current_mark": { "value": "5000000", "currency": "USD", "as_of": "2026-03-01", "provenance": "gp_mark" },
    "cost_basis": "4200000"
  },
  "encumbrances": [],
  "tokenization": { "status": "not_tokenized" },
  "provenance": { "acquired_via": "primary" },
  "metadata": {}
}

This DOIV membership interest has pari-passu preference, GP consent required for transfer with a 10-day timeout, a lockup expiring January 2027, ITAR and Reg D 506(b) restrictions, and cleared KYC/AML for US jurisdiction only. The governing_document_id binds this position to its Operating Agreement in the document registry; terms_hash provides an additional cryptographic integrity check. Lifecycle events are stored as separate PositionEvent records with hash chain integrity.

Lifecycle — Position state transitions
Transferability — Transfer rules and restrictions
Positions API reference — Full schema reference

Position Object

Position Object Schema

On this page