Tree - betula

https://schemas.wur.nl/betula/tree/0.6.0/schema.json

A phylogenetic (or other hierarchical) tree node, shared by picea, react-bio-viz, acacia, and iqtreeserver. The root of a tree is itself a Tree node; a whole tree and a single node use the same shape, so ‘type’ is optional and conventionally set only on a node transmitted as a standalone document (typically the root), not repeated on every nested child.

Field	Type	Required	Description
`type`	`"tree"`	optional	Wire-format object-kind discriminator (see betula’s versioning policy). Optional; omit on nested children.
`id`	`string` or `integer`	optional	Optional node identifier. Not every producer assigns one at parse time (acacia/iqtreeserver derive ids separately); consumers must not assume it is present.
`name`	`string`	required	Raw node label: a leaf name, or an internal-node label such as a bootstrap value or support string (e.g. picea’s “0.989”, IQ-TREE’s “95.3/88”). Kept as the original string for round-tripping; parse further only if you know the producer’s convention.
`length`	`number` (≥ 0)	required	Branch length leading to this node.
`children`	array of Tree	required	Child nodes. Empty array for a leaf.

No properties beyond those listed are allowed.

Valid examples¶

with-id-and-support.json

{
  "type": "tree",
  "id": 0,
  "name": "",
  "length": 0.0,
  "children": [
    {
      "id": 1,
      "name": "A",
      "length": 0.096360892,
      "children": []
    },
    {
      "id": 2,
      "name": "0.989",
      "length": 0.159121648,
      "children": [
        {
          "id": 3,
          "name": "B",
          "length": 0.05,
          "children": []
        },
        {
          "id": 4,
          "name": "C",
          "length": 0.07,
          "children": []
        }
      ]
    }
  ]
}

without-id.json

{
  "name": "root",
  "length": 0,
  "children": [
    {
      "name": "leaf1",
      "length": 0.12,
      "children": []
    },
    {
      "name": "95.3/88",
      "length": 0.34,
      "children": [
        {
          "name": "leaf2",
          "length": 0.01,
          "children": []
        },
        {
          "name": "leaf3",
          "length": 0.02,
          "children": []
        }
      ]
    }
  ]
}

Invalid examples¶

missing-children.json

{
  "name": "leaf",
  "length": 0.1
}

negative-length.json

{
  "name": "leaf",
  "length": -0.5,
  "children": []
}

wrong-type-const.json

{
  "type": "alignment",
  "name": "leaf",
  "length": 0.1,
  "children": []
}

tree.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.wur.nl/betula/tree/0.6.0/schema.json",
  "title": "Tree",
  "description": "A phylogenetic (or other hierarchical) tree node, shared by picea, react-bio-viz, acacia, and iqtreeserver. The root of a tree is itself a Tree node; a whole tree and a single node use the same shape, so 'type' is optional and conventionally set only on a node transmitted as a standalone document (typically the root), not repeated on every nested child.",
  "type": "object",
  "properties": {
    "type": {
      "const": "tree",
      "description": "Wire-format object-kind discriminator (see betula's versioning policy). Optional; omit on nested children."
    },
    "id": {
      "description": "Optional node identifier. Not every producer assigns one at parse time (acacia/iqtreeserver derive ids separately); consumers must not assume it is present.",
      "type": ["string", "integer"]
    },
    "name": {
      "description": "Raw node label: a leaf name, or an internal-node label such as a bootstrap value or support string (e.g. picea's \"0.989\", IQ-TREE's \"95.3/88\"). Kept as the original string for round-tripping; parse further only if you know the producer's convention.",
      "type": "string"
    },
    "length": {
      "description": "Branch length leading to this node.",
      "type": "number",
      "minimum": 0
    },
    "children": {
      "description": "Child nodes. Empty array for a leaf.",
      "type": "array",
      "items": { "$ref": "#" }
    }
  },
  "required": ["name", "length", "children"],
  "additionalProperties": false
}

Usage¶

Read a JSON document and parse it as a Tree. CI runs this exact code against the first valid example above; see Getting started to install the bindings.

Python

TypeScript

Rust

tree.py

from betula_schema import Tree, parse_json

with open("tree.json") as f:
    tree = parse_json(Tree, f.read())
print(tree)

tree.rs

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let text = std::fs::read_to_string("tree.json")?;
    let tree: betula_schema::Tree = betula_schema::parse_str(&text)?;
    println!("{tree:?}");
    Ok(())
}