spectrl: URL-safe interchange for mass spectra
Abstract
spectrl defines and implements a URL-safe interchange format for individual mass spectra. A spectrl.v3 token contains peak arrays, array units, precursor information, modeled metadata based on mzML controlled-vocabulary terms. The payload is encoded as CBOR and Base64url text with a CRC-32 integrity checksum. Peak arrays use four versioned numeric encodings: raw words, byte shuffle, modular delta plus byte shuffle, and quantized words. Fixed profiles support exact recovery or controlled numerical loss. Compression applies once to the complete CBOR document, with zlib as the default and raw and Brotli alternatives. Applications can register namespaced custom numeric encodings and extensions. PSI-MS accessions retain scientific array and metadata identity. Selected source, instrument, software, and processing context can accompany each spectrum. Because the spectrum is carried in the token, it can be placed in URL fragments, query parameters, data URIs, QR codes, notebooks, and publication supplements without requiring a repository lookup or application backend. The Python package provides encoding, decoding, validation, URL helpers, a command-line interface, and conversion from mzmlpy spectrum objects. A separate TypeScript implementation supports browsers and Node, and shared conformance vectors test agreement between the two implementations. spectrl is intended for self-contained spectrum exchange and application handoffs. Repository-based identifiers remain more appropriate when persistent archival lookup is the primary goal.
