Versions and changes

Two semantic versions and one fingerprint, all in index.json under versions:

  what it versions moves when
versions.release what is served: the API files and the cleaned tables, as one release (the repository’s VERSION, tag vX.Y.Z) MAJOR: a file, field or column renamed or removed, a CSV column added or reordered, a unit or frame changed; MINOR: something added; PATCH: a value or text corrected
schema_version (also versions.schema) the JSON contract of these documents MAJOR: a field renamed or removed; MINOR: a field or endpoint added; the changelog below
data_version (also versions.data) nothing: it is the SHA-256 of the served data, a fingerprint whenever a served measurement, geometry or score file changes

release in index.json gives the release’s date, tag, release page, changelog and base_url: the raw files of that release’s frozen copy at its tag, which never change. release_base_url is the same copy on this site, and versions.json lists every release. To pin an analysis to one release, fetch from one of them (see Versions and pinning):

REL=$(curl -s -A "aij-client/1.0" $BASE/index.json | jq -r .release_base_url)   # .../api/3.2.1
curl -s -A "aij-client/1.0" "$REL/cases/A/points.csv" | head -3

Within a major schema_version the API only adds: new fields, new endpoints, new runs. Clients must ignore fields they do not know. A field is renamed or removed only in a new major version, listed below. index.json serves the same changelog as changelog; the releases are in CHANGELOG.md.

Changelog

2.6.0 (2026-11-06)

  • Added to cases/{id}/validation.json: grid_study, the grid-convergence study of the OpenFOAM fixture (Cases A and E; null elsewhere): four meshes with every cell edge shrinking by sqrt(2), the scores on each mesh, the method (Roache’s grid convergence index by the Celik et al. 2008 procedure, computed by foamgci), and bands, cases/{id}/grid/openfoam12-realizableKE.csv: per point the measured value, the value on the second mesh (cell scale 1.00) and that mesh’s band. The study ran the fixture with the eddy-viscosity cap lifted, so its values are its own, not the served run’s.

2.5.0 (2026-10-18)

  • Added: cases/{id}/probes.csv, the published points to probe, one row per measured row of the point table: the key columns a scored file carries (point_id, config, campaign, instrument, run, wind_direction_deg), x y z in the case frame, and scored_as, the families the row is scored in (vector, \(k\), thermistor_bracket, concentration, theta). Linked from cases/{id}.json probes.
  • Added to cases/{id}.json: scoring (the reference speed the measured side is divided by, the constants of theta, the conventions and the metric meanings: what validation/score_submissions.py scores with) and inflow (the benchmark’s approach-flow data and fit under benchmark_data; the inlet this repository RECOMMENDS under recommended, a log law from the fit with \(k\) and epsilon from the neutral ABL relations, or the tabulated profile where no log law fits; the flow-direction convention; what Eddy3D’s runs used, quoted from their snapshots).
  • Added: submissions.json and submissions/{slug}.json, the community results: every folder under submissions/ in the repository, scored in this build by validation/score_submissions.py (run it from a checkout to score your own), with each submission’s own values at the published points served as submissions/{slug}/{id}.csv. A submission names its solver as free text (a slug); Eddy3D’s engines keep the engine enum and the validation documents. The repository’s own example (example: true) is served like any other and marked.
  • Added: cases/{id}/inflow_openfoam.txt, the recommended inlet as OpenFOAM 12 files in one text: 0/U, 0/k and 0/epsilon (atmBoundaryLayerInlet* where a log law fits, fixedProfile tables where not), 0/nut with the nutkAtmRoughWallFunction ground patch, and system/probes, a probes function object with the case’s published points.
  • Changed: index.json license_detail says what the licence covers: the data CC BY 4.0 (LICENSE-DATA), the code MIT (LICENSE).

2.4.0 (2026-10-18)

  • Added to index.json: cite.api, the citation of the API release (title, version, url, release_url, doi, apa, bibtex, csl_json). url is the pinned address of the release, /api/<release>/index.json; doi is null until Zenodo mints one for the release.
  • Added to cases/{id}.json: citation, the Zenodo dataset of the case as apa and bibtex.
  • Added to the stats of geometry.json and to the entries of the geometry index: bodies, body_contacts, inconsistent_triangles and min_body_volume, beside edges_boundary. watertight is true when every body is closed, consistently wound and positive in volume.
  • Changed: the geometry.stl of Cases E, F and M. Every body is a closed, consistently wound, outward body; Cases F and M stand on a 1 m base slab, so the bounding box of each starts at \(z = -1\thinspace\mathrm{m}\), and triangles and data_version change with the files.
  • Added: the layout figure of each case, case-<id>-layout.png, is the first entry of figures of the validation results of that case (Cases A to M); the agreement figures colour their points by the groups of that figure.

2.3.0 (2026-10-18)

  • Added: release-numbered paths. Every release is a frozen copy of the whole API under /api/<release>/ (for example /api/3.0.0/index.json, /api/3.0.0/cases/F.json). Every URL to a file of the API inside a copy points into the same copy (versions.json, served only at the unversioned path, aside), so a client that starts there never leaves it, and nothing under it changes once the release is tagged. The unversioned /api/ paths are unchanged and always equal the newest release (the latest alias).
  • Added: /api/versions.json (schema versions), the list of every release, newest first: version, date, status (latest or superseded), schema_version, data_version, base_url, tag, release page and changelog. Release 2.0.0 predates the layout and is not regenerated: /api/2.0.0/ holds the files of its tag byte for byte, with only their own addresses rewritten into the copy (scripts/host_release.py derives it and the release check re-derives it).
  • Added to index.json: tree (release in a frozen copy, latest in the alias), release_base_url (the frozen copy of versions.release; equal to base_url inside that copy) and versions_url. In a frozen copy base_url and fallback_base_url name that copy, and release.base_url (the raw files at the release tag) now ends in the release number; paths below it are unchanged.
  • Added: Cases F to M, thirteen cases in all (the case_ids of index.json): their cases.json entries, cases/{id}.json, points, approach flow, geometry (STL) and validation documents, and pairs files for the runs that exist. Every case has at least one scored run; an engine that has none for a case is pending there. cases.json and validation.json list thirteen cases (the schemas fixed the length at five).
  • Added: the point table’s columns of schema 2.0.0 (the cleaned release) are served in points.json and points.csv: campaign and run, uv uw vw, C c_rms concentration_ratio, T T_rms, uc vc wc, uT vT wT, velocity_ratio_sd and k_ratio; instrument takes the new values cup_anemometer, sonic_anemometer, ldv, hydrocarbon_analyser and sorbent_gc_ecd. A document lists only the columns a case has.
  • Added: four engines, openfoam12-kEpsilon and openfoam12-kOmegaSST, which exist for Case I only (the closures other than realizable k-epsilon, solved on one mesh), and umf-realizableKE and umf-buoyantKEpsilon, Eddy3D’s buoyant microclimate engine (urbanMicroclimateFoam, an OpenFOAM 12 solver) under its two closures, which exist for Cases J and L (umf-buoyantKEpsilon for J only). engines in cases.json and cases/{id}.json lists an engine only for the cases it applies to.
  • Added to each result of validation.json: notes, a list of the caveats that come with the run (what the model leaves out, what the measurement cannot say, how the solve ended); empty where the run has none recorded. Cases F, G and M have several runs on one engine (Case F: one per vertical frame, Case G: one per arm of a drag sweep, Case M: one per turbulent Schmidt number, each as configuration), all sharing the engine’s pairs file; the first column of Case F’s and Case G’s names the frame or the arm, and Case M’s holds the three Schmidt numbers as columns.

2.2.0 (2026-10-18)

  • Added: versions.release, the semantic version of the published data and API (the repository’s VERSION; tag vX.Y.Z; rules in CHANGELOG.md), and release with its date, tag, release page and base_url, the raw files of exactly that release (the tag never moves). schema_version stays the version of this JSON contract.

2.1.0 (2026-10-15)

  • Correction: index.json gave each templated endpoint (cases/{id}.json, schemas/{name}.schema.json, …) its URI template under url, which is not a URL and answered 404 when followed. A templated endpoint now says templated: true and lists every concrete file under urls; url is given only for single-file endpoints, and no URL anywhere contains a brace. llms.txt lists the concrete files the same way.

2.0.0 (2026-10-15)

  • Breaking: cases/{id}.json gotchas is renamed known_issues.
  • Breaking: licence is replaced by license, the SPDX identifier CC-BY-4.0; index.json licence_detail is license_detail.
  • Breaking: generated_from and generated_at are removed. data_version, a SHA-256 over every served measurement, geometry and score file, changes when, and only when, the data does; the build is reproducible byte for byte.
  • Breaking: links to JSON resources are named url (was file, endpoint, endpoint_json); file downloads are objects with url, path, media_type, bytes and sha256 (points csv, approach-flow csv, run pairs, geometry files, the archive, and every entry of index.json files).
  • Breaking: a validation result’s figures is a list of {url, caption}.
  • Added: validation.json, every case and engine in one table with each run’s headline scores.
  • Added: cases/{id}/pairs/{engine}.csv, the per-point measured and modelled values behind every scored run, so any score can be recomputed; linked from each result as pairs.
  • Added: cases/{id}/approach_flow.csv, the measured approach-flow profile in SI units.
  • Added: schemas/{name}.schema.json, the JSON Schema (draft 2020-12) of every document, named by its $schema and embedded in openapi.json.
  • Added: run_id on every validation result; geometry renders and captions in geometry.json.
  • Added: download URLs carry ?v=<SHA-256 prefix>, so a changed file has a new URL and no cache serves a stale copy.
  • Added: /llms.txt at the site root, and schema.org Dataset metadata on the home page.

1.0.0 (2026-10-14)

  • First release.

Regenerating and checking

# everything (cleaned tables, figures, API), in the pinned image: what CI runs
docker run --rm -v "$PWD:/w" -w /w "$(cat scripts/BUILD_IMAGE)" bash scripts/build_all.sh

# the API alone
uv sync --frozen
uv run python scripts/build_api.py          # builds docs/api/<VERSION>/ and docs/api/, the case pages and the site includes, then verifies
uv run python scripts/build_api.py --check  # verify only

The build writes the frozen copy of the release in VERSION (docs/api/<VERSION>/) and then the latest alias (docs/api/), from the same code, and writes docs/api/versions.json. It never touches another release’s copy: once a release is tagged, python scripts/release.py check fails if its copy differs from the tag. A new release therefore adds one directory to docs/api/ and moves the alias. Copies are kept from release 3.2.1 on; the copies of earlier releases were withdrawn before anyone used them.

The build is a pure function of the repository: no timestamps and no commit hashes, so rebuilding unchanged inputs gives byte-identical files. On every push and pull request, CI rebuilds everything in Python 3.12.12 (an image pinned by digest) with every package pinned by hash, and fails if anything differs from what is committed or if served content changed without the release version moving. The site deploys only after that check passes, and a new VERSION is then tagged and released. Verification covers:

  • every document against its JSON Schema, and openapi.json against the OpenAPI 3.1 specification;
  • every file’s size and SHA-256 against index.json, and every file served against the files listed, so a stray or missing file in any tree fails;
  • every link inside every document, including that each ?v= matches the file it points at, and that a link in a release’s copy never leaves the copy (versions.json is the one file outside it);
  • that the alias is the newest release, file for file: data files byte for byte, documents once their own address is accounted for;
  • versions.json against a rebuild of it from the trees on disk and CHANGELOG.md;
  • the point counts, the STL triangle counts and the archive’s contents.

The point tables come from clean/ (points_source in each points.json says which file). The scores and pairs come from the snapshots in validation/results/, each registered in RUNS in scripts/build_api.py; an unregistered snapshot stops the build.