# Redline format

> The markdown rendering behind text_url: change elements, attribution, and worked examples.

Every ready comparison, merged document, and version history carries a `text_url`: the same
redline rendered as markdown with its changes marked inline. It exists so an agent can read
the changes directly, instead of unzipping a `.docx` or re-deriving the diff from the source
documents.

It is working material for analysis, not a deliverable. Hand a person the Word or PDF
redline from the download manifest; give the model this.

## The self-describing header

Every file opens with the same header. It is an HTML comment, so markdown renderers hide it
while anything reading the file as text still sees it — which means an agent that reaches a
saved copy, a cached path, or a file from an earlier session can still read it correctly
with no other context.

```html
<!--
Version Story serialized redline. Generated for agents to read; it is working material for
analyzing the changes, not a document to deliver to a user.

This is the full text of a compared, merged, or version history document with its tracked
changes inline. Text outside a change element is unchanged text.

  <ins id="18" author="..." revision="..." date="...">text</ins>   added in the revision
  <del id="19" author="..." revision="..." date="...">text</del>   removed from the base version
  <moved-from move-id="1" id="20" ...>text</moved-from>            where moved text used to be
  <moved-to move-id="1" id="21" ...>text</moved-to>                where that same text now is
  <conflict id="1">...</conflict>                                  competing changes from different
                                                                   revisions (merged documents only)
-->
```

## Change elements

| Element | Meaning |
| --- | --- |
| `<ins id="18" author="..." revision="..." date="...">` | Text inserted in the revision |
| `<del id="19" author="..." revision="..." date="...">` | Text deleted from the base version |
| `<moved-from move-id="1">` / `<moved-to move-id="1">` | The two halves of one relocation, tied by a shared `move-id` |
| `<conflict id="1">` | Competing changes from different revisions over the same text — merged documents only |

`author` is who made the change; `revision` is the document version it came from, so in a
merged or version-history document every change says which draft introduced it. Text outside
a change element is unchanged.

On `<ins>`, `<del>`, `<moved-from>`, and `<moved-to>`, `id` is the tracked revision's own
identifier in the source document — every element corresponds to exactly one revision, and
the [JSON rendering](/developers/reference/json-format) reports the same value for the same
change, so a change can be cross-referenced between the two.

## Insertions and deletions

The most common case: one revision edits a sentence.

```html
6. The Recipient will <ins author="counsel@firm.com"
   revision="v2 NDA.docx" date="…">promptly </ins>notify the Company of any
   <del author="counsel@firm.com" revision="v2 NDA.docx" date="…">unauthorized
   </del>disclosure of Confidential Information.
```

Elements nest when revisions changed the same text. `<ins author="A">kept <del author="B">then
cut</del></ins>` is text A inserted that B then partially deleted.

## Moves

A relocated clause is one move, not a delete and an unrelated insert. Both halves carry the
same `move-id`.

```html
1. <moved-from move-id="1" author="counsel@firm.com"
   revision="v2 NDA.docx" date="2026-08-07T02:04:51Z">As used herein, “Confidential
   Information” will mean any and all technical and non-technical information … of the
   Company.</moved-from>

3. <moved-to move-id="1" author="counsel@firm.com"
   revision="v2 NDA.docx" date="2026-08-07T02:04:51Z">As used herein, “Confidential
   Information” will mean any and all technical and non-technical information … of the
   Company.</moved-to>
```

## Multi-author merges

In a merged document, non-conflicting changes from different revisions sit side by side,
each keeping the revision it came from.

```html
… to protect the confidentiality of certain <ins
author="counsel@firm.com" revision="v5(a) NDA.docx" date="…">valuable </ins>confidential
information of the Company …

1. … design details and specifications, engineering, financial information, <ins
author="legal@acme.com" revision="v5(b) NDA.docx" date="…">large language models,
</ins>procurement requirements, purchasing, manufacturing …
```

## Conflicts

When two revisions edit the same span, every candidate is wrapped in a `<conflict>`, each
keeping its own revision. Surface these to a person; do not resolve them automatically.

```html
(d) was rightfully communicated to the Recipient <conflict id="1"><ins
author="counsel@firm.com" revision="v5(a) NDA.docx" date="…">from an individual or entity
</ins><ins author="legal@acme.com" revision="v5(b) NDA.docx" date="…">by a person
</ins></conflict>free of any obligation of confidence …
```

## Everything else in the document

The document's own headings, section numbering, and signature tables are preserved as
markdown. Literal square brackets in the text are escaped — `\[Signature Page Follows\]` is
document text, not a change.

`text_url` is omitted for spreadsheet comparisons and when the rendering is unavailable. The
`word_redline` download carries the same set of tracked changes either way.
