Specification

The ISOF Specification

ISOF binds an isotopic result to the context that makes it evidence, its uncertainty, reference materials, co-measured geochemistry and sampling depth, in a single JSON document that any recipient can verify offline.

The standard at a glance

Format version1.3

SerializationSingle JSON document

SignatureSHA-256 / ECDSA P-256

LicenseCC-BY 4.0 (spec) / MIT (code)

Overview

What ISOF specifies

ISOF (Isotopic Secure Open Format) is an open format for exchanging isotopic and geochemical measurements together with the analytical context that makes them interpretable. An artefact is a single JSON document, conventionally carrying the .isof extension, rather than an archive of separate files. It can be opened and read with nothing more than a text editor.

The document groups its contents into top-level blocks: the samples and their measurements, the analytical methods, the purification record, authorship and project metadata, and a signature. Because every measurement lives inside the sample it belongs to, the sample is the natural unit of the format, and an isotopic ratio never travels detached from its elemental, molecular and depth context.

One evidentiary object

Ratio, uncertainty, reference materials, co-measured geochemistry and depth bound into one file that travels as a unit.

Signed at the source

A single signature over the signed scope lets any recipient confirm the artefact is intact and, at level 2, authentic.

Offline by design

Verification uses trust anchors embedded with the implementation, with no network, no third party and no cloud service.

Open and non-destructive

Raw and corrected values are both preserved, so data reduction can be reproduced independently from the same artefact.

Container

Top-level structure

An ISOF artefact is a single JSON object. A format-version field lets the schema evolve while older files remain readable; the three additional data classes are optional, and a file that omits them stays valid.

Block	Presence	Description
`isof_version`	required	Format version string (currently `1.3`). Governs how the document is interpreted.
`created_at`	optional	Creation timestamp, ISO 8601.
`created_by`	optional	Producing software, version and operator.
`project`	optional	Project or study, either a structured object or a plain title string.
`doi`, `date`, `location`	optional	Publication DOI, study date and geographic setting when the data are published.
`samples`	required	The core payload. An array of samples, each carrying its identifiers, provenance and nested measurement families (Section: Content model).
`methods`, `purification`	optional	Preparation and analytical methods, and the purification record, linked to the samples.
`signature`	optional	The signature over the signed scope (Section: Signature). Absent in an unsigned artefact.
`encryption`	optional	When present and active, indicates the payload is encrypted for a named recipient, adding confidentiality on top of integrity.

Content model

Measurements and their context

Each sample carries an isotopic family and three additional data classes. All four are part of the core content model, so context travels as first-class, co-signed data rather than as detached supplementary files.

Family	Key fields	Description
`isotope_data`	`element`, `system`, `ratio`, `ratio_2se`, `delta_notation`, `standard`	The isotopic system expressed canonically (e.g. `87Sr/86Sr`, `123Sb/121Sb`), the value with its reported uncertainty, and the reference material to which it is anchored.
`geochem_data`	`element`, `value_normalized`, `uncertainty`, `display_unit`, `method`, `depth_m`	Major, minor and trace element concentrations, with their units, uncertainties and analytical method.
`physico_data`	`parameter`, `value`, `uncertainty`, `method`, `depth_m`	Physicochemical parameters such as pH, redox potential, conductivity, dissolved oxygen or temperature.
`molecules_data`	`nom`, `cas`, `valeur`, `unite`, compound-specific isotopic value	Individual molecular species for compound-specific isotope analysis (CSIA) and organic-geochemical work.

Depth is a property of the measurement, not only of the sample. A depth_m field on individual records lets a down-hole profile, with several analyses along one core or borehole, be represented faithfully as a single signed artefact.

Signature

Two levels over one scope

Integrity rests on a single signature computed over a defined signed scope: the samples, methods and purification blocks taken together. Both levels sign the same scope as one object, so a change to any value in any data class invalidates the signature. No class is signed separately or more weakly than another.

Level 1

SHA-256 integrity

A SHA-256 hash over the signed scope. It lets anyone confirm the data have not changed since export.

It does not identify the signer, since any party can recompute the hash. Fields: level, algorithm, scope, hash.

Level 2

ECDSA P-256 authenticity

An ECDSA P-256 signature carrying the producing laboratory's X.509 certificate. It adds authentication of origin on top of the same integrity guarantee.

Fields: level, algorithm, signed_scope, signature_b64, certificate_chain (laboratory certificate at index 0, Issuing CA at index 1).

Canonicalization

Deterministic serialization

To make the signature reproducible, the signed scope is serialized deterministically before hashing.

The signed scope is encoded with a compact JSON serialization (no insignificant whitespace, key order preserved as produced), shared between the producing software and the verifier so that both hash exactly the same bytes. This plays the same role as a formal canonicalization scheme such as RFC 8785 (JCS): it prevents a signature from failing merely because a file was reformatted in transit. The exact serialization rules are fixed by this specification.

Known limitation. The current scheme preserves key order rather than sorting keys. A file whose keys were reordered by an intermediate tool, without any change to the data, would fail verification. Adopting RFC 8785 lexicographic ordering is the natural path to broaden interoperability with independent implementations, and is envisaged for a future revision.

Trust model

Offline public-key infrastructure

Level-2 signatures are issued under a three-tier X.509 PKI. Every tier can operate offline, which is what makes the format usable in air-gapped forensic, nuclear and defense-adjacent settings.

The Root CA and Issuing CA are distributed as embedded trust anchors alongside the reference implementation, so an artefact is verified by checking the signature over the signed scope and validating the certificate chain up to the embedded anchor, with no network access at any tier. Certificate revocation is out of scope for the format: the verifier performs no CRL or OCSP lookup, and revocation is left to the deploying application where connectivity allows. ISOF makes no assumption about who operates the root, so a national institute, a defense authority or a consortium can each run an independent root and distribute its own anchors.

Tier	Role	Typical validity
Root CA (offline)	Self-signed anchor. Signs only Issuing CA certificates. Held offline.	~20 years
Issuing CA (offline)	Signs laboratory certificates. Operated by a community body or, in sovereign deployments, a national authority.	~5 years
Laboratory certificate	End-entity certificate held by a laboratory or named analyst. Used to sign ISOF artefacts.	1 to 3 years

Example

An artefact at a glance

A minimal level-2 artefact, abridged. The signature covers the samples, methods and purification blocks; the certificate chain is embedded so the artefact verifies offline.

sample.isof

{
  "isof_version": "1.3",
  "created_by": { "software": "IsoFind", "operator": "Lab" },
  "project": "Sb isotopes, Oruro, Bolivia",
  "doi": "10.1007/s11270-025-08445-6",
  "samples": [{
    "id": "OR-01", "matrix": "water",
    "isotope_data": [{
      "element": "Sb", "system": "123Sb/121Sb",
      "ratio": 0.46, "ratio_2se": 0.02,
      "standard": "SPEX CertiPrep"
    }],
    "geochem_data": [{ "element": "Sb", "value_normalized": 7824, "display_unit": "ug/L" }]
  }],
  "signature": {
    "level": 2,
    "algorithm": "ECDSA-P256-SHA256",
    "signed_scope": ["samples", "methods", "purification"],
    "signature_b64": "MEUCIQ...",
    "certificate_chain": ["<lab-cert>", "<issuing-ca>"],
    "signed_by": "IsoFind SAS"
  }
}

terminal

# Read and verify an artefact with the reference package
pip install isof

import isof
report = isof.load("sample.isof")
result = report.verify()
print(result.valid, result.level, result.signer)

True 2 IsoFind SAS

Availability

Reference implementation

The reference Python package reads, verifies, builds and signs ISOF artefacts. Verification is sufficient for most receiving workflows and requires no network access.

The specification is released under CC-BY 4.0 and the reference implementation under the MIT license. Both are developed in the open, and contributions and critical review from the analytical community are welcome.

Source repository Python package