Custom JSON format

Most users never need this page. If you just want to import or export a tree, the regular Import and Export panels handle GEDCOM and the built-in JSON without any of this. This reference is for power users who want to round-trip a tree through their own scripts or build tooling on top of Draw My Tree's data.

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. Unknown fields are preserved on import but reported as warnings.

Top-level shape

Field	Type	Required	Description
schemaVersion	"1"	required	Format version. Currently only '1' is accepted.
meta	object	required	Export metadata. See Meta below.
data	object	required	Tree contents. See Data below.

Field	Type	Required	Description
exportedAt	string (ISO 8601)	required	When the export was produced.
appVersion	string	optional	Version of Draw My Tree that produced the export.
treeName	string	optional	Human-readable tree name.

Data

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

Field	Type	Required	Description
people	Person[]	required	Individuals in the tree.
relationships	Relationship[]	required	Parent-child and partner links.
personDetails	PersonDetails[]	required	Optional life-event places and dates per person.
events	PersonEvent[]	required	Census, marriage, immigration, and other dated records.
media	PersonMedia[]	required	Photos, portraits, and documents linked to a person or relationship.

Person

Field	Type	Required	Description
id	string	required	Stable identifier referenced by relationships and details.
name	string	required	Display name.
birthDate	string	optional	ISO date or partial date (e.g. '1815' or '1815-12-10').
deathDate	string	optional	ISO date or partial date.
gender	'male' \| 'female' \| 'other'	optional	Used for visual styling and GEDCOM export.
prefix	string	optional	Name prefix such as 'Dr.' or 'Sir'.
suffix	string	optional	Name suffix such as 'Jr.' or 'III'.
tags	string[]	optional	Free-form labels.
aliases	string[]	optional	Alternate or former names (maiden name, nickname, anglicized spelling).
story	string	optional	Long-form biography. Markdown is supported in the UI.
profileMediaId	string	optional	Id of the media item used as this person's profile picture.

Relationship

Discriminated by type.

Parent-child

Field	Type	Required	Description
id	string	required	Stable identifier.
type	"parent-child"	required	Discriminator.
parentId	string	required	Person id of the parent.
childId	string	required	Person id of the child.
parentType	'biological' \| 'adoptive' \| 'step' \| 'guardian'	optional	Nature of the parental link.
confidence	'certain' \| 'probable' \| 'possible'	optional	How certain the link is.

Partner

Field	Type	Required	Description
id	string	required	Stable identifier.
type	"partner"	required	Discriminator.
a	string	required	One partner's person id.
b	string	required	The other partner's person id.
status	'married' \| 'divorced' \| 'partnered'	optional	Current state of the partnership.
startYear	number	optional	Year the partnership began.
endYear	number	optional	Year the partnership ended.

PersonDetails

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

Field	Type	Required	Description
id	string	required	Matches a Person id.
birthDate	string \| null	optional	Overrides Person.birthDate when present.
deathDate	string \| null	optional	Overrides Person.deathDate when present.
birthPlace	string \| null	optional	Place of birth.
deathPlace	string \| null	optional	Place of death.
burialDate	string \| null	optional	Date of burial.
burialPlace	string \| null	optional	Place of burial.
baptismDate	string \| null	optional	Date of baptism.
baptismPlace	string \| null	optional	Place of baptism.
religion	string \| null	optional	Religious affiliation.

PersonEvent

Field	Type	Required	Description
id	string	required	Stable identifier.
type	'marriage' \| 'divorce' \| 'census' \| 'burial' \| 'immigration' \| 'newspaper' \| 'probate' \| 'property' \| 'church' \| 'record' \| 'occupation' \| 'residence'	required	Event category.
date	string \| null	optional	ISO date or partial date.
place	string \| null	optional	Where the event occurred.
summary	string \| null	optional	Short note about the event.
url	string \| null	optional	Link to a source record.
personId	string \| null	optional	Person the event is attached to.
relationshipId	string \| null	optional	Relationship the event is attached to (e.g. marriage).

PersonMedia

Field	Type	Required	Description
id	string	required	Stable identifier.
type	'photo' \| 'portrait' \| 'video' \| 'document' \| 'link' \| 'text'	required	Media category.
url	string	required	Direct URL to the media file. For 'text' items the content lives in body instead.
body	string \| null	optional	Inline content for 'text' items (transcripts, poems, recollections).
title	string \| null	optional	Short human-readable label shown as the media's display name. Recommended under ~80 characters.
caption	string \| null	optional	Longer descriptive context, transcript snippet, or alt text. Shown beneath the title.
source	string \| null	optional	Attribution or archive reference.
sourceUrl	string \| null	optional	Link to the source the item was drawn from.
personId	string \| null	optional	Person the media is attached to.
relationshipId	string \| null	optional	Relationship the media is attached to.

Files you uploaded through the app carry extra server-managed storage fields (storage, status, objectKey, contentType, bytes, width, height, checksum). They round-trip on export and re-import, but you don't set them by hand; for media you author yourself, a url (or body for text) is all you need.

Example

{
  "schemaVersion": "1",
  "meta": {
    "exportedAt": "2026-05-19T12:00:00.000Z",
    "appVersion": "1.12.0",
    "treeName": "My Lineage"
  },
  "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."
      }
    ],
    "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.
Unknown fields on a known object (for example a typo in a person field) are kept but surfaced as warnings in the import preview.
The chosen merge strategy controls how the import is reconciled with existing data. Pick a strategy in the Import sidebar before applying.