/shaip/variantformatter-v2

Purpose

High-performance genomic → transcript → protein formatter.

Optimised for:

• Genomic HGVS
• VCF lines
• Pseudo-VCF inputs
• Batch processing

This endpoint is intended for high-throughput workflows where speed and controlled transcript mapping are required.

---

Method

POST

---

Path

/shaip/variantformatter-v2

---

Input

Parameter	Type	Required	Description
variant_description	string or array	Yes	Variant input (HGVS, VCF, or pseudo-VCF). Multiple inputs via a JSON array or pipe-delimited string
genome_build	string	Yes	GRCh37, GRCh38, hg19, or hg38
transcript_model	string	Yes	refseq, ensembl, or all
select_transcripts	string or array	Yes	Transcript selection (see transcript_selection.md)
checkonly	boolean or "tx"	Yes	Validation mode
liftover_level	string or bool	No	Controls genomic liftover. True performs full liftover, primary excludes alternative scaffolds, and False disables liftover. Defaults to True
legacy_genomic_structure	bool	No	Controls the structure of primary assembly loci in the response. False uses the current VariantValidator-compatible structure. True returns the legacy REST VariantValidator structure. Defaults to False

---

Example

[
  {
    "variant_description": "17-50198002-C-A",
    "genome_build": "GRCh38",
    "transcript_model": "refseq",
    "select_transcripts": "mane_select",
    "checkonly": false,
    "liftover_level": false,
    "legacy_genomic_structure": false
  }
]

---

Example Response

{
  "17-50198002-C-A": {
    "errors": [],
    "flag": null,
    "17-50198002-C-A": {
      "p_vcf": "17-50198002-C-A",
      "g_hgvs": "NC_000017.11:g.50198002C>A",
      "selected_build": "GRCh38",
      "genomic_variant_error": null,
      "genomic_variant_warnings": null,
      "hgvs_t_and_p": {
        "NM_000088.4": {
          "t_hgvs": "NM_000088.4:c.589G>T",
          "p_hgvs_tlc": "NP_000079.2:p.(Gly197Cys)",
          "p_hgvs_slc": "NP_000079.2:p.(G197C)",
          "select_status": {
            "mane_select": true
          },
          "gene_info": {
            "symbol": "COL1A1",
            "hgnc_id": "HGNC:2197"
          },
          "transcript_version_warning": null,
          "gapped_alignment_warning": null,
          "gap_statement": null,
          "transcript_variant_error": null
        }
      }
    }
  },
  "metadata": {
    "variantvalidator_version": "4.0.0",
    "variantvalidator_hgvs_version": "4.0.0",
    "vvta_version": "vvta_2025_02",
    "vvseqrepo_db": "VV_SR_2025_02/master",
    "vvdb_version": "vvdb_2025_3",
    "variantformatter_version": "4.0.0"
  }
}

---

Behaviour

• Parses genomic and VCF-like variant inputs
• Performs genomic → transcript → protein mapping
• Applies transcript filtering based on select_transcripts
• Supports batch submission via arrays or pipe-delimited input
• Optionally performs genome build liftover
• Returns the current VariantValidator-compatible genomic structure by default
• Can return the legacy REST VariantValidator genomic structure when explicitly requested

---

Legacy Genomic Structure

legacy_genomic_structure controls the structure used to report primary assembly loci.

The default is:

"legacy_genomic_structure": false

This returns the current genomic structure, consistent with VariantValidator.

Set:

"legacy_genomic_structure": true

only when compatibility with the legacy REST VariantValidator output is required.

This option changes the response structure only. It does not alter variant validation, transcript mapping, or the behaviour of liftover_level.

The legacy structure is disabled by default because it does not match the current VariantValidator output structure.

---

Notes

• Multiple inputs:
• "17-50198002-C-A|17-50197802-G-T" as a pipe-delimited string
• ["17-50198002-C-A", "17-50198002-C-T"] as a JSON array
• Limit submissions to 10 variants
• Fastest endpoint for genomic inputs
• Transcript selection behaviour is defined in transcript_selection.md
• Prefer mane_select, mane, or explicit transcript IDs for performance
• Avoid all and raw unless full transcript enumeration is required
• Disable liftover_level where not needed to maximise performance
• Leave legacy_genomic_structure as false unless compatibility with the legacy REST VariantValidator output is specifically required