# Briefs When validating data with Pointblank, it's often helpful to have descriptive labels for each validation step. This is where *briefs* come in. A brief is a short description of what a validation step is checking and it appears in the `STEP` column of the validation report table. Briefs make your validation reports more readable and they help others understand what each step is verifying without needing to look at the code. Briefs can be set in two ways: 1. Globally: applied to all validation steps via the `brief=` parameter in [Validate](../../reference/Validate.md#pointblank.Validate) 2. Locally: set for individual validation steps via the `brief=` parameter in each validation method Understanding these two approaches to adding briefs gives you flexibility in how you document your validation process. Global briefs provide consistency across all steps and save time when you want similar descriptions throughout, while step-level briefs allow for precise customization when specific validations need more detailed or unique explanations. In practice, many validation workflows will combine both approaches (i.e., setting a useful global brief template while overriding it for steps that require special attention). # Global Briefs To set a global brief that applies to all validation steps, use the `Validate(brief=)` parameter when creating a [Validate](../../reference/Validate.md#pointblank.Validate) object: ``` python import pointblank as pb import polars as pl # Sample data data = pl.DataFrame({ "id": [1, 2, 3, 4, 5], "value": [10, 20, 30, 40, 50], "category": ["A", "B", "C", "A", "B"] }) # Create a validation with a global brief ( pb.Validate( data=data, # Global brief template --- brief="Step {step}: {auto}" ) .col_vals_gt(columns="value", value=5) .col_vals_in_set(columns="category", set=["A", "B", "C"]) .interrogate() ) ``` Y5NjggMTMuODg0MjM1OSw4LjcxOTIzMDc0IEMxMy43ODIyNzA0LDguNzM2NjM5NjcgMTMuNjg3NzY1NCw4Ljc3NjQzMTE1IDEzLjYwNTY5NTYsOC44Mzg2MDUxOCBMMTAuMjQzMzE1NiwxMS4zODUyNTk4IEMxMC4wNzY2ODg2LDExLjUwNDYzNDMgOS45NzcyMDk5MywxMS42OTg2MTgxIDkuOTc3MjA5OTMsMTEuOTAyNTQ5MSBDOS45NzcyMDk5MywxMi4xMDY0ODA3IDEwLjA3NjY4ODYsMTIuMzAwNDYzOSAxMC4yNDMzMTU2LDEyLjQxOTgzODMgTDEzLjYwNTY5NTYsMTQuOTY2NDkzIEMxMy44OTE2OTcsMTUuMTgwMzcyNSAxNC4yOTcwNzI5LDE1LjEyMzE3MjEgMTQuNTEwOTUxNywxNC44MzcxNzA3IEMxNC43MjQ4MzEzLDE0LjU1MTE2OTIgMTQuNjY3NjMwOSwxNC4xNDU3OTQgMTQuMzgxNjI5NCwxMy45MzE5MTQ1IEwxMi41MzEzMjU3LDEyLjUzOTIxMjcgTDIxLjg4MTI0OTUsMTIuNTM5MjEyNyBMMjEuODgxMjQ5NSwxMS4yNjU4ODU0IEwxMi41MzEzMjU3LDExLjI2NTg4NTQgTDE0LjM4MTYyOTQsOS44NzMxODM2NCBDMTQuNjM3Nzg3Miw5LjcxNjUwNDUzIDE0Ljc0OTcwMDYsOS40MDA2NjAxNCAxNC42NDc3MzUxLDkuMTE3MTQ1NTMgQzE0LjU0ODI1NjQsOC44MzM2MzE1NiAxNC4yNjIyNTUsOC42NTk1NDM1MiAxMy45NjM4MTg5LDguNjk5MzM1IFoiIGlkPSJhcnJvdyIgZmlsbD0iIzAwMDAwMCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTUuOTI5MjMwLCAxMS44OTQ3MzcpIHJvdGF0ZSgtMTgwLjAwMDAwMCkgdHJhbnNsYXRlKC0xNS45MjkyMzAsIC0xMS44OTQ3MzcpICIgLz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg==" />
Pointblank Validation
2026-07-13|18:00:22 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

Step 1: Expect that values in value should be > 5.

 value 5 ✓ 5 5
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_in_set()

Step 2: Expect that values in category should be in the set of A, B, C.

 category A, B, C ✓ 5 5
1.00		 0
0.00		 -- -- -- --
In this example, every validation step will have a brief description that follows the pattern `"Step X: [auto-generated description]"`. This is a simple example of template-based briefs. Later in this guide, we'll explore the full range of templating elements available for creating custom brief descriptions that precisely communicate what each validation step is checking. # Step-level Briefs You can also set briefs for individual validation steps: ``` python ( pb.Validate(data=data) .col_vals_gt( columns="value", value=5, brief="Check if values exceed minimum threshold of 5" ) .col_vals_in_set( columns="category", set=["A", "B", "C"], brief="Verify categories are valid" ) .interrogate() ) ```
Pointblank Validation
2026-07-13|18:00:22 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

Check if values exceed minimum threshold of 5

 value 5 ✓ 5 5
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_in_set()

Verify categories are valid

 category A, B, C ✓ 5 5
1.00		 0
0.00		 -- -- -- --
Local briefs override any global briefs that might be set. # Brief Templating Briefs support templating elements that get replaced with specific values: - `{auto}`: an auto-generated description of the validation - `{step}`: the step number in the validation plan - `{col}`: the column name(s) being validated - `{value}`: the comparison value used in the validation (when applicable) - `{thresholds}`: a short summary of thresholds levels set (or unset) for the step - `{segment}`, `{segment_column}`, `{segment_value}`: information on the step's segment Here's how to use these templates: ``` python ( pb.Validate(data=data) .col_vals_gt( columns="value", value=5, brief="Step {step}: Checking column '{col}' for values `> 5`" ) .col_vals_in_set( columns="category", set=["A", "B", "C"], brief="{auto} **(Step {step})**" ) .interrogate() ) ```
Pointblank Validation
2026-07-13|18:00:22 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

Step 1: Checking column 'value' for values > 5

 value 5 ✓ 5 5
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_in_set()

Expect that values in category should be in the set of A, B, C. (Step 2)

 category A, B, C ✓ 5 5
1.00		 0
0.00		 -- -- -- --
These template elements make briefs highly flexible and customizable. You can combine multiple templating elements in a single brief to create descriptive yet concise validation step descriptions. The templates help maintain consistency across your validation reports while providing enough detail to understand what each step is checking. Note that not all templating elements will be relevant for every validation step. For instance, `{value}` is only applicable to validation functions that hold a comparison value like Validate.col_vals_gt(). If you include a templating element that isn't relevant to a particular step, it will not be replaced with a corresponding value. Briefs support the use of Markdown formatting, allowing you to add emphasis with **bold** or *italic* text, include `inline code` formatting, or other Markdown elements to make your briefs more visually distinctive and informative. This can be especially helpful when you want certain parts of your briefs to stand out in the validation report. # Automatic Briefs If you want Pointblank to generate briefs for you automatically, you can set `brief=True`. Here, we'll make that setting at the global level (by using `Validate(brief=True)`): ``` python ( pb.Validate( data=data, # Setting for automatically generated briefs --- brief=True ) .col_vals_gt(columns="value", value=5) .col_vals_in_set(columns="category", set=["A", "B", "C"]) .interrogate() ) ```
Pointblank Validation
2026-07-13|18:00:22 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

Expect that values in value should be > 5.

 value 5 ✓ 5 5
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_in_set()

Expect that values in category should be in the set of A, B, C.

 category A, B, C ✓ 5 5
1.00		 0
0.00		 -- -- -- --
Automatic briefs are descriptive and include information about what's being validated, including the column names and the validation conditions. # Briefs Localized to a Specified Language When using the `lang=` parameter in [Validate](../../reference/Validate.md#pointblank.Validate), automatically generated briefs will be created in the specified language (along with other elements of the validation report table): ``` python ( pb.Validate( data=data, # Setting the language as Spanish --- lang="es", # Automatically generate all briefs in Spanish brief=True ) .col_vals_gt(columns="value", value=5) .col_vals_in_set(columns="category", set=["A", "B", "C"]) .interrogate() ) ```
Validación de Pointblank
2026-07-13|18:00:22 Polars
PASO COLUMNAS VALORES TBL EVAL UNID. PASA FALLO W E C EXT
#4CA64C 1
col_vals_gt()

Se espera que los valores en value sean > 5.

 value 5 ✓ 5 5
1,00		 0
0,00		 -- -- -- --
#4CA64C 2
col_vals_in_set()

Se espera que los valores en category estén en el conjunto de A, B, C.

 category A, B, C ✓ 5 5
1,00		 0
0,00		 -- -- -- --
When using the `lang=` parameter in combination with the `{auto}` templating element, the auto-generated portion of the brief will also be translated to the specified language. This makes it possible to create fully localized validation reports where both custom text and auto-generated descriptions appear in the same language. Pointblank supports several languages for localized briefs, including French (`"fr"`), German (`"de"`), Spanish (`"es"`), Italian (`"it"`), and Portuguese (`"pt"`). For the complete list of supported languages, refer to the [Validate](../../reference/Validate.md#pointblank.Validate) documentation. # Disabling Briefs If you've set a global brief but want to disable it for specific validation steps, you can set `brief=False`: ``` python ( pb.Validate( data=data, # Global brief template --- brief="Step {step}: {auto}" ) .col_vals_gt(columns="value", value=5) # This step uses the global brief setting .col_vals_in_set( columns="category", set=["A", "B", "C"], # No brief for this step --- brief=False ) .interrogate() ) ```
Pointblank Validation
2026-07-13|18:00:22 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

Step 1: Expect that values in value should be > 5.

 value 5 ✓ 5 5
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_in_set()
category A, B, C ✓ 5 5
1.00		 0
0.00		 -- -- -- --
# Practical Example: Comprehensive Validation with Briefs In real-world data validation scenarios, you'll likely work with more complex datasets and apply various types of validation checks. This final example brings together many of the brief-generating techniques we've covered, showing how you can mix different approaches in a single validation workflow. ``` python # Create a slightly larger dataset data_2 = pl.DataFrame({ "id": [1, 2, 3, 4, 5, 6, 7, 8], "value": [10, 20, 30, 40, 50, 60, 70, 80], "ratio": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], "category": ["A", "B", "C", "A", "B", "C", "A", "B"], "date": ["2023-01-01", "2023-01-02", "2023-01-03", "2023-01-04", "2023-01-05", "2023-01-06", "2023-01-07", "2023-01-08"] }) ( pb.Validate(data=data_2) .col_vals_gt( columns="value", value=0, # Plaintext brief --- brief="All values must be positive." ) .col_vals_between( columns="ratio", left=0, right=1, # Template-based brief --- brief="**Step {step}**: Ratios should be between `0` and `1`." ) .col_vals_in_set( columns="category", set=["A", "B", "C"], # Automatically generated brief --- brief=True ) .interrogate() ) ```
Pointblank Validation
2026-07-13|18:00:23 Polars
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()

All values must be positive.

 value 0 ✓ 8 8
1.00		 0
0.00		 -- -- -- --
#4CA64C 2
col_vals_between()

Step 2: Ratios should be between 0 and 1.

 ratio [0, 1] ✓ 8 8
1.00		 0
0.00		 -- -- -- --
#4CA64C 3
col_vals_in_set()

Expect that values in category should be in the set of A, B, C.

 category A, B, C ✓ 8 8
1.00		 0
0.00		 -- -- -- --
The example above demonstrates: - plaintext briefs with direct messages - template-based briefs with Markdown formatting - automatically generated briefs (`brief=True`) By combining these different brief styles, you can create validation reports that are informative, consistent, and tailored to your specific data quality requirements. # Best Practices for Using Briefs Well-crafted briefs can significantly enhance the readability and usefulness of your validation reports. Here are some guidelines to follow: 1. Be concise: briefs should be short and to the point; they're meant to quickly communicate the purpose of a validation step 2. Be specific: include relevant details or conditions that make the validation meaningful 3. Use templates consistently: if you're using template elements like `"{step}"` or `"{col}"`, try to use them consistently across all briefs for a cleaner look 4. Use auto-generated briefs as a starting point: you can start with `Validate(brief=True)` to see what Pointblank generates automatically, then customize as needed 5. Add custom briefs for complex validations: custom briefs are especially useful for complex validations where the purpose might not be immediately obvious from the code Following these best practices will help ensure your validation reports are easy to understand for everyone who needs to review them. # Conclusion Briefs help make validation reports more readable and understandable. By using global briefs, step-level briefs, or a combination of both, you can create validation reports that clearly communicate what each validation step is checking. Whether you want automatically generated descriptions or precisely tailored custom messages, the brief system provides the flexibility to make your data validation work more transparent and easier to interpret for all stakeholders.