ISOF
Isotopic
Open Format.
ISOF is a free and open file format for the exchange of isotopic data between laboratories, research institutions, environmental agencies and software systems. The format is a structured JSON container that bundles samples, isotopic measurements, analytical methods, purification yields, and an optional cryptographic signature. KINOS implements ISOF as its native import and export format.
A single JSON container,
completely self-describing.
Ten root fields, three of which are mandatory.
An ISOF file is a JSON document with a fixed root structure. Only isof_version, created_at and samples are required; all other fields are optional and allow progressive enrichment of the analytical context.
The format is designed for forward compatibility: unknown fields must be ignored by readers, ensuring that future extensions of the specification do not break existing tools. Sample and method identifiers are local to the file, with no global registry required for interoperability.
Encoding is UTF-8 only. Numerical values follow the standard JSON representation. Compressed variants use .isof.gz as extension.
| Field | Type | Required | Description |
|---|---|---|---|
| isof_version | string | Yes | Specification version. Currently "1.0". |
| created_at | ISO 8601 | Yes | UTC timestamp of file generation. |
| samples | array | Yes | List of samples and their isotopic measurements. |
| created_by | object | No | Software identity and operator information. |
| project | object | No | Global project context (code, client, period, location). |
| methods | object | No | Dictionary of analytical methods used (digestion, purification, instrumentation). |
| pipelines | object | No | Sequences of methods composing a complete analytical pipeline. |
| purification | object | No | Purification yields per sample and per element. |
| assignments | array | No | Links between methods, pipelines and samples. |
| signature | object | No | Cryptographic signature block (see section 02). |
Three layers of trust,
verifiable offline.
ISOF separates three concerns that are usually conflated: integrity (the file has not been modified), authenticity (the file comes from a verified party), and confidentiality (the contents are unreadable to unauthorised third parties). Each is addressed by a distinct, optional mechanism that can be combined.
SHA-256 hash of canonical content
A canonical SHA-256 digest is computed over the scientific content and embedded in the signature block. Any modification after export breaks the hash. Mandatory for any signed ISOF file. No identity verification.
ECDSA P-256 signature backed by PKI
The SHA-256 hash is signed with the laboratory's private key (ECDSA P-256). The associated certificate is embedded in the file. Any recipient verifies the chain locally, with no network connection required.
Asymmetric encryption of payload
The samples block can be encrypted with the recipient's public key (X25519 key encapsulation, AES-256-GCM payload). Metadata remains readable for routing and audit, but the scientific content is protected.
A three-tier chain of trust.
For level 2 signatures, ISOF defines a reference PKI consisting of three certificate authorities. The chain is verifiable offline: Root CA → Issuing CA → Laboratory certificate. The Root CA and Issuing CA certificates are embedded by any conforming ISOF reader, including KINOS.
The laboratory's private key is generated locally on the lab's machine and never leaves it. Only the Certificate Signing Request (CSR), containing the public key and identity, is sent to the Issuing CA for signature. The returned certificate is then used to sign ISOF files.
A Certificate Revocation List (CRL) is embedded in each signed ISOF file, allowing offline verification of certificate validity. An online fallback is available but never required.
1
ISOF Root CA
Top of the chain. Private key stored offline in a physical safe. Signs only the Issuing CA.
2
ISOF Issuing CA
Signs laboratory certificates. Private key on hardware security module (HSM).
Laboratory certificate
Issued per laboratory. Private key stays on the lab's local machine. Renewed annually.
A Python reference,
free to use, free to extend.
The isof package on PyPI.
A reference implementation of ISOF v1.0 is published as the Python package isof. It provides reading, writing, validation, signature and verification of ISOF files, with full support for all three trust levels.
The package is permissively licensed and intended to be reused by any third-party software that needs to read or write ISOF files. KINOS uses this package internally; nothing prevents another laboratory information system from doing the same.
The implementation is fully tested (56 unit tests covering the v0.1.0 surface) and validated against canonical ISOF samples signed at all three levels of the trust hierarchy.
Install from PyPI
Python 3.10+. Pure Python, no compiled dependencies.
An open format,
by design.
Open specification
The ISOF v1.0 specification is publicly available, royalty-free, and can be implemented by anyone. No registration, no licence fee, no usage tracking. The format belongs to the scientific community.
Verifiable offline
All trust mechanisms (hash, signature, encryption, revocation) work without network connection. ISOF is usable in air-gapped environments, on isolated networks, or in field conditions without connectivity.
Software-agnostic
ISOF does not depend on any particular software. KINOS implements it, the isof Python package reads and writes it, and any LIMS or analytical platform can integrate it without contractual dependency.
Forward compatible
Unknown fields are ignored by readers. Future extensions of the specification (quality flags, standards registry, global method URIs) will not break existing files or implementations.