VCF Text Format Rules

Sources: [VCF43] §1.3 "Data lines" — tab-delimited format, field order, missing value . syntax; §1.3.1 "Fixed fields" — CHROM/POS/ID/REF/ALT/QUAL/FILTER/INFO serialization; §1.3.2 "Genotype fields" — FORMAT:sample colon-separated encoding, GT allele/phase syntax; §1.0.2 "Character encoding" — percent-encoding of special characters. BGZF compression for .vcf.gz follows [SAM1] §4.1. See References.

These rules apply to the VCF text arm of the unified Writer. The Writer selects VCF text encoding when constructed with OutputFormat::Vcf or OutputFormat::VcfGz.

vcf_writer.output_formats

The unified Writer MUST support three output modes: uncompressed VCF (plain io::Write), BGZF-compressed VCF (.vcf.gz via BgzfWriter), and BCF binary. OutputFormat::from_path MUST return an error for unrecognized file extensions rather than silently defaulting.

[VCF43] §1.3 "Data lines" — tab-delimited, 8 fixed columns + FORMAT + samples

vcf_writer.tab_delimited

Data lines MUST be tab-delimited with exactly 8 fixed columns (CHROM through INFO) plus FORMAT and one column per sample when genotype data is present. Lines MUST end with \n.

vcf_writer.missing_dot

Missing values MUST be serialized as .: missing QUAL, missing ID, missing INFO (entire column), missing ALT, and missing individual sample values.

vcf_writer.info_serialization

INFO fields MUST be serialized as semicolon-separated key=value pairs. Flag-type fields emit the key only (no =). Multiple values within a field MUST be comma-separated. An empty INFO column MUST be written as ..

vcf_writer.format_serialization

FORMAT keys MUST be colon-separated. Per-sample values MUST be colon-separated in the same order as FORMAT keys. Trailing missing values at the end of a sample MAY be omitted.

_[VCF43] §1.3.2 "Genotype fields" — GT: allele[sep allele]_, sep is /or|, missing allele .*

vcf_writer.genotype_serialization

GT values MUST be serialized as allele indices separated by / (unphased) or | (phased). Missing alleles MUST be .. Examples: 0/1, 1|0, ./., 0|0|1 (triploid).

vcf_writer.float_precision

Float values MUST be written with sufficient precision to round-trip through parsing (at least 6 significant digits). Trailing zeros after the decimal point SHOULD be omitted for compactness.

vcf_writer.integer_format

Integer values MUST be written as decimal without leading zeros. Negative values MUST use - prefix. The itoa crate or equivalent fast formatting SHOULD be used for performance.

[VCF43] §1.0.2 "Character encoding" — percent-encoding for :;=%, TAB/LF/CR

vcf_writer.percent_encoding

Special characters in field values MUST be percent-encoded per the VCF spec: : → %3A, ; → %3B, = → %3D, % → %25, , → %2C, TAB → %09, LF → %0A, CR → %0D.

vcf_writer.buffer_reuse

The writer MUST reuse an internal line buffer across records to avoid per-record allocation. The buffer is cleared (not deallocated) before each record.

vcf_writer.finish

finish() MUST flush all buffered data and, for BGZF output, write the EOF marker block and finalize the TBI index.