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), andbands, 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}.jsonprobes. - 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) andinflow(the benchmark’s approach-flow data and fit underbenchmark_data; the inlet this repository RECOMMENDS underrecommended, 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
solveras free text (a slug); Eddy3D’s engines keep theengineenum 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_detailsays 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).urlis the pinned address of the release,/api/<release>/index.json;doiis null until Zenodo mints one for the release. - Added to cases/{id}.json:
citation, the Zenodo dataset of the case asapaandbibtex. - Added to the
statsof geometry.json and to the entries of the geometry index:bodies,body_contacts,inconsistent_trianglesandmin_body_volume, besideedges_boundary.watertightis true when every body is closed, consistently wound and positive in volume. - Changed: the
geometry.stlof 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}\), andtrianglesanddata_versionchange with the files. - Added: the layout figure of each case,
case-<id>-layout.png, is the first entry offiguresof 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 (thelatestalias). - Added:
/api/versions.json(schemaversions), the list of every release, newest first: version, date, status (latestorsuperseded), 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(releasein a frozen copy,latestin the alias),release_base_url(the frozen copy ofversions.release; equal tobase_urlinside that copy) andversions_url. In a frozen copybase_urlandfallback_base_urlname that copy, andrelease.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_idsof index.json): their cases.json entries,cases/{id}.json, points, approach flow, geometry (STL) and validation documents, andpairsfiles for the runs that exist. Every case has at least one scored run; an engine that has none for a case ispendingthere.cases.jsonandvalidation.jsonlist 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.jsonandpoints.csv:campaignandrun,uvuwvw,Cc_rmsconcentration_ratio,TT_rms,ucvcwc,uTvTwT,velocity_ratio_sdandk_ratio;instrumenttakes the new valuescup_anemometer,sonic_anemometer,ldv,hydrocarbon_analyserandsorbent_gc_ecd. A document lists only the columns a case has. - Added: four engines,
openfoam12-kEpsilonandopenfoam12-kOmegaSST, which exist for Case I only (the closures other than realizable k-epsilon, solved on one mesh), andumf-realizableKEandumf-buoyantKEpsilon, Eddy3D’s buoyant microclimate engine (urbanMicroclimateFoam, an OpenFOAM 12 solver) under its two closures, which exist for Cases J and L (umf-buoyantKEpsilonfor J only).enginesincases.jsonandcases/{id}.jsonlists 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 asconfiguration), 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), andreleasewith its date, tag, release page andbase_url, the raw files of exactly that release (the tag never moves).schema_versionstays 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 saystemplated: trueand lists every concrete file underurls;urlis 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
gotchasis renamedknown_issues. - Breaking:
licenceis replaced bylicense, the SPDX identifier CC-BY-4.0; index.jsonlicence_detailislicense_detail. - Breaking:
generated_fromandgenerated_atare 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(wasfile,endpoint,endpoint_json); file downloads are objects withurl,path,media_type,bytesandsha256(pointscsv, approach-flowcsv, runpairs, geometry files, the archive, and every entry of index.jsonfiles). - Breaking: a validation result’s
figuresis 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
$schemaand embedded in openapi.json. - Added:
run_idon 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.jsonagainst 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.jsonis 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.jsonagainst a rebuild of it from the trees on disk andCHANGELOG.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.