Skip to main content
GOBL validates every document automatically as part of the build process. These validation rules check that documents have the right fields, follow the expected formats, and satisfy whatever constraints the relevant schema, tax regime and addons define.

​
How it works

When you build a GOBL document, it’s processed through a validation rules engine that checks each struct in a document against a set of assertions. Every assertion has three parts:
  • A unique validation code that identifies the rule.
  • One or more tests that evaluate to true or false.
  • A human-readable message that surfaces when a test fails.
When GOBL processes a document, it runs all applicable rules and collects any failures into a structured error response, including the field path, validation code, and message for each failure.

​
Three layers of rules

Rules are organized into three layers, applied in order:

​
Core rules

Core rules apply to every GOBL document, regardless of country or configuration. They enforce the basic structure each document type requires. An invoice, for example, always needs a type, issue_date, currency, and supplier. Core rules live alongside the structs they validate in the GOBL source, and are listed under the Validation Rules section on each schema’s reference page.

​
Regime rules

Tax regimes add country-specific requirements on top of core rules. When a document specifies a regime — Portugal, Mexico, France, and so on — that regime’s rules are also evaluated. A Portuguese rule might require invoices to include a specific extension, or that the series code follows a particular format. These rules only kick in when the document’s regime is set to Portugal.

​
Addon rules

Addons layer further validation on top of regime rules. When a document has an addon enabled such as Mexico CFDI or Peppol’s EU EN 16931, its rules are checked as well. Addon rules typically enforce the requirements of a specific standard or reporting system. The Mexico CFDI addon, for instance, requires certain tax extensions and customer fields depending on whether the invoice is global or domestic.

​
Validation codes

Every assertion gets a unique code built from the package, struct, and a sequence number: These codes show up in error responses and can be used to programmatically identify and handle specific validation failures.

​
Error collection

Validation never stops at the first failure. The engine runs every applicable rule across all three layers — and collects every fault it finds. The full list of errors is returned together in a single response, so you can see and fix all problems at once rather than going through them one at a time.

​
Calculated fields

Some fields are marked as calculated in the validation tables. These fields are automatically populated by GOBL during the build step, before validation runs. For example, an invoice’s totals are computed from the line items, taxes, and discounts — you never need to provide them yourself. A validation rule that requires a calculated field to be present does not mean you must supply it as input. GOBL will fill it in during calculation, and validation will then confirm the result is correct. In the validation tables, calculated fields are labeled with calculated beneath the field name.