BlastResult - betula

https://schemas.wur.nl/betula/blast-result/0.6.0/schema.json

A full BLAST search result, matching blastserver’s parsed-XML shape: hit-level, with nested HSPs and taxonomy/cluster enrichment. react-bio-viz’s flattened single-row-per-hit visualization shape is a derived view of this, not a separate wire format. Numeric fields here are typed as numbers; blastserver’s raw XML parse currently yields numeric strings and must cast before serializing against this schema.

Field	Type	Required	Description
`type`	`"blast-result"`	optional	Wire-format object-kind discriminator (see betula’s versioning policy). Optional.
`program`	`string`	required
`version`	`string`	required
`db`	`string`	required
`queryId`	Identifier	required
`queryLen`	`integer` (≥ 1)	required
`queryTitle`	`string`	required
`hits`	array of Hit	required
`stat`	`string`	required
`message`	`string`	required
`taxonomyTrees`	array of TaxonomyNode	optional

No properties beyond those listed are allowed.

Definitions¶

Hsp¶

Field	Type	Required
`num`	`integer` (≥ 1)	required
`bitScore`	`number`	required
`score`	`number`	required
`evalue`	`number` (≥ 0)	required
`identity`	`integer` (≥ 0)	required
`alignLen`	`integer` (≥ 1)	required
`queryFrom`	`integer` (≥ 1)	required
`queryTo`	`integer` (≥ 1)	required
`hitFrom`	`integer` (≥ 1)	required
`hitTo`	`integer` (≥ 1)	required
`qseq`	`string`	required
`hseq`	`string`	required
`midline`	`string`	required

No properties beyond those listed are allowed.

HitMember¶

One member of a clustered hit (e.g. in a clustered_nr database); a non-clustered hit has exactly one member.

Field	Type	Required
`accession`	Identifier	required
`title`	`string`	required
`taxid`	`integer`	required
`name`	`string`	required

No properties beyond those listed are allowed.

Hit¶

Field	Type	Required	Description
`accession`	Identifier	required
`title`	`string`	required
`taxid`	`integer`	required
`saccver`	Identifier	required
`name`	`string`	required	Resolved taxon scientific name.
`members`	array of HitMember	required
`clusterSize`	`integer` (≥ 1)	required
`queryCover`	`number` (≥ 0, ≤ 100)	required
`percentIdentity`	`number` (≥ 0, ≤ 100)	required
`num`	`integer`	required
`len`	`integer` (≥ 1)	required
`hsps`	array of Hsp	required
`ancestors`	array of `integer`	required	Taxonomy lineage taxids.

No properties beyond those listed are allowed.

TaxonomyNode¶

Field	Type	Required
`id`	`integer`	required
`name`	`string`	required
`ancestors`	array of `integer`	required
`children`	array of TaxonomyNode	optional
`depth`	`integer` (≥ 0)	optional
`count`	`integer` (≥ 0)	optional

No properties beyond those listed are allowed.

Valid examples¶

simple.json

{
  "type": "blast-result",
  "program": "blastp",
  "version": "BLAST 2.16.0+",
  "db": "nr",
  "queryId": "Query_1",
  "queryLen": 120,
  "queryTitle": "example query protein",
  "stat": "",
  "message": "",
  "hits": [
    {
      "accession": "WP_012345678",
      "title": "hypothetical protein [Example species]",
      "taxid": 1280,
      "saccver": "WP_012345678.1",
      "name": "Example species",
      "members": [
        { "accession": "WP_012345678", "title": "hypothetical protein", "taxid": 1280, "name": "Example species" }
      ],
      "clusterSize": 1,
      "queryCover": 95.5,
      "percentIdentity": 87.2,
      "num": 1,
      "len": 118,
      "ancestors": [1, 2, 1224, 1236, 1280],
      "hsps": [
        {
          "num": 1,
          "bitScore": 210.5,
          "score": 540,
          "evalue": 1e-65,
          "identity": 103,
          "alignLen": 118,
          "queryFrom": 1,
          "queryTo": 118,
          "hitFrom": 1,
          "hitTo": 118,
          "qseq": "MST...",
          "hseq": "MST...",
          "midline": "MST..."
        }
      ]
    }
  ],
  "taxonomyTrees": [
    { "id": 1, "name": "root", "ancestors": [], "children": [{ "id": 1224, "name": "Proteobacteria", "ancestors": [1], "children": [] }] }
  ]
}

Invalid examples¶

hsp-string-coordinate.json

{
  "program": "blastp",
  "version": "BLAST 2.16.0+",
  "db": "nr",
  "queryId": "Query_1",
  "queryLen": 120,
  "queryTitle": "example query protein",
  "stat": "",
  "message": "",
  "hits": [
    {
      "accession": "WP_012345678",
      "title": "hypothetical protein",
      "taxid": 1280,
      "saccver": "WP_012345678.1",
      "name": "Example species",
      "members": [
        { "accession": "WP_012345678", "title": "hypothetical protein", "taxid": 1280, "name": "Example species" }
      ],
      "clusterSize": 1,
      "queryCover": 95.5,
      "percentIdentity": 87.2,
      "num": 1,
      "len": 118,
      "ancestors": [1280],
      "hsps": [
        {
          "num": 1,
          "bitScore": 210.5,
          "score": 540,
          "evalue": 1e-65,
          "identity": 103,
          "alignLen": 118,
          "queryFrom": "1",
          "queryTo": 118,
          "hitFrom": 1,
          "hitTo": 118,
          "qseq": "MST...",
          "hseq": "MST...",
          "midline": "MST..."
        }
      ]
    }
  ]
}

missing-hits.json

{
  "program": "blastp",
  "version": "BLAST 2.16.0+",
  "db": "nr",
  "queryId": "Query_1",
  "queryLen": 120,
  "queryTitle": "example query protein",
  "stat": "",
  "message": ""
}

wrong-type-const.json

{
  "type": "alignment",
  "program": "blastp",
  "version": "BLAST 2.16.0+",
  "db": "nr",
  "queryId": "Query_1",
  "queryLen": 120,
  "queryTitle": "example query protein",
  "stat": "",
  "message": "",
  "hits": []
}

blast-result.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.wur.nl/betula/blast-result/0.6.0/schema.json",
  "title": "BlastResult",
  "description": "A full BLAST search result, matching blastserver's parsed-XML shape: hit-level, with nested HSPs and taxonomy/cluster enrichment. react-bio-viz's flattened single-row-per-hit visualization shape is a derived view of this, not a separate wire format. Numeric fields here are typed as numbers; blastserver's raw XML parse currently yields numeric strings and must cast before serializing against this schema.",
  "type": "object",
  "$defs": {
    "Hsp": {
      "type": "object",
      "properties": {
        "num": { "type": "integer", "minimum": 1 },
        "bitScore": { "type": "number" },
        "score": { "type": "number" },
        "evalue": { "type": "number", "minimum": 0 },
        "identity": { "type": "integer", "minimum": 0 },
        "alignLen": { "type": "integer", "minimum": 1 },
        "queryFrom": { "type": "integer", "minimum": 1 },
        "queryTo": { "type": "integer", "minimum": 1 },
        "hitFrom": { "type": "integer", "minimum": 1 },
        "hitTo": { "type": "integer", "minimum": 1 },
        "qseq": { "type": "string" },
        "hseq": { "type": "string" },
        "midline": { "type": "string" }
      },
      "required": ["num", "bitScore", "score", "evalue", "identity", "alignLen", "queryFrom", "queryTo", "hitFrom", "hitTo", "qseq", "hseq", "midline"],
      "additionalProperties": false
    },
    "HitMember": {
      "type": "object",
      "description": "One member of a clustered hit (e.g. in a clustered_nr database); a non-clustered hit has exactly one member.",
      "properties": {
        "accession": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
        "title": { "type": "string" },
        "taxid": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["accession", "title", "taxid", "name"],
      "additionalProperties": false
    },
    "Hit": {
      "type": "object",
      "properties": {
        "accession": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
        "title": { "type": "string" },
        "taxid": { "type": "integer" },
        "saccver": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
        "name": { "type": "string", "description": "Resolved taxon scientific name." },
        "members": { "type": "array", "items": { "$ref": "#/$defs/HitMember" }, "minItems": 1 },
        "clusterSize": { "type": "integer", "minimum": 1 },
        "queryCover": { "type": "number", "minimum": 0, "maximum": 100 },
        "percentIdentity": { "type": "number", "minimum": 0, "maximum": 100 },
        "num": { "type": "integer" },
        "len": { "type": "integer", "minimum": 1 },
        "hsps": { "type": "array", "items": { "$ref": "#/$defs/Hsp" }, "minItems": 1 },
        "ancestors": { "type": "array", "items": { "type": "integer" }, "description": "Taxonomy lineage taxids." }
      },
      "required": ["accession", "title", "taxid", "saccver", "name", "members", "clusterSize", "queryCover", "percentIdentity", "num", "len", "hsps", "ancestors"],
      "additionalProperties": false
    },
    "TaxonomyNode": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "ancestors": { "type": "array", "items": { "type": "integer" } },
        "children": { "type": "array", "items": { "$ref": "#/$defs/TaxonomyNode" } },
        "depth": { "type": "integer", "minimum": 0 },
        "count": { "type": "integer", "minimum": 0 }
      },
      "required": ["id", "name", "ancestors"],
      "additionalProperties": false
    }
  },
  "properties": {
    "type": {
      "const": "blast-result",
      "description": "Wire-format object-kind discriminator (see betula's versioning policy). Optional."
    },
    "program": { "type": "string" },
    "version": { "type": "string" },
    "db": { "type": "string" },
    "queryId": { "$ref": "https://schemas.wur.nl/betula/core/identifier/0.6.0/schema.json" },
    "queryLen": { "type": "integer", "minimum": 1 },
    "queryTitle": { "type": "string" },
    "hits": { "type": "array", "items": { "$ref": "#/$defs/Hit" } },
    "stat": { "type": "string" },
    "message": { "type": "string" },
    "taxonomyTrees": { "type": "array", "items": { "$ref": "#/$defs/TaxonomyNode" } }
  },
  "required": ["program", "version", "db", "queryId", "queryLen", "queryTitle", "hits", "stat", "message"],
  "additionalProperties": false
}

Usage¶

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

Python

TypeScript

Rust

blast-result.py

from betula_schema import BlastResult, parse_json

with open("blast-result.json") as f:
    blast_result = parse_json(BlastResult, f.read())
print(blast_result)

blast-result.ts

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

const blastResult: BlastResult = parseJson("BlastResult", readFileSync("blast-result.json", "utf8"));
console.log(blastResult);

blast-result.rs

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