diff --git a/docs/user_manual/data-validator.md b/docs/user_manual/data-validator.md index 2049b73cd8..84b09291b0 100644 --- a/docs/user_manual/data-validator.md +++ b/docs/user_manual/data-validator.md @@ -10,13 +10,22 @@ The power-grid-model repository provides an input/update data validator. For performance reasons, the input/update data is not automatically validated. However, it would be advisable to validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors -will raise exceptions, most of them wil just yield invalid results without warning. +will raise exceptions; most of them will just yield invalid results without warning. The main validation functions and classes can be included from `power_grid_model.validation`. ```{seealso} Check the [example](examples/Validation%20Examples.ipynb) for an example of function applications. ``` +```{warning} +When IDs are supplied explicitly, each update ID must occur at most once for each component type within one batch +scenario. The current validator does not detect duplicate IDs in a scenario, and the calculation core leaves the result +undefined; in practice, the later update can overwrite values from an earlier update with the same ID. If one object +needs several fields changed in the same scenario, combine those changes into a single update row. This limitation is tracked in +[issue #1552](https://github.com/PowerGridModel/power-grid-model/issues/1552); the maintainers plan to address it as +part of the [C++ validator migration](https://github.com/PowerGridModel/power-grid-model/issues/1421). +``` + ## Validation Errors Each validation error is an object which can be converted to a compact human-readable message using `str(error)`. diff --git a/tests/unit/test_documentation.py b/tests/unit/test_documentation.py new file mode 100644 index 0000000000..c1af0b196a --- /dev/null +++ b/tests/unit/test_documentation.py @@ -0,0 +1,16 @@ +# SPDX-FileCopyrightText: Contributors to the Power Grid Model project +# +# SPDX-License-Identifier: MPL-2.0 + +from pathlib import Path + + +def test_data_validator_documents_duplicate_update_ids() -> None: + documentation = (Path(__file__).parents[2] / "docs" / "user_manual" / "data-validator.md").read_text( + encoding="utf-8" + ) + + assert "will just yield invalid results without warning" in documentation + assert "{warning}" in documentation + assert "issue #1552" in documentation + assert "C++ validator migration" in documentation