Annotation - betula

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

A GFF3-derived sequence feature (gene model) node. Shared verbatim between picea (SequenceInterval) and react-bio-viz (SequenceInterval). seqid/start/end/strand stay flat rather than nesting under core/Location, to match the real current wire shape exactly.

Field	Type	Required	Description
`type`	`"annotation"`	optional	Wire-format object-kind discriminator (see betula’s versioning policy). Optional. Distinct from ‘interval_type’: ‘type’ says this is a betula Annotation object, ‘interval_type’ says which GFF3 feature kind it is.
`ID`	Identifier	required
`seqid`	Identifier	required	GFF3 column 1: the reference sequence this feature is on.
`source`	`string`	required	GFF3 column 2.
`interval_type`	`string` (minLength 1)	required	GFF3 column 3 (feature type), e.g. ‘gene’, ‘mRNA’, ‘exon’, ‘CDS’.
`start`	`integer` (≥ 1)	required	GFF3 column 4: 1-based inclusive start.
`end`	`integer` (≥ 1)	required	GFF3 column 5: 1-based inclusive end.
`score`	`number` \| `"."`	required	GFF3 column 6. ‘.’ is the GFF3 convention for ‘no score’.
`strand`	one of `"+"`, `"-"`, `"."`	required	GFF3 column 7.
`phase`	one of `0`, `1`, `2` \| `"."`	required	GFF3 column 8 (CDS reading-frame phase). ‘.’ is the GFF3 convention for ‘not applicable’.
`attributes`	Metadata	required
`children`	array of Annotation	required	Nested features, e.g. mRNA under gene, exon/CDS under mRNA.

No properties beyond those listed are allowed.

Valid examples¶

gene-with-mrna.json

{
  "type": "annotation",
  "ID": "gene:MtrunA17Chr1g0184451",
  "seqid": "MtrunA17Chr1",
  "source": "EuGene",
  "interval_type": "gene",
  "start": 35039693,
  "end": 35045433,
  "score": ".",
  "strand": "+",
  "phase": ".",
  "attributes": {
    "name": ["MtrunA17Chr1g0184451"],
    "locus_tag": ["MtrunA17_Chr1g0184451"]
  },
  "children": [
    {
      "ID": "mRNA:MtrunA17Chr1g0184451.1",
      "seqid": "MtrunA17Chr1",
      "source": "EuGene",
      "interval_type": "mRNA",
      "start": 35039693,
      "end": 35045433,
      "score": ".",
      "strand": "+",
      "phase": ".",
      "attributes": {
        "parent": ["gene:MtrunA17Chr1g0184451"]
      },
      "children": [
        {
          "ID": "exon:MtrunA17Chr1g0184451.1.exon1",
          "seqid": "MtrunA17Chr1",
          "source": "EuGene",
          "interval_type": "exon",
          "start": 35039693,
          "end": 35039900,
          "score": ".",
          "strand": "+",
          "phase": ".",
          "attributes": {
            "parent": ["mRNA:MtrunA17Chr1g0184451.1"]
          },
          "children": []
        },
        {
          "ID": "cds:MtrunA17Chr1g0184451.1.cds1",
          "seqid": "MtrunA17Chr1",
          "source": "EuGene",
          "interval_type": "CDS",
          "start": 35039693,
          "end": 35039900,
          "score": 0.97,
          "strand": "+",
          "phase": 0,
          "attributes": {
            "parent": ["mRNA:MtrunA17Chr1g0184451.1"]
          },
          "children": []
        }
      ]
    }
  ]
}

Invalid examples¶

bad-phase.json

{
  "ID": "cds:1",
  "seqid": "chr1",
  "source": "EuGene",
  "interval_type": "CDS",
  "start": 1,
  "end": 100,
  "score": 0.5,
  "strand": "+",
  "phase": 5,
  "attributes": {},
  "children": []
}

missing-attributes.json

{
  "ID": "gene:1",
  "seqid": "chr1",
  "source": "EuGene",
  "interval_type": "gene",
  "start": 1,
  "end": 100,
  "score": ".",
  "strand": "+",
  "phase": ".",
  "children": []
}

wrong-type-const.json

{
  "type": "tree",
  "ID": "gene:1",
  "seqid": "chr1",
  "source": "EuGene",
  "interval_type": "gene",
  "start": 1,
  "end": 100,
  "score": ".",
  "strand": "+",
  "phase": ".",
  "attributes": {},
  "children": []
}

annotation.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.wur.nl/betula/annotation/0.6.0/schema.json",
  "title": "Annotation",
  "description": "A GFF3-derived sequence feature (gene model) node. Shared verbatim between picea (SequenceInterval) and react-bio-viz (SequenceInterval). seqid/start/end/strand stay flat rather than nesting under core/Location, to match the real current wire shape exactly.",
  "type": "object",
  "properties": {
    "type": {
      "const": "annotation",
      "description": "Wire-format object-kind discriminator (see betula's versioning policy). Optional. Distinct from 'interval_type': 'type' says this is a betula Annotation object, 'interval_type' says which GFF3 feature kind it is."
    },
    "ID": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
    "seqid": {
      "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json",
      "description": "GFF3 column 1: the reference sequence this feature is on."
    },
    "source": {
      "type": "string",
      "description": "GFF3 column 2."
    },
    "interval_type": {
      "type": "string",
      "minLength": 1,
      "description": "GFF3 column 3 (feature type), e.g. 'gene', 'mRNA', 'exon', 'CDS'."
    },
    "start": {
      "type": "integer",
      "minimum": 1,
      "description": "GFF3 column 4: 1-based inclusive start."
    },
    "end": {
      "type": "integer",
      "minimum": 1,
      "description": "GFF3 column 5: 1-based inclusive end."
    },
    "score": {
      "description": "GFF3 column 6. '.' is the GFF3 convention for 'no score'.",
      "oneOf": [{ "type": "number" }, { "const": "." }]
    },
    "strand": {
      "type": "string",
      "enum": ["+", "-", "."],
      "description": "GFF3 column 7."
    },
    "phase": {
      "description": "GFF3 column 8 (CDS reading-frame phase). '.' is the GFF3 convention for 'not applicable'.",
      "oneOf": [{ "enum": [0, 1, 2] }, { "const": "." }]
    },
    "attributes": { "$ref": "https://schemas.wur.nl/betula/core/metadata/0.6.0/schema.json" },
    "children": {
      "type": "array",
      "items": { "$ref": "#" },
      "description": "Nested features, e.g. mRNA under gene, exon/CDS under mRNA."
    }
  },
  "required": ["ID", "seqid", "source", "interval_type", "start", "end", "score", "strand", "phase", "attributes", "children"],
  "additionalProperties": false
}

Usage¶

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

Python

TypeScript

Rust

annotation.py

from betula_schema import Annotation, parse_json

with open("annotation.json") as f:
    annotation = parse_json(Annotation, f.read())
print(annotation)

annotation.ts

import { readFileSync } from "node:fs";
import { parseJson, type Annotation } from "betula-schema";

const annotation: Annotation = parseJson("Annotation", readFileSync("annotation.json", "utf8"));
console.log(annotation);

annotation.rs

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