Open-Source Code Integration

The ISOF format is open and fully documented. This page introduces the official Python package, implementation rules for third-party readers, and available resources.

The ISOF format is an open standard. IsoFind SAS publishes the necessary tools for its integration into third-party software without requiring an IsoFind license or any commercial agreement.

The isof Python Package

The isof package is published on PyPI under the MIT license. It allows you to read, verify, and export .isof files from any Python environment.

pip install isof # With pandas support for DataFrame export pip install isof[pandas]

Source: github.com/ColinFerrari/isof : MIT license, contributions welcome.

Core Functions

Function / Method	Description
isof.load(path)	Loads an .isof file from disk.
isof.loads(json_str)	Loads from a JSON string (API, database).
report.verify()	Returns a VerificationResult object containing valid, level, signer, signed_at, and reason.
report.is_authentic()	Returns True if the signature is valid (Level 1 or 2).
report.to_pandas()	Returns a tidy DataFrame (one row per isotopic measurement).
report.to_csv(path)	Exports data to a CSV file.
report.samples	List of samples (dicts).
report.methods	Dictionary of analytical methods.
report.created_by	Creation metadata (software, operator, organization).

Exceptions

Exception	Cause
ISOfParseError	Invalid JSON or unrecognized ISOF structure.
ISOfVersionError	Format version not supported by this package version.
ISOfSignatureError	Error during the signature verification process (distinct from an invalid signature).

Implementing an ISOF Reader

Any software can implement an ISOF reader without depending on the Python package. The format is standard JSON with the following rules:

The isof_version, created_at, and samples fields are the only mandatory ones. All other fields are optional. Unknown fields must be ignored (for future extensibility). UTF-8 encoding is mandatory. Floating-point numbers follow the standard JSON representation (no local decimal commas, no quotes).

Level 1 Verification in 4 Lines of Python

import json, hashlib doc = json.loads(raw_text) sig = doc["signature"] scope = sig["scope"] payload = {k: doc[k] for k in scope if k in doc} digest = hashlib.sha256( json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8") ).hexdigest() valid = digest == sig["hash"]

Canonical serialization must use sort_keys=True and separators=(",", ":") (no spaces). A single extra space or a different key order will produce a different hash and invalidate the signature.

Technical Specification

The complete ISOF v1.0 format specification is available at isofind.tech/isof-spec. It covers JSON structure, data types, the format of samples, methods, purification, and signature blocks, canonicalization rules, and the roadmap for future versions.

To report a compatibility issue between your implementation and IsoFind, or to propose a format extension, open an issue at github.com/ColinFerrari/isof or contact colin.ferrari@isofind.tech.