diff --git a/src/probeinterface/schema/probe.json.schema b/src/probeinterface/schema/probe.json.schema index aed88b5c..35da4d75 100644 --- a/src/probeinterface/schema/probe.json.schema +++ b/src/probeinterface/schema/probe.json.schema @@ -1,5 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://probeinterface.readthedocs.io/schema/probe.json.schema", + "$comment": "Validates probeinterface specification versions matching the 'version' property pattern (currently 0.3.x). The pattern is bumped only when the schema changes incompatibly. See https://probeinterface.readthedocs.io", "type": "object", "properties": { "specification": { @@ -8,7 +10,8 @@ }, "version": { "type": "string", - "pattern": "^\\d+\\.\\d+\\.\\d+$" + "$comment": "Range of specification versions this schema validates. Bump when the schema changes incompatibly.", + "pattern": "^0\\.3\\.\\d+$" }, "probes": { "type": "array", diff --git a/tests/test_schema.py b/tests/test_schema.py new file mode 100644 index 00000000..b3839926 --- /dev/null +++ b/tests/test_schema.py @@ -0,0 +1,29 @@ +import re + +from probeinterface import __version__ +from probeinterface.testing import schema + + +def test_schema_is_annotated(): + """The schema must carry the annotations documenting what it validates.""" + assert schema.get("$schema"), "The schema must declare the JSON Schema draft it uses ('$schema')." + assert "specification versions" in schema.get( + "$comment", "" + ), "The schema '$comment' must document which specification versions it validates." + + +def test_package_version_is_compatible_with_schema(): + """ + The current package (specification) version must match the compatibility pattern + declared by the schema's 'version' property. + + The schema rarely changes, so it stays compatible across many releases. When a + release introduces an incompatible schema change, bump the 'version' pattern in + ``src/probeinterface/schema/probe.json.schema`` (e.g. to allow ``1.x.y``). + """ + pattern = schema["properties"]["version"]["pattern"] + assert re.fullmatch(pattern, __version__), ( + f"The package version ({__version__}) does not match the schema's declared " + f"compatibility pattern ({pattern}). Either this is an incompatible schema " + f"change (update the pattern) or the version is malformed." + )