Choose stable check identifiers for a local reporting tool

By Batu · English technical notes

Also published in our Blogger archive.

Direct answer

Automation needs a stable value that is not tied to display copy. The two check IDs use lowercase hyphenated names, while labels are human-facing text. After the example changes “Root README” to “Project README,” the assertion confirms that a saved filter for root-readme still identifies the same observation.

The edge case is editorial rename. Without the separation, a wording improvement can break dashboards, historical comparisons, or suppressions that were keyed by the former label. The uniqueness assertion catches a second failure mode: two checks sharing one ID make a consumer unable to distinguish them.

This convention does not choose a namespace, provide automatic migrations, or determine whether an ID can ever be removed. When an observation changes meaning, add a new ID and publish a mapping. Do not reuse an established ID for a different check merely because its label looks similar.

Complete example

checks = [
    {"id": "root-readme", "label": "Root README"},
    {"id": "license-file", "label": "License file"},
]
identifiers = [check["id"] for check in checks]
assert identifiers == ["root-readme", "license-file"]
assert len(identifiers) == len(set(identifiers))
checks[0]["label"] = "Project README"
assert checks[0]["id"] == "root-readme"
print("ids=root-readme,license-file labels=mutable")

Expected stdout:

ids=root-readme,license-file labels=mutable

Sources

- Official API documentation

Prepared with AI assistance. The example uses synthetic data; its stated limits apply.