Feature

Tana Intermediate Format

Use Tana Intermediate Format 2.1 to import structured JSON into a new Tana Outliner workspace. Create outlines, supertags, and fields, reuse existing schema, or import an editable copy of a workspace export.

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.

  1. Save your JSON as a file, such as project.tif.json.
  2. Open the user menu in Tana Outliner and choose Import content.
  3. Choose Tana Intermediate Format and select the file.
  4. 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:

MemberWhere its children go
workspaceWorkspace home
inboxInbox
libraryLibrary
schemaSchema, usually supertag and field definitions
additionalRootsAn 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.

InputImported result
A definition with uidNew node; references to that label use it
A definition with idNew copy with a fresh ID
A reference to an ID defined in the fileThe imported copy
A reference to an ID outside the fileThe 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>&amp;</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:

InputResult
Computed valuesPlain text
Search, chat, and journal partsStatic outlines
TranscriptsSpeaker text; timing is dropped
Omitted export contentCannot be recovered from the file
Unknown field data typePlain field
Inaccessible external node or schemaLink 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.

Tana Intermediate Format - Tana Outliner Learn