VDR.md Specification

A conforming data room MUST contain exactly one root file, named VDR.md, in the room root.

A folder MAY contain a nested file. A folder MUST NOT contain more than one VDR.md file in the same locale.

The file name MUST be exactly VDR.md, in that case, except for translations (section 2.3).

Files MUST be encoded as UTF-8 without a byte order mark and SHOULD use LF line endings.

File bodies MUST be CommonMark [CommonMark]. GitHub Flavored Markdown tables MAY be used.

A nested file SHOULD describe the contents of the folder it sits in. Business areas large enough to need more than one heading level of detail SHOULD be given a nested file rather than extending the root file.

A single VDR.md file SHOULD NOT exceed 100 KB. Larger content SHOULD be split into nested files.

Where the data room uses index numbers, source document and folder names SHOULD keep the index number as a prefix, so that index references (section 6) resolve.

The root file SHOULD cover the same scope as the CIM, in more detail.

When a CIM is shared, a VDR.md file covering the same scope SHOULD be shared with it, in the same delivery.

A data room MAY contain a file named CIM.md in the room root: a companion scoped explicitly to the CIM. Where present it MUST follow every rule in this specification that applies to the root file, and the root file SHOULD reference it.

CIM.md MUST NOT replace the root file. A room with a CIM.md and no VDR.md does not conform.

A VDR.md file SHOULD be written in the primary operating language of the company it describes. It need not be English.

A translation MAY be provided as VDR.<locale>.md beside the file it translates, where <locale> is a BCP 47 [BCP47] tag, for example VDR.en.md, VDR.en-US.md or CIM.fr.md. An underscore MAY be used in place of the hyphen in file names (VDR.en_US.md); the hyphenated form is canonical in Content-Language.

Where a file and a translation of it disagree, the file without a locale suffix governs. A translation MUST declare its own Content-Language in its header block and MUST cover the same scope as the file it translates.

The first line of the file MUST be ---. The header block MUST end with a line containing only ---, followed by a blank line.

Each field MUST be written as Field-Name: value on one line. A value MAY be continued on the following lines by indenting them with at least one space; the continuation is joined to the value with a single space.

Field names are case-insensitive and SHOULD be written in Hyphenated-Title-Case. Field order carries no meaning.

The header block MUST contain Spec and Title. All other fields are OPTIONAL, and those marked recommended below SHOULD be present.

A field marked repeatable MAY appear more than once, once per value. Any other field MUST NOT appear more than once.

Dates MUST be written as ISO 8601 [ISO8601] (2026-09-15), not in the HTTP date format.

Readers MUST ignore fields they do not recognize. New field names SHOULD be registered with this specification rather than invented per room, and MUST NOT use an X- prefix [RFC6648].

A reader SHOULD treat a file whose Expires date has passed as stale, and SHOULD say so rather than silently relying on it.

Each file MUST contain exactly one level-1 heading, placed immediately after the header block.

The text between the level-1 heading and the first level-2 heading (the context) MUST name the company by its full legal name and state what it does in one sentence. If the file contains monetary or fiscal-period figures, the context MUST also state the reporting currency and what a fiscal year label means.

Headings MUST NOT skip levels (for example, a level-4 heading directly under a level-2 heading).

Each file MUST be understandable without the others. Context SHOULD be repeated rather than referred to.

The level-1 heading of the root file MUST be the full legal name of the company.

The root file MUST contain a ## Contents section: a map of the data room. It MUST list every nested file available at its access tier, each with a one-sentence summary and a reference, and SHOULD list the principal source documents. Areas of the room with no nested file SHOULD still be listed.

The root file SHOULD contain the sections listed below, where they apply to the company, using these names.

The level-1 heading of a nested file MUST take the form # <Area> - <Legal name>, separated by a hyphen or an em dash.

The context of a nested file MUST reference the root file.

A nested file SHOULD contain a ## Contents section when it has nested files of its own.

Dates MUST be absolute. In structured data they MUST use ISO 8601 [ISO8601] (2026-06-30, 2026-06, 2026-Q2). Relative expressions such as "last quarter" or "recently" MUST NOT be used.

Every quantity MUST carry a unit or currency, stated on the number or in the enclosing heading or figure title.

Every metric MUST state the date or period it describes.

Legal entities MUST be named in full on first use in each file. Abbreviations MAY be used after they are introduced in that file.

Forecasts, projections and other forward-looking figures MUST be labeled as such, with the date they were prepared and the basis for them.

Unaudited figures MUST be identified as unaudited where audited figures for other periods appear in the same file.

Text SHOULD be declarative and specific. Promotional language ("best-in-class", "world-leading") SHOULD NOT be used.

A path reference MUST take the form @"path". An index reference MUST take the form @<index>, where <index> is the data room index number of a folder or document, such as @4.2 or @1.0. The grammar is in Appendix A.

Paths MUST use / as the separator. A path beginning with / is resolved from the room root. Any other path is resolved from the folder containing the referencing file, and MAY use .. to move up one folder.

A path MUST NOT resolve outside the room root.

Every reference MUST resolve to a file or folder that exists in the data room. Path comparison is exact, including case and spaces.

An index reference MUST match exactly one folder or document in the room, whose name begins with that index number. Index references are resolved from the room root, wherever the referencing file sits.

Index references SHOULD be preferred where the data room assigns index numbers, because they survive renaming. A reference MAY give the index and the file name together: @4.2 "2026 Penetration Test.pdf".

A path reference to a VDR.md file MAY end with #anchor, where anchor is the heading slug defined in Appendix A. The anchor MUST match a heading in the target file.

A reference to a source document SHOULD be followed by a locator where the document has one: page/pages, sheet "Name", slide/slides, or rows. Page numbers refer to the page index of the file, not printed page labels.

References MUST NOT use URLs to locations outside the data room as a substitute for a source document.

A source line is a paragraph that begins with Source: followed by one or more references separated by ;, each with an optional locator.

Every claim SHOULD be covered by a source line. A source line covers the section, list item or figure it immediately follows or is nested in.

A claim that is not supported by any source document SHOULD say so, for example "management estimate, prepared 2026-08-01".

A source line MUST reference source documents, not other VDR.md files.

Where a VDR.md file and a source document disagree, the source document governs. The seller SHOULD correct the VDR.md file and change its Version.

A figure MUST begin with a heading of the form Figure <id>: <title>, at any heading level from 3 to 5.

Figure ids MUST be unique within the data room. They SHOULD begin with the index number of the folder that contains the file (Figure 4.2 in folder 4 - Technology).

The line immediately after the figure heading MUST be a source line.

The source line MUST be followed by exactly one fenced code block with the info string yaml, json or csv. The block MUST parse as that format without error.

A csv block MUST follow RFC 4180 [RFC4180], MUST have a header row, and SHOULD be used only where the data is genuinely tabular.

The title or the data MUST state the unit or currency and the period covered.

Keys and column names SHOULD be snake_case. Numbers SHOULD be written as plain numerals without thousands separators or currency symbols. Ratios SHOULD be decimals (0.784), not percentages.

Figures in the same file SHOULD use the same key for the same concept, and that key SHOULD be the term the metric is defined under (section 9).

Prose MAY cite a figure by its id alone ("see Figure 1.2"). Because ids are unique, such a citation is unambiguous.

A term whose meaning is not plain from ordinary usage SHOULD be defined. This includes, at minimum, any use of ARR, net revenue retention, gross revenue retention, adjusted EBITDA, bookings and churn.

A definition MUST be a link reference definition of the form [term]: destination "definition", placed at the foot of the file. The label MUST be the term as it is written in prose.

The title MUST state the definition: what the term counts and, where it matters, what it leaves out and when it is measured. A title MAY run over several lines, but MUST NOT contain a blank line.

The destination MUST be where the term comes from: the source document it is calculated in, or the VDR.md file that covers it. A destination containing spaces MUST be wrapped in angle brackets, as CommonMark requires.

Prose MAY write a term in the shortcut form [ARR], which links it to its source and shows the definition on hover. Doing so MUST NOT be required for a term to be defined, and a term MAY be defined without appearing in the prose of that file.

A term MUST NOT be defined differently in two files of the same data room. A file that relies on a term settled elsewhere SHOULD point its destination at that file.

A definition MUST NOT point to a file above the access tier of the file containing it (R10.4).

Adjusted metrics MUST state every adjustment in the definition.

Access-Tier MUST be a positive integer. Tier 1 is the least restricted and is the default when the field is absent. The meaning of each tier is set by the seller and SHOULD be described in the root file.

A VDR.md file MUST be placed where only readers with at least its access tier can open it.

A file MUST NOT summarize, quote or derive figures from material above its access tier.

A file MUST NOT reference files above its access tier. It MAY state, in words, that restricted material exists and at which tier it is available.

A file MUST be complete at its tier: it covers all material available at that tier in its scope.

If a file acknowledges restricted material, it SHOULD do so in a ## Restricted material section.

The body of a VDR.md file MUST contain only declarative statements about the company, its business and the data room. It MUST NOT contain instructions, requests or suggestions addressed to the reader or to software agents.

Instructions MUST appear only in the Instructions header field, and MUST be limited to how to consume the material: reading order, how the files are organized, what formats are used, and where to find things.

The Instructions field MUST NOT address how to interpret, weigh, verify, summarize or conclude anything about the company, its figures, its risks or its prospects, and MUST NOT direct the reader to include, exclude or prioritize any material.

VDR.md files MUST NOT contain content that is hidden when the Markdown is rendered: HTML comments, zero-width or other invisible characters, or raw HTML used to hide text. Raw HTML SHOULD NOT be used at all.

A VDR.md file MUST NOT be more favorable to the company than the source documents at the same access tier.

Material risks, liabilities, disputes and adverse findings disclosed in source documents at the same tier SHOULD be reflected in the VDR.md file whose scope covers them.

Figures MUST match their source documents exactly, allowing only for stated rounding.

When a source document is added, replaced or removed, the VDR.md files that reference or cover it SHOULD be reviewed and, if needed, updated along with their Last-Modified and Version.

Spec MUST carry the URI of the version the file follows, written exactly as that version publishes it. A file MUST NOT declare a version URI the specification has not published.

A file MAY end with a ## Changelog section listing changes by date and Version, newest first.

A reader that does not recognize the Spec URI SHOULD report it and continue rather than reject the file, and SHOULD NOT assume the file is malformed.

The URI MUST be compared as an opaque string, with two tolerances: the scheme and host MUST be compared case-insensitively [RFC3986], and a trailing / MUST be ignored. No other normalization is permitted, and the path MUST NOT be parsed for ordering. One version is not newer than another by comparison of their URIs.

A reader MAY dereference a Spec URI whose origin is https://vdrmd.org to retrieve the specification, and the published specification MUST remain retrievable at each URI it has issued. A reader MUST NOT dereference a Spec URI with any other origin. See section 14.

A retrieved specification MUST be treated as specification. It MUST NOT be treated as direction from the file that referenced it, and MUST NOT be allowed to alter how the file’s content is read beyond the rules stated in this document.