From 741e3fa2c56ef954c09b1382edec2dd961a08c76 Mon Sep 17 00:00:00 2001 From: Abdeltoto Date: Sat, 25 Apr 2026 21:34:52 -0400 Subject: [PATCH] docs: improve validation report reference Made-with: Cursor --- docs/framework/report.md | 62 +++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 14 deletions(-) diff --git a/docs/framework/report.md b/docs/framework/report.md index fcda43c2ab..a43dc6d2bb 100644 --- a/docs/framework/report.md +++ b/docs/framework/report.md @@ -7,43 +7,64 @@ script: ## Validation Report -All the `validate` functions return the Validation Report. It's an unified object containing information about a validation: source details, found error, etc. Let's explore a report: +All the `validate` functions return a Validation Report. It is a unified object containing +information about a validation run: whether the data is valid, validation statistics, top-level +metadata errors, and task-level errors for each validated resource. Let's explore a report: ```python script tabs=Python from frictionless import validate -report = validate('capital-invalid.csv', pick_errors=['duplicate-label']) +report = validate("capital-invalid.csv", pick_errors=["duplicate-label"]) print(report) ``` -As we can see, there are a lot of information; you can find its details description in "API Reference". Errors are grouped by tables; for some validation there are can be dozens of tables. Let's use the `report.flatten` function to simplify errors representation: +The main report fields are: + +- `report.valid`: whether the whole validation run passed. +- `report.stats`: aggregate counts such as tasks, errors, warnings, and elapsed seconds. +- `report.errors`: top-level errors that are not associated with a specific validation task. +- `report.tasks`: task reports, usually one per validated resource. + +Task reports contain their own `valid`, `place`, `labels`, `stats`, `warnings`, and `errors` +properties. For example, package and inquiry validation can produce multiple tasks. + +Let's use the `report.flatten` function to simplify error representation: ```python script tabs=Python from pprint import pprint from frictionless import validate -report = validate('capital-invalid.csv', pick_errors=['duplicate-label']) -pprint(report.flatten(['rowNumber', 'fieldNumber', 'code', 'message'])) +report = validate("capital-invalid.csv", pick_errors=["duplicate-label"]) +pprint(report.flatten(["taskNumber", "rowNumber", "fieldNumber", "code", "message"])) ``` -In some situation, an error can't be associated with a table; then it goes to the top-level `report.errors` property: +`flatten()` returns a list of rows using the requested property names. It includes top-level +`report.errors` and all `report.tasks[].errors`; `taskNumber` is added for task-level errors. + +In some situations, an error can't be associated with a validation task; then it goes to the +top-level `report.errors` property: ```python script tabs=Python from frictionless import validate -report = validate('bad.json', type='schema') +report = validate("bad.json", type="schema") print(report) ``` +For convenience, `report.task` is available when the report has exactly one task, and +`report.error` is available when the report has exactly one error. Similarly, `task.error` is +available when a task has exactly one error. + ## Validation Errors -The Error object is at the heart of the validation process. The Report has `report.errors` and `report.tables[].errors` properties that can contain the Error object. Let's explore it: +The Error object is at the heart of the validation process. The Report has `report.errors` and +`report.tasks[].errors` properties that can contain Error objects. Let's explore one: ```python script tabs=Python from frictionless import validate -report = validate('capital-invalid.csv', pick_errors=['duplicate-label']) -error = report.task.error # it's only available for 1 table / 1 error sitution +report = validate("capital-invalid.csv", pick_errors=["duplicate-label"]) +error = report.error # available only for single-error reports print(f'Type: "{error.type}"') print(f'Title: "{error.title}"') print(f'Tags: "{error.tags}"') @@ -52,17 +73,30 @@ print(f'Message: "{error.message}"') print(f'Description: "{error.description}"') ``` -Above, we have listed universal error properties. Depending on the type of an error there can be additional ones. For example, for our `duplicate-label` error: +Above, we have listed universal error properties. Depending on the type of error, there can be +additional properties. For example, for our `duplicate-label` error: ```python script tabs=Python from frictionless import validate -report = validate('capital-invalid.csv', pick_errors=['duplicate-label']) -error = report.task.error # it's only available for 1 table / 1 error sitution +report = validate("capital-invalid.csv", pick_errors=["duplicate-label"]) +error = report.error print(error) ``` -Please explore "Errors Reference" to learn about all the available errors and their properties. +Some common location properties are: + +- `rowNumber`: the row where the error occurred. +- `fieldName` / `fieldNumber`: the field where the error occurred, for field-specific errors. +- `cells`: the full row values at the point where the row-level or cell-level error was detected. +- `cell`: the specific cell value that failed, for cell-level errors. + +This means that `cells` provides row context, while `cell` points to the individual problematic +value when the error is tied to a specific field. For example, an `extra-cell` error includes both +the complete row in `cells` and the extra value in `cell`. + +Please explore the [Errors Reference](../errors/cell.html) to learn about all the available +errors and their properties. ## Reference