Custom JSON format

This is the file format behind the JSON export, for reading or writing it with your own scripts. To move a tree in or out normally, use the Import and Export panels.

Overview

Draw My Tree uses a versioned JSON wrapper for imports and exports. Files start with a schemaVersion and a meta block, followed by a data object that holds people, relationships, and optional details, events, and media. An unknown key at the top level, in meta or in data rejects the file; an unknown field on a record is reported as a warning and not saved.

The backup .zip

The JSON export downloads as a .zip backup. It holds tree.json, the wrapper described on this page, and a media folder with each uploaded file's bytes as media/<id>.<ext>. That uploaded file's media item names it by the same relative path in url, so a backup carries no signed links. Links and text items stay as they are. Account → Download all my data writes one folder per tree in this layout, with an account.json at the top listing the trees.

The Import panel takes the .zip (one tree.json, at the top or in a single folder). It imports tree.json, then uploads each file to the person the import stored, and gives each person the picture their profileMediaId names when they have none in the tree. The 25 MB limit applies to tree.json, not to the files.

Top-level shape

Meta

Data

The data block contains five arrays. Every array must be present, even if empty.

Person

Relationship

Discriminated by type.

Parent-child

Partner

PersonDetails

One entry per person id. All fields except id are nullable.

PersonEvent

PersonMedia

Files you uploaded through the app carry storage fields on export (storage, status, contentType, bytes, width, height). An import doesn't read them; an uploaded file comes back as an uploaded file only from a backup .zip, uploaded again from its media folder. For media you write yourself, a url (or body for text) is all you need.

Example

{
  "schemaVersion": "1",
  "meta": {
    "exportedAt": "2026-05-19T12:00:00.000Z",
    "treeName": "My Lineage",
    "homePersonId": "p1"
  },
  "data": {
    "people": [
      {
        "id": "p1",
        "name": "Ada Lovelace",
        "birthDate": "1815-12-10",
        "deathDate": "1852-11-27",
        "gender": "female",
        "tags": ["mathematician"],
        "story": "Wrote the first algorithm intended for a machine."
      },
      {
        "id": "p2",
        "name": "Byron King-Noel",
        "birthDate": "1836-05-12",
        "gender": "male"
      },
      {
        "id": "p3",
        "name": "William King-Noel",
        "birthDate": "1805-02-21",
        "gender": "male"
      }
    ],
    "relationships": [
      {
        "id": "r1",
        "type": "parent-child",
        "parentId": "p1",
        "childId": "p2",
        "parentType": "biological",
        "confidence": "certain"
      },
      {
        "id": "r2",
        "type": "partner",
        "a": "p1",
        "b": "p3",
        "status": "married",
        "startYear": 1835
      }
    ],
    "personDetails": [
      {
        "id": "p1",
        "birthPlace": "London, England",
        "religion": "Anglican"
      }
    ],
    "events": [
      {
        "id": "e1",
        "type": "census",
        "date": "1841-06-06",
        "place": "Surrey, England",
        "summary": "1841 UK Census",
        "personId": "p1"
      }
    ],
    "media": [
      {
        "id": "m1",
        "type": "portrait",
        "url": "https://example.com/ada.jpg",
        "title": "Ada at the writing desk",
        "caption": "Portrait, c. 1840, oil on canvas",
        "personId": "p1"
      }
    ]
  }
}

Import behavior

• Files larger than 25 MB are rejected.
• Each list holds at most 50,000 records.
• An unknown key at the top level, in meta or in data rejects the file. An unknown field on a person, relationship, detail, event or media item (for example a typo) is reported as a warning in the import preview and is not saved.
• A person id containing + rejects the file. A second record with an id already used in the same list is dropped with a warning, and so is a relationship that links a person to themselves.
• A relationship, detail, event or media item that names a person or relationship not in the file is dropped.
• A media item whose url is a media/ path (a tree.json imported without its .zip) is dropped with a warning. Import the .zip to restore the file.
• The import API does not restore a person's profileMediaId or an uploaded file's storage fields; the Import panel restores both from a backup .zip, as above.
• The chosen merge strategy controls how the import is reconciled with existing data. Pick a strategy in the Import sidebar before applying.
• An import stores every record under the tree's own ids. An id the tree already holds (a re-import of this tree's own export) is kept; any other id is replaced by one derived from the tree and the file's id, so importing the same file into the same tree again finds the records the first import made. References inside the file (relationships, details, events, media and cite: links) are translated with them.
• The import response carries an idMap with people, relationships, events and media, each mapping the file's id to the id stored. A script that goes on to update or attach to what it imported should look its ids up there rather than reuse the file's.

Last updated October 30, 2026 by Prescott Bros LLC, the makers of Draw My Tree.