hts-specs: the documents that define SAM, BAM, CRAM and VCF

The specifications, and who owns them

The repository is the home of the specifications for SAM, BAM and related high-throughput sequencing file formats, and it is worth being clear about the governance because that is unusual for a set of file format documents.

These documents are maintained by the Large Scale Genomics work stream of the Global Alliance for Genomics and Health, and information on GA4GH procedures and how to get involved is available in the LSG wiki. Lists of contributors and acknowledgements can generally be found in each individual specification document, which is a convention that keeps the credit with the document rather than in one central file.

The practical consequence is that this is not one person's notes or one company's internal documentation. A format used across the whole genomics field has a specification with a governance process behind it, and improvements or errors are requested through this repository, with the list of maintainers in MAINTAINERS.md if you need to contact them directly. The README also points to the build instructions in MAINTAINERS.md for how to generate the PDF documents from their source text.

The primary language of the repository is recorded as TeX, which is the practical detail: the documents are LaTeX sources, and the PDFs published on the GitHub Pages site are built from them. The site is samtools.github.io/hts-specs.

The last push to the repository was on 2026-08-25, the repository is not archived, and there are no GitHub releases, which is what you would expect for a document set whose versions are tracked in the file names rather than in tags.

Alignment formats: SAM, BAM, BAI, and the tags that extend them

The alignment data section is the core of the repository, and the four documents split into a canonical spec, a companion spec and an obsolete predecessor.

SAMv1.tex is the canonical specification for the SAM, Sequence Alignment/Map, format, for BAM, its binary equivalent, and for the BAI format used to index BAM files. SAMtags.tex is a companion specification describing the predefined standard optional fields and tags found in SAM, BAM and CRAM files.

The division matters more than it might look. SAMv1 defines the format itself, the records and the fields, while SAMtags defines the extension mechanism, the named optional fields that let tools carry extra information in a way that stays compatible with readers that do not understand it. Two documents because the tag registry grows and changes on a different cadence from the core format, and because a tool that reads SAM correctly still has to know which tags it may ignore.

These formats are discussed on the samtools-devel mailing list, which is the right place to take a question about the meaning of a field, because that list is where the specification's ambiguities get worked out before they are written down.

CRAMv3.tex is the canonical specification for the CRAM format, and CRAMv2.1.tex describes its now-obsolete predecessor. CRAMcodecs.tex contains details of the CRAM custom compression codecs, which is a separate document because the codec set is where the interesting and changeable parts of CRAM live, and the format specification itself refers to it.

And then the index formats, which are the newer additions. The tabix.tex and CSIv1.tex quick references summarize more recent index formats, where the tabix tool indexes generic textual genome position-sorted files, and CSI is htslib's successor to the BAI index format. That is a two-line description of a significant change in the ecosystem, since BAI is index-of-BAM and CSI is a general coordinate-sorted index, which is what lets the same index serve CRAM and other formats.

Further details on CRAM can be found at ENA's CRAM toolkit page and on GA4GH's CRAM page.

Variant calls, features, encryption and the decision not to define a fastq

The VCF section shows the same version discipline as CRAM, with one addition that is worth noting.

VCFv4.5.tex is the canonical specification for the Variant Call Format and its textual VCF and binary BCF encodings, while VCFv4.1.tex through VCFv4.4.tex describe their predecessors. These formats are discussed on the vcftools-spec mailing list, a different list from the one used for SAM and CRAM, which reflects that the two have different communities and different maintainers.

The BCF documents are labelled quick references, and the difference is deliberate. BCFv1_qref.tex summarizes the obsolete BCF1 format historically produced by samtools, and it is explicitly no longer recommended for use, having been superseded by the more widely implemented BCF2. BCFv2_qref.tex describes just the layout of data within BCF2 files. So the repository holds both a summary of a format you should not use and a layout reference for the one you should, and the wording tells you which is which.

BEDv1.tex is the canonical specification for the GA4GH Browser Extensible Data format, and crypt4gh.tex is the canonical specification of the crypt4gh format, which can be used to wrap existing file formats in an encryption layer. The crypt4gh document is the interesting one for anyone thinking about what happens to sequencing data at rest, because it is the layer that adds encryption to formats that have none.

Then the unaligned sequence section, which is where the project makes a decision rather than publishing a format. They do not define or endorse any dedicated unaligned sequence data format. Instead they recommend storing such data in one of the alignment formats, SAM, BAM or CRAM, with the unmapped flag set.

That is a significant position. It means there is one format family to implement rather than several, at the cost of a slightly awkward encoding for pure reads, and the README says it lists the commonest formats below with external links for completeness rather than endorsing them. FASTA is described as an early sequence-only format originally defined by William Pearson's tool of the same name, and FASTQ was designed as a replacement for FASTA, combining the sequence and quality information in the same file, with no formal definition and several incompatible variants, described in a paper by Cock et al.

Transfer protocols, and the versioning machinery behind the PDFs

Two newer documents cover how data moves rather than what it contains, and both are marked as enabling something.

Htsget.md describes the hts-get retrieval protocol, which enables parallel streaming access to data sharded across multiple URLs or files. Refget.md enables access to reference sequences using an identifier derived from the sequence itself.

Both are worth reading as a pair. A reference genome is a large immutable blob that is the same for everyone working on a given assembly, and deriving its identifier from its content means a client can ask for exactly the reference it needs without the server having to maintain a naming registry, and a client that has a different copy can verify they match. The hts-get protocol solves the parallel access problem, where a single URL serving a whole file is a bottleneck for a client that wants a few regions.

The build machinery is the part of this repository that shows real care, and it is visible in the Makefile. The default target is pdf, and the PDFS list enumerates every document that gets built, including the BEDv1.pdf conditionally on whether CIRCLECI is set, which is the continuous integration service skipping the lualatex build.

The interesting part is the three-directory pattern. The rule for each document is that a new/<name>.pdf is built from <name>.tex, then compared against diff/<name>.pdf, and a version file new/<name>.ver records the result. The generic rule is:

new/%.pdf: %.tex | new
	$(LATEXMK) --output-directory=new $<

The LATEXMK variable is set to latexmk with a pdf engine using pdflatex, and the Makefile explains how to override it to use a previous controller script if your installation does not have latexmk. There is a separate LATEXDIFF_ENGINE using the LATEX=pdflatex configuration, which is what performs the comparison against the previous version.

The result is that the repository can show a reader the exact diff between two versions of a specification, and can assert that a change to a document is the only change. For a format that other people's software is written against, being able to see what changed and when is worth more than any feature, and the older .tex files staying in the tree is what makes that possible.

How to read a specification like this, and what to expect from it

There is no installation step here and there is no API, and the way to use this repository is different from the way you would use a library.

The practical entry point is the published PDF for the document you care about, and the README says that links in bold point to the corresponding PDFs on the GitHub Pages website. If you want the source, the .tex file for each document is in the repository root next to its PDF, which means you can read the specification as text in an editor rather than as a rendered document, and that is much easier when you are looking for a specific field name.

The build, if you want to regenerate the PDFs, is the Makefile with latexmk and pdflatex, and the README sends you to the build instructions in MAINTAINERS.md for the details. The CircleCI directory at the root and the continuous integration conditional in the Makefile tell you that the documents are rebuilt automatically on every change, which is why the checked-in PDFs are trustworthy rather than stale.

The structure of the site is visible in the repository layout. There is a _config.yml, an _includes/ directory, a _layouts/ directory, an img/ directory for the figures that the CRAM documents in particular need, an examples/ directory with a vcf/ subdirectory of sample data, a scripts/ directory, a pub/ directory, a test/ directory and an index.md. So the site is a Jekyll build, the examples directory carries real sample files, and there is a test directory for the build itself.

What you will not find is a tutorial. These are normative documents, written for people who already know the domain, and the audience for the specification is the person implementing a reader or writer for the format. The topics tags are consistent with that: the repository is not tagged as a library or a tool, because it is neither.

The maintainers are reachable through MAINTAINERS.md, and the format discussions happen on two different mailing lists depending on whether the question is about alignments or about variant calls.

Editorial conclusion

Adopt hts-specs as the reference when you are writing or debugging a tool that reads or writes sequencing files, because these are the documents the tools themselves are built from and the version history is published alongside. Do not treat it as a tutorial, since it is a specification and assumes you already know what an alignment record is. Before you implement against a format, check which version of the document you are reading against, since the previous versions stay in the tree, and use the newest canonical document rather than a quick reference when the details matter.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. samtools/hts-specs on GitHub