# Serializing Validation Plans A validation plan you build in Python isn't locked inside the [Validate](../../reference/Validate.md#pointblank.Validate) object. Pointblank can render an in-memory plan back into canonical source, either as a Python method chain, a YAML configuration, or a language-neutral JSON Schema document. This is the inverse of writing a plan by hand: you hand it a [Validate](../../reference/Validate.md#pointblank.Validate) object and it gives you a portable representation. Three methods do this: - Validate.to_code() produces the `pb.Validate(...).col_vals_*()...` chain as a string - Validate.to_yaml() produces a yaml_interrogate()-compatible YAML document - Validate.to_json_schema() produces a [JSON Schema](https://json-schema.org/) document The first two are ordinary, deterministic utilities that round-trip through Pointblank itself. [to_json_schema()](../../reference/Validate.to_json_schema.md#pointblank.Validate.to_json_schema) produces a standard that tools in many ecosystems can consume. All three are useful for sharing plans, reviewing changes in a diff, and persisting a plan alongside its results. [to_code()](../../reference/Validate.to_code.md#pointblank.Validate.to_code) and [to_yaml()](../../reference/Contract.md#pointblank.Contract.to_yaml) are also the foundation for the [AI Validation Editor](../../user-guide/advanced-validation/ai-validation-editor.md), which sends the current plan to a model as editable code. # Rendering a Plan as Python Code Given any validation plan, to_code() returns a self-contained block of Python that reproduces it: ``` python import pointblank as pb validation = ( pb.Validate( data=pb.load_dataset("small_table"), tbl_name="small_table", label="Small table checks", thresholds=pb.Thresholds(warning=0.1, error=0.25), ) .col_vals_gt(columns="d", value=100) .col_vals_not_null(columns="a") .col_vals_not_null(columns="b") .col_vals_in_set(columns="f", set=["low", "mid", "high"]) .rows_distinct() .row_count_match(count=13) ) print(validation.to_code()) ``` import pointblank as pb validation = ( pb.Validate( data=your_data, # Replace your_data with the actual data variable tbl_name="small_table", label="Small table checks", thresholds=pb.Thresholds(warning=0.1, error=0.25), ) .col_vals_gt(columns="d", value=100) .col_vals_not_null(columns=["a", "b"]) .col_vals_in_set(columns="f", set=["low", "mid", "high"]) .rows_distinct() .row_count_match(count=13) ) validation A few things to notice in the output: - The table-level configuration (`tbl_name`, `label`, `thresholds`) is reproduced on the `pb.Validate(...)` call. - The data source is rendered as the placeholder `your_data`, since the plan doesn't know the name of the variable your data lives in. Replace it with your actual data variable before running the code. - Adjacent steps that differ only by column are collapsed into a single call: the two [col_vals_not_null()](../../reference/Validate.col_vals_not_null.md#pointblank.Validate.col_vals_not_null) steps above become `col_vals_not_null(columns=["a", "b"])`. This keeps the output compact and diffs minimal. - Only non-default arguments are emitted. A step-level threshold that matches the table-level default is omitted, `na_pass=True` appears only where it was set, and so on. The result is regular source you can paste into a script or notebook, commit to version control, or share with a colleague. # Rendering a Plan as YAML to_yaml() renders the same plan using the schema consumed by yaml_interrogate(): ``` python print(validation.to_yaml()) ``` tbl: small_table tbl_name: small_table label: Small table checks thresholds: warning: 0.1 error: 0.25 steps: - col_vals_gt: columns: d value: 100 - col_vals_not_null: columns: - a - b - col_vals_in_set: columns: f set: - low - mid - high - rows_distinct - row_count_match: count: 13 The `tbl` field is set from `tbl_name` when available, otherwise to the placeholder `your_data`. Set it to a loadable data source (a dataset name, file path, or Python expression) before handing the YAML to [yaml_interrogate()](../../reference/yaml_interrogate.md#pointblank.yaml_interrogate). See the [YAML Validation Workflows](../../user-guide/yaml/yaml-validation-workflows.md) page for the full YAML schema. You can also write the YAML directly to a file by passing `path=`: ``` python validation.to_yaml(path="plans/small_table.yaml") ``` # Round-Tripping a Plan Because [to_yaml()](../../reference/Contract.md#pointblank.Contract.to_yaml) emits a [yaml_interrogate()](../../reference/yaml_interrogate.md#pointblank.yaml_interrogate)-compatible document, a plan round-trips through YAML. Here we serialize a plan, then rebuild and run it with [yaml_interrogate()](../../reference/yaml_interrogate.md#pointblank.yaml_interrogate): ``` python yaml_str = validation.to_yaml() rebuilt = pb.yaml_interrogate(yaml_str) rebuilt ```
Pointblank Validation
Small table checks Polarssmall_tableWARNING0.1ERROR0.25CRITICAL--
STEP COLUMNS VALUES TBL EVAL UNITS PASS FAIL W E C EXT
#4CA64C 1
col_vals_gt()
d 100 ✓ 13 13
1.00		 0
0.00		 ○ ○ -- --
#4CA64C 2
col_vals_not_null()
a -- ✓ 13 13
1.00		 0
0.00		 ○ ○ -- --
#4CA64C 3
col_vals_not_null()
b -- ✓ 13 13
1.00		 0
0.00		 ○ ○ -- --
#4CA64C 4
col_vals_in_set()
f low, mid, high ✓ 13 13
1.00		 0
0.00		 ○ ○ -- --
#AAAAAA 5
rows_distinct()
ALL COLUMNS -- ✓ 13 11
0.85		 2
0.15		 ● ○ -- CSV
#4CA64C 6
LDY5LjQ4NTMzMDYgTDMyLjI2NDUyODYsNjkuNDg1MzMwNiBMMzIuMjY0NTI4NiwyOC40ODUzMzA2IEwzNS4xNTk5MzkzLDI4LjQ4NTMzMDYgWiBNNDAuMzU5MzQ3NSwyOC40ODU3NTA3IEM0MC40NzMzOTUzLDI4LjQ4ODcyOCA0MC43NjY4MiwyOC41MDQ4MTQ2IDQwLjk4NTM1NTIsMjguNjk0OTQ1MSBDNDEuMTAwODIxNSwyOC43OTU0MDM0IDQxLjE4MTk5OTksMjguOTUxMzY4NCA0MS4yMDUxNzc2LDI5LjE3NDgzMiBMNDEuMjA1MTc3NiwyOS4xNzQ4MzIgTDQxLjIxMjIzNCw2OC42NTE5OTczIEM0MS4yMTIyMzQsNjguOTMwOTgzMyA0MS4xMzg1Mjc3LDY5LjEyNTgzNjkgNDEuMDEzMjgwMyw2OS4yNDk4MDk0IEM0MC43OTQzMDc0LDY5LjQ2NjU1MzUgNDAuNDc4MDQ3LDY5LjQ4MTg3ODcgNDAuMzU5NDEzOSw2OS40ODQ5MTA2IEw0MC4zNTk0MTM5LDY5LjQ4NDkxMDYgTDM4LjI1OTg1Myw2OS40ODUyNDk4IEwzOC4yNTk4NTMsMjguNDg1NDExNCBaIiBpZD0icm93c190d28iIHN0cm9rZT0iIzAwMDAwMCIgZmlsbC1ydWxlPSJub256ZXJvIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzMy43MTIyMzQsIDQ4Ljk4NTMzMSkgcm90YXRlKC05MC4wMDAwMDApIHRyYW5zbGF0ZSgtMzMuNzEyMjM0LCAtNDguOTg1MzMxKSAiIC8+CiAgICAgICAgICAgIDxnIGlkPSJ2ZXJ0aWNhbF9lcXVhbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMzAuMDAwMDAwLCAyOS4zODA1NzApIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS1saW5lY2FwPSJzcXVhcmUiPgogICAgICAgICAgICAgICAgPGxpbmUgeDE9IjIuMjEyMjMzOTciIHkxPSIwLjUxNDY2OTM1MyIgeDI9IjIuMjEyMjMzOTciIHkyPSI3LjU4NTczNzE2IiBpZD0iTGluZSI+PC9saW5lPgogICAgICAgICAgICAgICAgPGxpbmUgeDE9IjUuMjEyMjMzOTciIHkxPSIwLjUxNDY2OTM1MyIgeDI9IjUuMjEyMjMzOTciIHkyPSI3LjU4NTczNzE2IiBpZD0iTGluZSI+PC9saW5lPgogICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDxwYXRoIGQ9Ik0yNy4wOTMxODYzLC0yLjk4NTMzMDY1IEMyNi44ODM2NjI1LC0yLjk4NTMzMDY1IDI1LjcxMjIzNCwtMi45MzUzMzA2NSAyNS43MTIyMzQsLTEuNjUxOTk3MzEgTDI1LjcxMjIzNCwzNy42ODEzMzYgQzI1LjcxMjIzNCwzOC45NjQ2Njk0IDI2Ljg4MzY2MjUsMzkuMDE0NjY5NCAyNy4wOTMxODYzLDM5LjAxNDY2OTQgTDI5LjY2NDYxNDksMzkuMDE0NjY5NCBMMjkuNjY0NjE0OSwtMi45ODUzMzA2NSBMMjcuMDkzMTg2MywtMi45ODUzMzA2NSBaIE0zNS42NzIxNzcxLC0yLjk4NTMzMDY1IEwzNS42NzIxNzcxLDM5LjAxNDY2OTQgTDMxLjc1MjI5MDgsMzkuMDE0NjY5NCBMMzEuNzUyMjkwOCwzOS4wMTQ2Njk0IEwzMS43NTIyOTA4LC0yLjk4NTMzMDY1IEwzMS43NTIyOTA4LC0yLjk4NTMzMDY1IEwzNS42NzIxNzcxLC0yLjk4NTMzMDY1IFogTTQwLjM2NTYxNDksLTIuOTg0OTA5NiBDNDAuNjQ0ODc4NiwtMi45NzgyMzY5OCA0MS43MTIyMzQsLTIuODc2OTk3MzEgNDEuNzEyMjM0LC0xLjY1MTk5NzMxIEw0MS43MTIyMzQsLTEuNjUxOTk3MzEgTDQxLjcxMjIzNCwzNy42ODEzMzYgQzQxLjcxMjIzNCwzOC45NjQ2Njk0IDQwLjU0MDgwNTQsMzkuMDE0NjY5NCA0MC4zMzEyODE2LDM5LjAxNDY2OTQgTDQwLjMzMTI4MTYsMzkuMDE0NjY5NCBMMzcuNzU5ODUzLDM5LjAxNDY2OTQgTDM3Ljc1OTg1MywtMi45ODUzMzA2NSBaIiBpZD0icm93c19vbmUiIGZpbGw9IiMwMDAwMDAiIGZpbGwtcnVsZT0ibm9uemVybyIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMzMuNzEyMjM0LCAxOC4wMTQ2NjkpIHJvdGF0ZSgtOTAuMDAwMDAwKSB0cmFuc2xhdGUoLTMzLjcxMjIzNCwgLTE4LjAxNDY2OSkgIiAvPgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+" /> row_count_match()
-- 13 ✓ 1 1
1.00		 0
0.00		 ○ ○ -- --
2026-08-13 17:32:30 UTC< 1 s2026-08-13 17:32:30 UTC
The rebuilt plan carries the same steps as the original. The Python code from [to_code()](../../reference/Validate.to_code.md#pointblank.Validate.to_code) round-trips in the same way: executing it (after replacing `your_data`) reconstructs an equivalent plan. # Fidelity and Limitations Most validation steps round-trip exactly. The exceptions are steps that carry live Python objects that can't be reconstructed from source: - `pre=` preprocessing callables - step-level `actions=` - callable `active=` conditions - the expressions used by col_vals_expr(), conjointly(), and specially() For these, Pointblank emits a clearly-marked placeholder so the generated code still parses and runs, and raises a warning describing what was lost. The following plan uses a `pre=` callable that can't be serialized: ``` python import warnings flagged = pb.Validate(data=pb.load_dataset("small_table")).col_vals_gt( columns="d", value=100, pre=lambda df: df ) with warnings.catch_warnings(record=True) as caught: warnings.simplefilter("always") code = flagged.to_code() for w in caught: print("warning:", w.message) ``` warning: Some parts of the validation plan could not be fully serialized to code: - Step 'col_vals_gt' has a `pre=` preprocessing callable that cannot be serialized; it was dropped from the generated plan. When you see such a warning, review the generated plan and restore the affected step by hand. Plans built entirely from literal arguments (values, ranges, sets, patterns, counts, schemas) serialize without any loss. # When to Use Serialization Rendering a plan back to source is helpful whenever you want the plan to leave the current Python session: - **Sharing.** Send a colleague the exact plan as code or YAML rather than describing it. - **Code review.** Serialize a plan before and after a change and diff the two to see precisely what moved. You can produce this comparison directly with EditValidation.from_plans() (no LLM required), which is also how the [AI Validation Editor](../../user-guide/advanced-validation/ai-validation-editor.md) presents proposed edits. - **Persistence.** Store the *plan* (not just the results) alongside a validation run, so you have a durable, human-readable record of what was checked. - **Migrating between formats.** Move a plan from Python to YAML (or, via yaml_to_python(), from YAML to Python) to fit it into a configuration-driven workflow. # Exporting a Plan as JSON Schema While [to_code()](../../reference/Validate.to_code.md#pointblank.Validate.to_code) and [to_yaml()](../../reference/Contract.md#pointblank.Contract.to_yaml) reproduce your plan as Pointblank-specific source, to_json_schema() converts your validation rules into a [JSON Schema](https://json-schema.org/) document. JSON Schema is a widely adopted, language-neutral standard, so the exported schema can be consumed by validation libraries in JavaScript, Java, Go, and many other ecosystems. ``` python import json validation = ( pb.Validate( data=pb.load_dataset("small_table"), tbl_name="small_table", ) .col_vals_gt(columns="d", value=100) .col_vals_not_null(columns="date_time") .col_vals_in_set(columns="f", set=["low", "mid", "high"]) .col_vals_regex(columns="b", pattern="^[0-9]-[a-z]{3}-[0-9]{3}$") .col_vals_between(columns="a", left=1, right=8) ) schema = validation.to_json_schema() print(json.dumps(schema, indent=2)) ``` { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "d": { "exclusiveMinimum": 100, "type": "number" }, "date_time": {}, "f": { "enum": [ "low", "mid", "high" ], "type": "string" }, "b": { "pattern": "^[0-9]-[a-z]{3}-[0-9]{3}$", "type": "string" }, "a": { "minimum": 1, "maximum": 8, "type": "integer" } }, "required": [ "date_time" ] } Each validation method is mapped to its closest JSON Schema keyword: | Pointblank method | JSON Schema keyword | |----|----| | [col_vals_not_null()](../../reference/Validate.col_vals_not_null.md#pointblank.Validate.col_vals_not_null) | `required` | | [col_vals_gt()](../../reference/Validate.col_vals_gt.md#pointblank.Validate.col_vals_gt) | `exclusiveMinimum` | | [col_vals_ge()](../../reference/Validate.col_vals_ge.md#pointblank.Validate.col_vals_ge) | `minimum` | | [col_vals_lt()](../../reference/Validate.col_vals_lt.md#pointblank.Validate.col_vals_lt) | `exclusiveMaximum` | | [col_vals_le()](../../reference/Validate.col_vals_le.md#pointblank.Validate.col_vals_le) | `maximum` | | [col_vals_eq()](../../reference/Validate.col_vals_eq.md#pointblank.Validate.col_vals_eq) | `const` | | [col_vals_between()](../../reference/Validate.col_vals_between.md#pointblank.Validate.col_vals_between) | `minimum` + `maximum` | | [col_vals_in_set()](../../reference/Validate.col_vals_in_set.md#pointblank.Validate.col_vals_in_set) | `enum` | | [col_vals_regex()](../../reference/Validate.col_vals_regex.md#pointblank.Validate.col_vals_regex) | `pattern` | | [col_vals_within_spec()](../../reference/Validate.col_vals_within_spec.md#pointblank.Validate.col_vals_within_spec) | `format` | When the [Validate](../../reference/Validate.md#pointblank.Validate) object has data attached, the schema is automatically enriched with column type information (`"type": "integer"`, `"type": "string"`, etc.) inferred from the data. Steps that have no natural JSON Schema equivalent (e.g., [rows_distinct()](../../reference/Validate.rows_distinct.md#pointblank.Validate.rows_distinct), [tbl_match()](../../reference/Validate.tbl_match.md#pointblank.Validate.tbl_match)) are silently skipped. ## Writing to a File Pass a `path=` argument to write the JSON Schema to disk. Parent directories are created automatically: ``` python validation.to_json_schema(path="schemas/small_table.schema.json") ``` This is useful for checking schemas into version control or feeding them into downstream tooling that consumes JSON Schema files. ## Relationship to [export_contract()](../../reference/export_contract.md#pointblank.export_contract) Under the hood, [to_json_schema()](../../reference/Validate.to_json_schema.md#pointblank.Validate.to_json_schema) delegates to the export_contract() function with `format="json_schema"`. The convenience method adds type enrichment from the data and handles file output. If you need the raw adapter behavior (for example, to export without type enrichment, or to work with a [Contract](../../reference/Contract.md#pointblank.Contract) object rather than a [Validate](../../reference/Validate.md#pointblank.Validate) object), use [export_contract()](../../reference/export_contract.md#pointblank.export_contract) directly. See the [Importing and Exporting Contracts](../../user-guide/contracts-and-pipelines/importing-contracts.md) guide for the full story on contract adapters. # Conclusion to_code(), to_yaml(), and to_json_schema() turn a live validation plan back into portable source. The first two are deterministic, Pointblank-specific formats that round-trip through execution and yaml_interrogate() respectively. The third produces a language-neutral JSON Schema that any JSON-Schema-aware tool can consume. Beyond sharing and persistence, these representations provide the reviewable, diffable record that powers the [AI Validation Editor](../../user-guide/advanced-validation/ai-validation-editor.md) covered in the next section.