Validators Overview¶
A validator is the engine behind a workflow step. It takes the submitted data, runs a specific kind of check, and produces a pass / fail result plus any findings — the specific things that went wrong, with locations and severity.
Validibot ships with two families of validators: built-in validators that run in-process and are available to every edition, and advanced validators that run in isolated containers and are unlocked by the Pro and Enterprise editions.
Built-in validators¶
These run inside the Validibot web app itself. They're fast, deterministic, and good enough for the majority of structural and rule-based checks.
| Validator | What it checks | File types | Page |
|---|---|---|---|
| Basic | Your own pass/fail rules expressed in CEL | JSON, YAML, any text | Basic Validator |
| JSON Schema | A JSON file against a JSON Schema you upload or paste | JSON | JSON Schema Validator |
| XML Schema | An XML file against an XSD you upload | XML | XML Schema Validator |
| Tabular | A CSV against a Frictionless Table Schema, plus cross-field row rules | CSV | Tabular Validator |
| SHACL | An RDF graph against SHACL shapes (e.g. ASHRAE 223P) | Turtle, JSON-LD, RDF/XML | SHACL Validator |
| AI | Natural-language acceptance criteria, evaluated by an LLM | Any text-extractable file | AI Validator |
Advanced validators (Pro / Enterprise)¶
These dispatch the submission to a dedicated container, run a heavier process (a simulation, a compute-bound parse), and return structured outputs you can write rules against. They unlock when your deployment is licensed for Pro or Enterprise.
| Validator | What it does | File types | Page |
|---|---|---|---|
| EnergyPlus™ | Runs a building energy simulation and exposes EUI, end-use, unmet hours, and envelope metrics | IDF, epJSON | EnergyPlus Validator |
| FMU | Runs a Functional Mock-up Unit co-simulation and exposes its output variables | FMU package + driver JSON/YAML | FMU Validator |
You can also build your own advanced validator by packaging a check as a Docker container and registering it — see Self-Hosted Editions for the deployment side and the developer docs for the SDK.
How a validator decides pass or fail¶
Every validator runs two kinds of rule on your data:
Default assertions are built into the validator. They always run. For a JSON Schema validator, the default assertion is the schema match. For Basic, there are no defaults — you write everything.
Step assertions are the rules you add on a specific step. You
write these as CEL expressions against
the data namespaces (p.*, s.*,
i.*, o.*). Step assertions are how you tighten a generic validator
for your domain — for example, "this JSON Schema must match and
p.price > 0 and s.target_eui <= 60."
A step fails if any default assertion or step assertion fails. Whether the workflow fails depends on its mode (any-failure-stops vs. collect-all-findings) — see Running Validations.
Choosing the right validator¶
The fastest way to pick:
- Is the file JSON or YAML and you have a JSON Schema for it? → JSON Schema validator. Add a Basic step after it for any extra cross-field rules.
- Is it XML with an XSD? → XML Schema validator. Same Basic follow-up if you need cross-field checks.
- Is it a CSV? → Tabular validator. Column types, ranges, regex, uniqueness, and cross-column row rules in one place.
- Is it an RDF graph (Turtle, JSON-LD)? → SHACL validator.
- Is it an EnergyPlus model and you want energy / unmet-hours checks? → EnergyPlus validator (Pro).
- Is it an FMU simulation package? → FMU validator (Pro).
- No formal schema, just plain rules you want to express? → Basic validator with CEL.
- The acceptance criteria are subjective (e.g. "does this README cover installation and licensing?") → AI validator.
You can chain multiple validators in one workflow — start strict (schema), then add semantic checks (Basic / CEL), then run a simulation (EnergyPlus / FMU) if you need behavioural validation. Earlier steps typically gate later, more expensive ones.
File-type compatibility¶
When you add a step to a workflow, the validator picker disables any validator that doesn't match the workflow's allowed file types. If you find the validator you want greyed out, open the workflow settings and add the file type, then come back.
Where to next¶
- Data Namespaces — what
p.*,s.*,i.*,o.*mean across all validators. - CEL Expressions — the language used for step assertions and Tabular row rules.
- Workflow Management — how to wire steps together into a workflow.