Publishing your own archive on the Tree Canvas
Draw your own research on the canvas with its page links and correction marks, from one file, without uploading it and without asking anyone.
Two ways, and only the first is open to everyone. Drop a tree.json on the canvas and it draws your tree, read in your browser and never uploaded.
Or ask for your site to be listed, so the canvas knows it by name, which is a decision the Atlas makes for each archive.
Open the Tree Canvas · Download an invented example file to try it now.
Two file formats one is the industry standard, one is ours
| GEDCOM | tree.json | |
|---|---|---|
| Whose format | The industry standard. Almost every genealogy program and website can export one. | Ours. Made up for Record Atlas and its Roots & Routes tool. No other program reads or writes it, and it is not a standard. |
| What it carries | People, dates, places, families, sources | The same, plus a page link for each person, a corrections count, the route a person travelled and a living flag |
| Where it is described | The GEDCOM specification, published outside Record Atlas | The file format on this page, which is the contract the reader enforces |
Route 1: drop a tree.json open to anyone · available now
If you build a Roots & Routes tree for your own site, it already makes a tree.json. Open the folder button on the canvas, or drag the file onto the page, as you would a
GEDCOM. The canvas tells the two apart by what is inside, not by the file name.
- Nothing is uploaded and nobody has to approve it. The file is read in your browser. The only requests the page makes are for the Atlas's own public files for the places your file names, the same ones a GEDCOM needs.
- What you get that a GEDCOM cannot give. A link from each person to their own page on your site, a mark where you have recorded corrections or notes, full dates as you wrote them, the route a person travelled, and your sources. All of it comes from the file.
- It is labelled as yours. It appears under the title in your file's
meta.title, never as one of the Atlas's archives, and the canvas does not check what it says. You can still set it beside a family archive and compare. - Anyone who may be alive is left as a name and a family. This is applied to every file before anything is drawn, whatever the file says: a person marked
living, or with no death year (or only an estimated one) and born after 1920, keeps their name and their family links, and loses dates, places, page link, sources and occupation. A careless export cannot put a living person's details on the canvas. The canvas says how many it did this to.
The tree.json format our own format · what the reader takes, and nothing more
tree.json is Record Atlas's own format, not an industry standard. This table is its contract: the reader (treejson.js) takes what is listed here and ignores the rest, and a test (scripts/test-tree-json.mjs) checks the reader against it. The top level is an object with meta and people (a list), and optionally places. Each person is an object. Anything not in the table is ignored. Text is cut to a safe length, years must be whole numbers from 1000 to 2100, and a link to someone who is not in the file is dropped and counted.
| Field | Meaning | Needed |
|---|---|---|
id | A unique, stable text id. A repeated id is skipped. | Yes |
sex | m, f or u | Optional |
given, sur | Given names, surname | Optional |
by, dy | Birth year, death year (numbers). | Optional |
bye, dye | true when that year is an estimate. An estimated death year does not release someone born after 1920 from the living rule. | Optional |
bd, dd | Full date, such as 1851-03-02 or 2 Mar 1851 | Optional |
bp, dp | Birth place, death place, as text (see Places below) | Optional |
father, mother | Ids of the parents | Optional |
spouse, kids | Lists of ids. Where a child names a parent, or a parent lists a child, the other side is filled in. | Optional |
occ, my | Occupation; marriage year | Optional |
route | Places lived, in order: [place, year, estimated], up to 40 | Optional |
page | The person's own page, a path on your site such as /people/ivan/. It is used only when meta.site names your site. | Optional |
cx | How many corrections and notes you have recorded about them (a count). It links to their page. | Optional |
srcs | Sources: { t: title, u: https link }, up to 20. Links that are not https are dropped. | Optional |
surAlso | Other spellings of the surname recorded for them | Optional |
living | true to show the person as a name and family only | Optional |
meta.title | The name the canvas shows for your tree | Optional |
meta.site | Your site's address, https only, for example https://family.example.org. Page links and corrections links are built on it. | Needed for page links |
Places how a name becomes a flag and a country
A place is text. Written with its country (Rijeka, Croatia), it is looked up in the Atlas's own place files, and the canvas draws the flag in force there in the year of the event, as it does for a GEDCOM.
A bare name such as Mascali or Melbourne could be anywhere, so a file may also bring the places it has already placed, as Roots & Routes writes them: a list places (or atlas.places) of
{ n, lat, lon, cn }, the name exactly as used in the people, its coordinates, and its country (Italy or IT). Only those four are read. The flag, the rulers and the eras are still looked up in the Atlas, so
nothing drawn comes from your file. A place that cannot be found stays as the text you wrote, with no flag, and the person is drawn without a map position.
Route 2: a listed archive by request · one decision each time
An archive on the list opens by name from the canvas, with its own colour, page links and corrections marks, and can be compared with a GEDCOM like the eight family archives. It is the Atlas vouching for the site, so each one is a decision.
- An entry is a host, a name and a colour in an allow-list, plus a change to the page's security policy so the canvas may connect to that host.
- Before one is added, the site must publish a
/roots/ page in the same format, must leave out living people, and must keep its data public and stable. The Atlas can check the first by reading the file; the other two are the owner's word. - Not offered for a listed archive: a site cannot become a listed archive by typing its address. What is offered is Route 1 from a link: the first screen of the Tree Canvas has a box for the https address of a public GEDCOM or tree.json (a link of the form
/tree-canvas/?url=… only fills that box; nothing is fetched until you press Open link). The page around the canvas fetches the file in your browser, never the canvas itself, and the security policy of that one page now lets it read an https address; the canvas and the rest of the site are unchanged. The limits: https only; a public website (no sign-in details, port, bare IP address or local name); the site must allow other websites to read the file (an Access-Control-Allow-Origin header, which GitHub's raw files and GitHub Pages send); 100 MB at most; nothing passes through Record Atlas; and the site it came from is named when the canvas opens. The file is treated exactly like one you opened yourself: labelled as your file, with the living rule applied.
The two side by side
Route 1: tree.json Route 2: listed archive Who decides You The Atlas, per archive Privacy The file stays in your browser The canvas fetches your public /roots/ page Page links and corrections Yes, if the file carries them and names your site Yes Appears as Labelled as your file Named, with its own colour Security policy Unchanged for a file you drop; the opening page may read any https link you paste One host added per archive Status Available Not offered yet