Basic Validator¶

The Basic validator is the simplest and most flexible validator in the library. It doesn't carry a schema, a simulator, or any built-in domain knowledge — it just gives you a place to write your own rules as CEL expressions and runs them against the submitted file.

It's the right choice when you have a structured file (typically JSON or YAML) and a set of acceptance rules that don't fit cleanly into a JSON Schema. Think: "every line item must have a non-negative price and the discounted total must not exceed the original", or "if mode is production then endpoint must start with https://".

What you'll need¶

• A Validibot account with permission to author workflows.
• A workflow whose allowed file types include the format you want to check (typically JSON or YAML — see "File types" below).
• A clear, written list of rules you want to enforce.

Setting up a Basic step¶

1. Open the workflow editor and click Add step.
2. Pick Basic from the validator library.
3. Give the step a name like "Order acceptance rules" and a short description.
4. Click Save step.
5. Open the saved step and click Add assertion for each rule you want to enforce. Each assertion gets:
6. A short label (shown on findings — make it readable).
7. A CEL expression that must evaluate to true for the rule to pass.
8. An error message shown to the submitter when it fails.
9. A severity (error, warning, info).

The assertion editor's autocomplete shows which namespaces you can reference — for a Basic step, that's p.* (the payload) and s.* (any workflow signals). Basic doesn't run a process, so i.* and o.* are empty.

Common patterns¶

A few rule shapes that come up often:

# Required field with a sensible value
p.order_id != null && size(p.order_id) > 0

# Cross-field numeric check
p.discount <= p.subtotal * 0.5

# Conditional rule — production must use HTTPS
p.mode != "production" || p.endpoint.startsWith("https://")

# All items in an array must satisfy a check
p.line_items.all(item, item.price >= 0 && item.quantity > 0)

# Compare against a workflow-wide signal
p.total <= s.contract_ceiling

The CEL Expressions page is the reference for the full operator and helper list, including the Validibot-specific helpers (has, percentile, mean, duration, …).

When to choose Basic vs. JSON Schema¶

The Basic validator and the JSON Schema validator are complementary, not competing.

• JSON Schema is best at structural checks — does this field exist, does it have the right type, does it match a regex, is it one of an allowed enum, is the array the right length.
• Basic + CEL is best at behavioural and cross-field checks — comparing two fields to each other, conditional requirements, numeric tolerances, length-of-array-times-cost-per-item-must-not-exceed rules.

A common pattern is to use both in the same workflow: a JSON Schema step first to enforce structure, then a Basic step (or step-level assertions on the schema step itself) for the cross-field and behavioural rules.

File types¶

Basic works against any text-extractable, structured file Validibot can parse into a tree. In practice that means JSON and YAML; the workflow's allowed file types control which formats the validator will let you attach it to.

Tips¶

• Label your assertions well. The label appears as the heading on any finding the rule produces — "Discount cannot exceed 50%" reads better in a report than "discount_check".
• Use signals for thresholds you reuse. If three different assertions all reference the same number, promote it to a workflow signal (s.contract_ceiling) and reference it from each — then changing the threshold is one edit.
• Pick the right severity. A warning is a great way to surface "this looks suspicious but isn't actually disallowed" without failing the whole submission.
• Test against a sample submission. The Basic validator's feedback loop is tight — paste a representative JSON into the run page and iterate on the assertions until they fail and pass for the right reasons.