Documentation changelog

This documentation carries a version of its own, independent from the version of Insights and from the version of the API. Every page displays it in the stamp at the bottom, next to the date the page was last reviewed.

How the three version numbers relate

Why three different numbers

Golden rule

The product version says what exists, the API version says what a call returns, the documentation version says what has been written down.

They move at different speeds and cannot be merged into one. A page can be rewritten without any product change, and a product release can ship before its documentation catches up — the stamp is what makes that visible instead of leaving the reader guessing.

Number Where it lives Changes when
Documentation version _docVersion in docfx.json, shown on every page A batch of documentation changes is published. Format YYYY.MM.
Page review date lastReviewed in the page's front matter Someone verifies that a given page still matches reality.
API version apiVersion in the front matter of API pages The page is confirmed against a new API version. See API versioning.
Product version Release notes Insights itself ships.

Reading the stamp

Every page ends with a line like this one:

DOCS 2026.08     REVIEWED 2026-08-28     API 1.7        Documentation changelog →
  • DOCS — the documentation release this page belongs to.
  • REVIEWED — the last time a human confirmed the page against the product. Absent means never formally reviewed since the convention was introduced.
  • API — on API pages, the API version the page was verified against.
Tip

A page whose REVIEWED date is far behind the current DOCS version is not necessarily wrong, but it is the first place to look when the documentation and the product disagree.

Marking a page as reviewed

Add the keys to the YAML front matter of the page. Both are optional and independent:

---
uid: my-page
lastReviewed: 2026-08-28
apiVersion: "1.7"
---

Use the ISO date format, YYYY-MM-DD. apiVersion only makes sense on pages that describe the API; leave it out everywhere else.

Note

The stamp can be suppressed on a page — a landing page, for instance — with _disableDocVersion: true in the front matter.

Publishing a documentation release

  1. Bump _docVersion and _docVersionDate in docfx.json.
  2. Add an entry to the Releases section below, describing what changed and why.
  3. Update lastReviewed on the pages that were actually verified — not on the ones that were merely touched.

Golden rule

Bump lastReviewed only when you have checked the page against the product.

A review date that gets refreshed by a typo fix stops carrying information. If nobody verified the content, the honest date is the old one.

Releases

2026.08

Three sections were reviewed end to end. The scheme described on this page was introduced with this release.

API documentation

Reviewed against the V1.7 Swagger definition, a real integration, and a live read of the metadata endpoints.

  • New: Getting started, an end-to-end walkthrough from token to first data point.
  • New: Querying the API — entity chain, shared filtering conventions, full GET /data reference, aggregation semantics.
  • New: Files and triggers — the /storage and /fileTrigger endpoints.
  • New: Reference data — the identifier referentials, with the small enumerations read live from the API on 2026-08-28, and the unit conversion model (reference = (value − offset) × divisor) documented and verified.
  • New: Recipes — task-oriented examples.
  • New: .NET client and Python client.
  • Fixed: the "API introduction" TOC entry pointed at the User Manual home page.
  • Fixed: the 1.7 row of the API version table was truncated.
  • Fixed: the connection page listed 2 of the 5 OAuth2 scopes.

Technical documentation

An audit of the 93 pages of the section, followed by a content review.

  • New: Technical documentation — the landing page was a single sentence for a 93-page section. It is now a map of the five families.
  • New: Geozones — the page existed but was empty. Written from the V1.7 Swagger; geozones were also absent from the TOC entirely.
  • New: Webhooks or data forwarding? — the two mechanisms overlap and nothing said which to use. The retry policy is now diagrammed, with the point that a failing hook goes silent after roughly half an hour and nothing re-enables it.
  • Fixed: 21 dead links shipped on the published site. Nineteen were written ](./xref:…), which is not xref syntax but a relative link to a file that does not exist; two more were corrupted markdown that rendered as literal text. None was caught by the build, because the targets carry no .md extension.
  • Fixed: 39 pages had no uid, 4 had no title, 9 had several H1s, 4 were reachable from neither the TOC nor any link, and one page was published empty.
  • Reviewed: Master Data — the two-file model, the nine processing phases and the business key are now each explained with a diagram. json/template_file.md announced five root properties and listed six, one of which the sample does not use while omitting one it does.

Calculated variables

The R contract is now documented: what the engine passes to the script, what the script must return, and the anatomy of a formula.

Corrections to this release

  • Querying the API claimed the CustomFilter grammar was unspecified. It is documented — Custom filter query syntax carries the operators, the type rules and a BNF grammar. The page now links to it.
  • Python client stated that no Verity-maintained Python package existed. The datahub-api-connector package supersedes the retired opinum-api-connector, and the page now documents it — version 1.6, its retry model and its parallel-call helper — instead of a hand-rolled client.

Before 2026.08

Changes predating this scheme are not listed. Use the repository history.

DOCS 2026.08 REVIEWED 2026-08-28 Documentation changelog →