Anatomy of a .deepcell

The first question a careful person asks about a new file format is the correct one: what's inside, and can I get out?

Black-box formats are a moat for the vendor and a trap for the user. You can't audit what you can't read. You can't extract what you can't parse. And "trust us, it's structured" is not a promise worth accepting from anyone whose business model depends on retention.

So .deepcell is the opposite of that. Open one in any text editor and you can read it. It's plain text, not a proprietary binary blob — organized, labeled, human-readable. Standard tools can compare two versions and show you what changed. Nothing is hidden. There are eight sections, each doing one job, and you can read them top to bottom like prose.

The matrix laying out the post you're reading right now is itself a .deepcell. Sixteen blog posts as Items, six finance roles plus three customer segments as Contexts, audience fit as the cell value. No formulas, no reasoning notes — a minimal structure, because that's all this example needed. We'll walk it section by section.

The eight sections#

Header → StatusDefs → ContextDefs → ItemDefs →
CalcDefs → PresentationDefs → Values → Reasoning

CalcDefs and Reasoning are both optional. The matrix file omits them. A 3-statement model uses every section.

1. Header#

Who, what, when. Free text, plainly labeled — the whole section reads as a simple list:

If you remember nothing else, remember this: the title and description are plain text under a plain label. No proprietary encoding. No vendor magic.

2. StatusDefs#

Every value carries a status. In a finance model that's the difference between actual (reported numbers), projected (your working forecast), forecast (an alternate forward path), and any custom label your team needs. The calculation engine uses status to decide which values are visible to which scenario — actuals override projections, and so on.

The matrix file only needs one: a single status labeled "Audience fit."

One axis of meaning. That's all this document does.

3. ContextDefs#

The time-and-scenario axis. In a DCF this is where Q1_2027, Q2_2027, base_case, bear_case live. In the matrix, the "context" axis isn't time — it's audiences. You don't need to read the tags below — the point is only that every audience is plainly labeled:

<ContextDefinitions>
  <Context contextId="SS" level="0" statusRef="fit">
    <Label>Sell-side analyst</Label>
  </Context>
  <Context contextId="BS" level="0" statusRef="fit">
    <Label>Buy-side analyst (public markets)</Label>
  </Context>
  <Context contextId="PV" level="0" statusRef="fit">
    <Label>PE / VC analyst</Label>
  </Context>
  <!-- FPA, CF, IB, Individual, Team, Enterprise ... -->
</ContextDefinitions>

A finance model lays its periods on this same axis. The shape is the same; the labels change.

4. ItemDefs#

The row axis. The line items. In a model these are Revenue, COGS, Gross_Margin — the line items, organized into a hierarchy (up to four levels deep), so the system knows which lines roll up into which subtotals. In the matrix they are blog posts. You don't need to read the tags below — the point is only that every field is plainly labeled:

<Item itemId="post_03" order="30" level="0">
  <Label>[T1] Anatomy of a .deepcell</Label>
  <Description>What's inside the file? Am I locked in?</Description>
  <DataType>category</DataType>
</Item>

level="0" means top-level. A consolidated P&L would put Revenue at level 0, Product_Revenue and Service_Revenue at level 1, and the SKU-level lines under those. The hierarchy is enforced — you can't post a value to a parent if it has children doing the work.

5. CalcDefs#

The matrix has none. It's a literal table; every cell was authored directly. So <CalculationDefinitions/> sits empty:

<CalculationDefinitions/>

In a 3-statement model this section is where the document earns its name. You don't need to read the tags below — the point is only that each calculation plainly names the line it produces and the formula behind it (illustrative — your model will have hundreds):

<Calculation itemRef="Gross_Margin"
             formula="Revenue - COGS"
             scenarioRef="base_case"/>

The engine ships NPV, IRR, SUMIF, IF, and about thirty other functions, works out which cell feeds which, detects circular references, and recomputes on edit. The point isn't the function library — Excel has more. The point is that the formulas live in their own section, separately addressable from the values they produce. That's what makes them auditable.

6. PresentationDefs#

How the data is laid out on screen. One sheet, one block, in this case — a table named "Audience fit by post," with the posts running down the rows, the nine audiences across the columns, from order 10 through 160.

This is what tells the display — the web grid, the Excel add-in, and the export, all drawn from the same underlying blueprint — that items go down, contexts go across, and the block runs from order 10 through 160. Presentation is separate from data. Re-pivoting is a presentation edit, not a model edit.

7. Values#

The cells themselves. Grouped by item and status. You don't need to read the tags below — each line is just one audience and its rating:

<ItemGroup itemRef="post_01" statusRef="fit">
  <Value contextRef="SS">primary</Value>
  <Value contextRef="BS">primary</Value>
  <Value contextRef="PV">primary</Value>
  <Value contextRef="FPA">secondary</Value>
  <Value contextRef="CF">primary</Value>
  <Value contextRef="IB">secondary</Value>
  <Value contextRef="Individual">primary</Value>
  <Value contextRef="Team">primary</Value>
  <Value contextRef="Enterprise">primary</Value>
</ItemGroup>

Read that block out loud and you have the spec for one row of the matrix. "Post 1 is a primary target for sell-side, buy-side, PE/VC, controllers, individuals, teams, and enterprises; a secondary target for FP&A and deal analysts." The file tells you exactly that, in exactly that order.

Every fact in a .deepcell is one of these <Value> elements, addressed by Item × Time × Scenario × Status. Four dimensions. No hidden state.

8. Reasoning#

The matrix doesn't carry any reasoning. A real model does — structured entries for Claims, Assumptions, Evidence, and Arguments, the reasoning behind the numbers, connecting each number to the conviction behind it. The why for the discount rate. The source for the growth curve. The connected map of the reasoning that says this catalyst supports that thesis, and here's the filing it cites.

That's a long enough subject to get its own post. Show your work covers it.

Am I locked in?#

No. You can export to Excel anytime — formulas preserved if you want them, values-only if you don't. The reasoning notes and the edit history can't be stored inside a plain spreadsheet, so they stay behind, but the model itself comes out clean. You can leave whenever you want.

That's the difference between a file format and a platform. We picked the file format on purpose. The full argument is in why a new file format.

See it for yourself — open a sample .deepcell in the playground. Edit a value, watch the dependents recalculate, inspect the reasoning behind any number.