Portable validation rules, defined as data.
OpenVDL (Open Validation Description Language) is a draft open specification for expressing data validation rules as portable, versioned documents. The goal is to let applications in different languages share the same definition of what makes a value valid.
Read the specification · Explore examples · View the roadmap · Contribute
Early-stage project: the specification is a v0.1 draft, and the reference runtime is a scaffold. Examples illustrate the proposed format; support across independent engines still needs to be built and tested.
An email address, IBAN, or VAT number often gets checked in several services, each with its own copy of the rules. Those copies drift as formats and policies change, making it difficult to explain why the same value passes in one place and fails in another.
OpenVDL proposes keeping the definition in a document that teams can read, review, and version together:
- Define once: describe inputs, normalization steps, and named validation rules.
- Reuse and compose: extend base validators and combine them into larger flows.
- Keep the context: record the facts and sources behind a rule as it evolves.
- Share across languages: give engines a common definition to interpret.
The specification covers the representation and evaluation of validators. Consistent behavior across implementations is a design goal that requires precise semantics and shared conformance tests.
Suppose an internal service accepts email addresses only at acme.com. This
excerpt from the email extension example declares
the base validator and adds the domain policy:
openvdl: "0.1"
id: "acme/email"
version: "1.0.0"
extends:
- "openvdl/email@1"
stages:
- id: acme-policy
rules:
- id: acme-domain-only
type: domainEquals
value: acme.comThe shared email rules and the local policy have separate definitions, with an explicit dependency between them. The full example adds a local-part length constraint and declares the input and result model.
Explore IBAN checks,
alternative identifiers with anyOf, or
VAT routing by country.
| Principle | What it means |
|---|---|
| Declarative and readable | Rules are documents that people can inspect and engines can interpret. |
| Portable | Definitions are independent of application languages and frameworks. |
| Composable | Shared validators can be extended, referenced, and combined. |
| Versioned | Changes to definitions and their dependencies can be tracked explicitly. |
| Deterministic | Compliant engines should agree for the same input, definition, and enabled capabilities. |
The intended scope includes email, URLs, domains, IP addresses, UUIDs, IBANs, BICs, ISBNs, payment card numbers, national and business identifiers, VAT numbers, phone numbers, postal codes, vehicle identifiers, and product codes. Provider and organization policies can layer additional constraints on top.
OpenVDL should be treated as a reusable validator ecosystem, not just a file format for isolated rules.
The core ideas are:
- a validator can extend another validator instead of duplicating it
- a validator can import and reference other validators as reusable modules
- a validator can be composed with
allOf,anyOf,oneOf,not, and conditional logic such asif/then/elseormatch/cases - a root OpenVDL document can act as an entry point that aggregates other validators
- provider and organization policy should layer on top of base validators
- validation may involve both local rules and provider-backed truth-source checks
- OpenVDL should be able to describe the request/response contract of external validation providers
- OpenVDL documents should be able to embed world facts that justify validator evolution
Typical examples:
- extend a standard email validator with company-only domain constraints
- apply Gmail-specific policy only when the domain is
gmail.com - aggregate email, phone, and internal employee ID validators into a single user identifier validator
- adapt a third-party validation API into a standard OpenVDL validation flow
- maintain a curated validator catalog whose changes are traceable to real-world facts encoded in the validator semantics
The draft organizes a validator into stages, such as syntax checks, provider policy, and organization constraints. Evaluation produces one of three results:
| Result | Meaning |
|---|---|
VALID |
All applicable constraints passed. |
INVALID |
A validation rule failed. |
ERROR |
Evaluation could not complete, for example because a required reference could not be resolved. |
Structured diagnostics can identify the rule, location, and expected condition behind a result.
OpenVDL should support a small set of first-class primitives for reuse and orchestration:
extends: inherit a base validator and add constraintsimports: declare reusable validator dependenciesref: reference an imported validatorallOf,anyOf,oneOf,not: compose validators and rulesif/then/else: enable conditional validation flowsmatch/cases: support structured multi-branch validator selection
This allows an OpenVDL file to behave like the root of a validator codebase rather than a single flat rule list.
OpenVDL should not stop at local validation rules.
Some validations depend on external truth sources, such as:
- government registries
- tax databases
- banking systems
- business registries
- domain infrastructure
- trusted validation providers
For those cases, OpenVDL should describe:
- the request shape sent to a validation provider
- the response shape returned by that provider
- how provider responses map back into OpenVDL result semantics
- how third-party APIs can be adapted into a standard OpenVDL validation model
One open architectural question is whether providers should implement OpenVDL natively, or whether OpenVDL should define an adapter layer that formalizes how arbitrary provider APIs are integrated.
OpenVDL should treat facts about the world as part of validator semantics, not as side documentation.
If a validator depends on a discovered real-world constraint, that fact should be representable inside the OpenVDL document itself, with fields such as:
- subject
- statement
- impact on validation
- provenance
- confidence
- effective date or revision window
Separate notes may still exist as supporting material, but they should not be the primary semantic source. The validator document must carry the essential fact model so implementations and maintainers do not lose critical context.
OpenVDL should also preserve the discovery process behind maintained validator changes.
Modern LLM and agentic tools make it possible to run iterative explorations over world facts that may later affect validation semantics. Those explorations should be logged as research rounds, hypotheses, and findings.
That diary is useful for:
- preserving how a fact was discovered
- retaining failed or partial hypotheses
- linking validator changes back to exploration rounds
- supporting future re-evaluation when the world changes again
The intended split is:
- OpenVDL validator documents contain the canonical semantic facts
- the exploration diary records how those facts were discovered and promoted
This repository currently contains a draft specification intended for discussion and experimentation. It is not yet a final standard.
The specification is written as an RFC-style draft (RFC-OpenVDL.txt). It has not been submitted to the IETF yet; the intention is to submit it as an individual Internet-Draft.
Contributions are welcome: see CONTRIBUTING.md.
Current work is tracked in ROADMAP.md.
An early runtime scaffold is available in libopenvdl/.
A curated maintained validator library scaffold is available in validators/, with validators/openvdl.yml as its current entry point.
An exploration diary scaffold is available in explorations/, with explorations/index.md as its current index.
| Start here | What you will find |
|---|---|
| Specification overview | Core concepts and the proposed data model. |
| RFC-style draft | The formal draft, not yet submitted to the IETF. |
| Composition model | Extension, references, and validator aggregation. |
| Provider integration | External sources and API adaptation. |
| Examples | Email, IBAN, extension, composition, and country dispatch. |
| Validator library | The initial catalog and its openvdl.yml entry point. |
| Reference runtime | The early C implementation scaffold. |
| Exploration diary | Research rounds behind proposed facts and rules. |
| Roadmap | Open questions and planned work. |
Pick a format you know well and try describing its rules. Useful contributions include validator definitions, authoritative sources, test vectors, feedback on ambiguous semantics, and independent engines.
Read CONTRIBUTING.md or open an issue to start a discussion.
Declarative validation is not a new idea: LIVR, JSON Schema, CEL/Protovalidate, libphonenumber and python-stdnum all move parts of validation out of application code. OpenVDL focuses on the layer they leave open: a shared, versioned definition of what "valid" means for real-world identifiers, where that knowledge comes from, and when it changed. See docs/related-work.md for the survey and the alignment direction (CEL, JSON Schema bridge, generation from authoritative data, conformance suite).
OpenVDL uses two licenses:
- Code and validator documents, under Apache License 2.0:
- Specification and documentation, under Creative Commons Attribution 4.0 International (CC BY 4.0):
- RFC-OpenVDL.txt
- docs/
- explorations/
- this README and the other Markdown documents in the repository root
Copyright 2026 The OpenVDL Authors.