Tana Intermediate Format 2.1, or TIF2, is JSON for importing structured content into Tana Outliner. You can write it yourself, generate it with a script, or export it from another Tana Outliner workspace.
Use TIF2 for a bulk import into a new workspace. For pasting content into an existing outline, use Tana Paste. For ongoing programmatic changes, use the local API and MCP.
Import a TIF2 file
Every TIF2 import creates a new workspace. Nodes defined in the file receive fresh IDs. References to nodes outside the file remain links to those existing nodes. Importing never updates existing nodes.
- Save your JSON as a file, such as
project.tif.json. - Open the user menu in Tana Outliner and choose Import content.
- Choose Tana Intermediate Format and select the file.
- Open the new workspace and review any import warnings.
Try the complete project example. It creates a supertag, an options field, references, and todos. It needs no existing node IDs.
Write your first file
This file creates a Research node with two children and a mention linking one child to the other:
{
"version": "TanaIntermediateFile V2.1",
"contents": {
"workspace": {
"children": [
{
"name": "Research",
"children": [
{ "uid": "source", "name": "Original source" },
{ "name": "Summary of [[source]]", "isDone": false }
]
}
]
}
}
}Use the exact version string TanaIntermediateFile V2.1. Every member of contents is optional:
| Member | Where its children go |
|---|---|
workspace | Workspace home |
inbox | Inbox |
library | Library |
schema | Schema, usually supertag and field definitions |
additionalRoots | An array of nodes placed under the workspace root |
The named containers are regular nodes. Their names are ignored. TIF2 does not need a summary, timestamps, or a top-level nodes array.
An ordinary node needs only a name. Add children to nest content, description for a description, or isSection: true for a heading. Set isDone to false for an unchecked todo or true for a checked todo. Omit it for a node without a checkbox.
Define nodes and reuse references
Give a node a uid when other nodes in the file need to reference it. The label is local to that file. Use { "isRef": true, "uid": "source" } to place a reference in an outline, or [[source]] to mention it in a name. The definition can appear after the reference.
To link to an existing Tana Outliner node, use its id:
{ "isRef": true, "id": "EXISTING_NODE_ID" }A reference has exactly one of id or uid. It does not search for a node by name.
| Input | Imported result |
|---|---|
A definition with uid | New node; references to that label use it |
A definition with id | New copy with a fresh ID |
| A reference to an ID defined in the file | The imported copy |
| A reference to an ID outside the file | The existing node |
Importing the same file again creates another workspace and another set of copies. References elsewhere in Tana Outliner still point to the original nodes.
An external reference does not grant access to its source workspace. If you cannot read its target, it remains a link and can appear as unknown. The importer reports a warning. Importing also does not enable cross-workspace search. Configure Allow content from separately when needed.
Create supertags and fields
Declare supertags and field definitions under schema. Fields and ordinary notes share the ordered children array. A supertag uses type: "supertag", a field definition uses type: "fieldDefinition", and a field on a node uses type: "field" with a field reference and a values array.
{
"version": "TanaIntermediateFile V2.1",
"contents": {
"schema": {
"children": [
{ "type": "supertag", "uid": "project", "name": "project" },
{ "type": "fieldDefinition", "uid": "budget", "name": "Budget", "dataType": "number" }
]
},
"workspace": {
"children": [
{
"name": "Launch plan",
"tags": [{ "uid": "project" }],
"children": [
{
"type": "field",
"field": { "uid": "budget" },
"values": [500]
}
]
}
]
}
}
}The result is a Launch plan with the #project supertag and a Budget field set to 500. Strings and numbers in values import as literal text. Booleans become Yes/No values. Use a node with name for a formatted value or a mention, and an empty values array for an empty field.
To reuse an existing supertag, set tags to ["EXISTING_TAG_ID"]. To reuse an existing field, set field to { "id": "EXISTING_FIELD_ID" }. Replace the placeholders with real IDs, which you can find through Show API schema on a supertag.
Field data types are list, number, integer, boolean, date, user, instance, formula, url, email, and options. Omit dataType for a plain field.
For options fields, fixedOptionIds lists the options in order. Define options owned by the field in its inlineNodes map, and reference them from field values. See the complete example and format reference for this structure. Field definitions cannot own outline children.
Supertags can use extends to reference parent supertags. The field, tags, extends, and fixedOptionIds properties always reference definitions declared elsewhere. Expanded metadata does not declare a new node. An expanded fieldDefinition in field requires isRef: true.
Keep a field definition local to a supertag
An inlineNodes map declares nodes owned by its containing node, outside the outline. A supertag can declare a local field definition and reference it in a default field:
{
"type": "supertag",
"uid": "task",
"name": "task",
"inlineNodes": {
"estimate": { "type": "fieldDefinition", "uid": "estimate", "name": "Estimate", "dataType": "number" }
},
"children": [{ "type": "field", "field": { "uid": "estimate" }, "values": [] }]
}Other nodes can reference Estimate by its uid. Declare each definition once, with an id or uid. A field occurrence can also own its definition through inlineNodes; its field property remains a reference.
Format names, code, and media
String names support **bold**, __italic__, ~~strikethrough~~, ^^highlight^^, and backtick code spans. Code spans keep mentions literal. Use [label](https://example.com) for web links, [label]([[source]]) for mention aliases, and [[date:2026-10-15]] for inline dates.
Mentions resolve a file-local uid first, then an ID defined in the file, then an existing node ID. Names and mention aliases are text; HTML is escaped.
Exports use structured nameParts, which can hold text, node mentions, dates, users, and links. Choose name or nameParts on a node, never both. See the name reference for the supported parts.
For code blocks, set plainText: true when writing literal source:
{ "type": "codeBlock", "language": "html", "plainText": true, "content": "<p>&</p>" }Without that flag, the importer decodes HTML entities in content.
Use type: "url" with url for a URL node, or type: "visual" with url for a media node. Media stays linked to its URL. TIF2 does not embed or copy attachment bytes.
Export and import a workspace copy
Open the workspace home node’s ellipsis menu and choose Export workspace as JSON. In the dialog, select Tana Intermediate Format 2.1. This option becomes available once the workspace finishes loading.
The export includes readable workspace content and schema. Importing it creates an editable copy, with its owned supertags, fields, and fixed options pointing at the copies. References outside the exported workspace keep pointing at their original targets.
TIF2 does not restore the whole workspace. The export dialog also offers Tana JSON, which contains Tana’s full stored representation for technical use. Tana JSON is a separate format and cannot be imported through the TIF importer.
Import limits and warnings
The importer shows warnings when content needs a conversion:
| Input | Result |
|---|---|
| Computed values | Plain text |
| Search, chat, and journal parts | Static outlines |
| Transcripts | Speaker text; timing is dropped |
| Omitted export content | Cannot be recovered from the file |
| Unknown field data type | Plain field |
| Inaccessible external node or schema | Link remains; target may appear unknown |
Views, automations, workspace settings, membership, and appearance metadata are not restored.
Invalid JSON, duplicate definitions, missing local references, invalid schema roles, and nesting deeper than 1000 levels stop the import. A rejected TIF2 file does not create a workspace.
Build an importer
The public tana-import-tools repository holds the full format reference, TypeScript definitions, and sample file.
Use TanaIntermediateFile and its related types to generate files. The converters in the repository write TanaIntermediateFile V2.1.

