Validation Rules Reference

A complete reference of every rule Klervex applies to a shipment before it generates documents. Validation is deterministic — the same input always produces the same result — and runs in under one second.

If a rule fails, Klervex returns a structured error with the rule ID, the field path, and a specific message. Documents are not generated until the failing rules are fixed or explicitly waived.

How Validation Works

Klervex uses Rynko Flow to evaluate rules. The flow is:

1. Schema validation — Field types, required fields, format constraints
2. Business rule evaluation — Cross-field rules and lookup table queries
3. Country-specific rules — Applied based on origin and destination
4. Document-specific rules — Applied based on the requested document types

Every rule:

• Has a unique rule ID (e.g. rule_total_matches_line_items)
• Returns a structured error message if it fails
• References a specific field path in the shipment data
• Is explainable — you can see exactly why a rule failed and what to change

Error Response Format

{
  "valid": false,
  "score": 87,
  "results": [
    {
      "rule_id": "rule_hs_code_us",
      "category": "HS Code",
      "severity": "error",
      "message": "HS code 9999.99.9999 not found in US HTS schedule",
      "field": "goods.line_items[0].hs_code"
    }
  ],
  "validation_hash": "sha256:a1b2c3...",
  "validated_at": "2026-04-08T10:00:00Z"
}

Severity Levels

Severity	Behavior
error	Blocks document generation. Must be fixed.
warning	Allows document generation but flagged for review.
info	Informational only.

---

Category 1 — Required Fields

Mandatory fields that must be present on every shipment.

Rule ID	Check	Severity
rule_exporter_required	Exporter name, address, and country must be present	error
rule_importer_required	Importer name, address, and country must be present	error
rule_route_required	Route origin, destination, and transport mode must be present	error
rule_currency_required	Currency must be a valid ISO 4217 three-letter code	error
rule_has_line_items	At least one line item must be present	error
rule_line_item_description	Each line item must have a non-empty description	error
rule_line_item_quantity	Each line item must declare a quantity	error
rule_line_item_unit_price	Each line item must declare a unit price	error

---

Category 2 — Mathematical Consistency

Cross-field math checks that catch silent extraction errors and data entry mistakes.

Rule ID	Check	Severity
rule_positive_total	goods.total_value > 0	error
rule_positive_quantities	Every line item quantity must be greater than zero	error
rule_positive_prices	Every line item unit price must be greater than zero	error
rule_total_matches_line_items	goods.total_value equals sum(line_items, quantity × unit_price)	error
rule_gross_gte_net_weight	Gross weight must be ≥ net weight per line item	error
rule_total_packages_consistent	Total packages count matches packages array length	warning
rule_total_weight_consistent	Total gross weight matches sum of package weights	warning

Example: total mismatch

{
  "rule_id": "rule_total_matches_line_items",
  "severity": "error",
  "message": "Total value 25000 does not match sum of line items 24500",
  "field": "goods.total_value",
  "context": {
    "declared_total": 25000,
    "computed_total": 24500,
    "difference": 500
  }
}

---

Category 3 — HS Code Validation

Every line item HS code is checked against the destination country's actual tariff schedule. Klervex maintains synced lookup tables for US HTS, EU TARIC, UK Trade Tariff, and India Customs Tariff.

Rule ID	Check	Severity
rule_hs_code_format	HS code must be a 6-10 digit numeric code	error
rule_hs_code_us	When destination is US, HS code must exist in US HTS lookup table	error
rule_hs_code_eu	When destination is in EU, HS code must exist in EU TARIC lookup table	error
rule_hs_code_uk	When destination is UK, HS code must exist in UK Trade Tariff lookup table	error
rule_hs_code_in	When destination is IN, HS code must exist in India Customs Tariff lookup table	error
rule_hs_code_length_us	US destination requires 10-digit HTS codes	error
rule_hs_code_length_eu	EU destination requires 10-digit codes	error
rule_hs_code_length_in	India destination requires 8-digit codes	error
rule_origin_country_per_item	Each line item must have a declared origin_country	error

Lookup table data sources

Table	Source	Refresh
hs_codes_us	Derived from WCO 6-digit codes (10-digit extension)	Quarterly
hs_codes_eu	Derived from WCO 6-digit codes (8-digit extension)	Quarterly
hs_codes_uk	HMRC UK Trade Tariff API (trade-tariff.service.gov.uk)	Quarterly
hs_codes_in	Derived from WCO 6-digit codes (8-digit extension)	Quarterly
hs_codes_wco	World Customs Organization 6-digit reference	Annual
duty_rates	Not populated — see note below	—

Duty Rates — Not Yet Implemented

The duty_rates lookup table exists but is intentionally empty. No business rules currently reference it, and no UI displays duty rate information. Duty rates are complex — they vary by trade agreements, quotas, anti-dumping measures, and seasonal adjustments. A simple MFN rate doesn't capture the full picture.

This table will be populated when Klervex adds duty estimation features (estimated landed cost, duty cost on shipment summary). Real rate sources:

• UK: trade-tariff.service.gov.uk/api/v2/bulk_search
• US: hts.usitc.gov/export (HTS CSV/JSON with general rate of duty)
• EU: ec.europa.eu/taxation_customs/dds2/taric/ or CN CSV dumps

For now, HS code validation works independently of duty rates — it checks code existence, not the rate.

---

Category 4 — Sanctions & Party Screening

All parties named on a shipment are screened against the OFAC Specially Designated Nationals (SDN) list.

Rule ID	Check	Severity
rule_sanctions_exporter	Exporter not on OFAC SDN list	error
rule_sanctions_importer	Importer not on OFAC SDN list	error
rule_sanctions_notify_party	Notify party (if present) not on OFAC SDN list	error
rule_embargoed_origin	Origin country not on comprehensive embargo list	error
rule_embargoed_destination	Destination country not on comprehensive embargo list	error

Lookup table data sources

Table	Source	Refresh
sanctions_ofac	US Treasury OFAC Specially Designated Nationals list	Daily

---

Category 5 — Route & Transport

Route validation ensures the declared journey is physically possible and that the transport mode is consistent with the documents.

Rule ID	Check	Severity
rule_port_of_loading_valid	Port of loading must be a valid UN/LOCODE	error
rule_port_of_discharge_valid	Port of discharge must be a valid UN/LOCODE	error
rule_port_country_match_origin	Port of loading must be in the declared origin country	warning
rule_port_country_match_dest	Port of discharge must be in the declared destination country	warning
rule_exporter_country_matches_origin	exporter.country must equal route.origin_country	error
rule_importer_country_matches_dest	importer.country must equal route.destination_country	error
rule_transport_mode_valid	Transport mode must be one of: sea, air, road, rail, multimodal	error

Lookup table data sources

Table	Source	Refresh
port_codes	UNECE UN/LOCODE database	Quarterly

---

Category 6 — Incoterms 2020

Incoterms must be a valid 2020 code and compatible with the declared transport mode.

Rule ID	Check	Severity
rule_incoterms_valid_2020	Must be one of: EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF	error
rule_incoterms_sea_only	FAS, FOB, CFR, CIF only valid with sea or inland waterway transport	error
rule_incoterms_2010_deprecated	Old 2010 codes (DAT, DAF, DES, DEQ, DDU) are no longer accepted	error

Sea-only Incoterms

Code	Full name	Required transport mode
FAS	Free Alongside Ship	Sea or inland waterway
FOB	Free On Board	Sea or inland waterway
CFR	Cost and Freight	Sea or inland waterway
CIF	Cost, Insurance, and Freight	Sea or inland waterway

Multimodal Incoterms

Code	Full name	Compatible transport modes
EXW	Ex Works	Any
FCA	Free Carrier	Any
CPT	Carriage Paid To	Any
CIP	Carriage and Insurance Paid To	Any
DAP	Delivered at Place	Any
DPU	Delivered at Place Unloaded	Any
DDP	Delivered Duty Paid	Any

---

Category 7 — Country-Specific Compliance

Country-specific rules that apply based on the origin or destination jurisdiction.

United States

Rule ID	Check	Severity
rule_us_hts_10_digit	US destination requires 10-digit HTSUS code per line item	error
rule_us_ein_format	If exporter has EIN, must be in XX-XXXXXXX format	warning

European Union

Rule ID	Check	Severity
rule_eu_eori_required	EU destination requires importer EORI	error
rule_eu_eori_format	EORI must follow <country><digits> format (e.g. DE123456789012345)	error
rule_eu_taric_10_digit	EU destination requires 10-digit TARIC code per line item	error

United Kingdom

Rule ID	Check	Severity
rule_uk_eori_gb_prefix	UK destination requires GB-prefixed EORI (post-Brexit)	error
rule_uk_eori_format	Format GB<9 digits> or GB<12 digits>	error

India

Rule ID	Check	Severity
rule_in_iec_required	India destination requires importer IEC (Importer-Exporter Code)	error
rule_in_iec_format	IEC must be a 10-character alphanumeric code	error
rule_in_gstin_format	If GSTIN provided, must match 15-character GST format	warning
rule_in_pan_format	PAN must match [A-Z]{5}[0-9]{4}[A-Z]	warning

---

Category 8 — Document-Specific Rules

Per-document rules that apply only when the relevant document type is being generated.

Rule ID	Document	Check	Severity
rule_doc_bl_sea_only	Bill of Lading	Transport mode must be sea or multimodal with sea leg	error
rule_doc_awb_air_only	Air Waybill	Transport mode must be air	error
rule_doc_coo_origin_per_item	Certificate of Origin	Each line item requires origin_country	error
rule_doc_dgd_un_classification	Dangerous Goods Declaration	Hazardous items need UN number, hazard class, packing group	error
rule_doc_vgm_sea_container	VGM Declaration	Transport mode must be sea and packaging.containers must be present	error
rule_doc_vgm_method_valid	VGM Declaration	Weighing method must be 1 (entire weighed) or 2 (sum of contents)	error
rule_doc_eur1_agreement	EUR.1 Movement Certificate	preferential_origin.agreement_name must be set	error
rule_doc_usmca_parties	USMCA Certificate of Origin	At least one party must be in US, MX, or CA	error
rule_doc_phyto_botanical	Phytosanitary Certificate	Each plant product requires botanical name	error
rule_doc_health_vet_authority	Health/Veterinary Certificate	Competent authority and inspection date required	error
rule_doc_coa_test_results	Certificate of Analysis	At least one test result row required	error

---

Category 9 — Format Validation

Schema-level format checks for individual fields.

Rule ID	Check	Severity
rule_format_iso_country	All country fields must be ISO 3166-1 alpha-2 (two uppercase letters)	error
rule_format_iso_currency	Currency must be ISO 4217 (three uppercase letters)	error
rule_format_email	Contact emails must be valid email format	warning
rule_format_phone	Phone numbers must contain only digits, spaces, +, -, ()	warning
rule_format_date_iso8601	All date fields must be ISO 8601 format	error
rule_format_postal_code_us	US postal codes must be 5 or 9 digits	warning

---

Requesting New Rules

The rule library is curated by the Klervex team and updated as customs regulations change. If you need a rule that isn't in the list above — for example, a country-specific check, a new document type, or an industry-specific compliance requirement — please reach out at [email protected].

We prioritise rule additions that benefit multiple customers over single-team customizations.

---

Rule Updates

The Klervex rule library is updated as customs regulations change. Recent changes:

Date	Change
2026-04	Added USMCA Certificate of Origin rules
2026-04	Added VGM Declaration rules (SOLAS)
2026-04	Added EUR.1 Movement Certificate rules
2026-04	Added Phytosanitary, Health/Veterinary, COA document rules
2026-03	Added India IEC and GSTIN format checks
2026-03	Updated EU TARIC lookup table to current version
2026-02	Added comprehensive Incoterms 2020 transport mode validation

---

Try It

Want to see the rules running on your own data?

1. Sign up at app.klervex.com (free tier: 5 shipments/month)
2. Upload a commercial invoice or enter shipment data manually
3. Click Validate — you'll see exactly which rules pass, which fail, and why

Or use the REST API:

curl -X POST https://app.klervex.com/api/v1/shipments/validate \
  -H "Authorization: Bearer klv_your_api_key" \
  -H "Content-Type: application/json" \
  -d @shipment.json

The response includes the full rule evaluation result — every rule that ran, every pass and fail, and the validation hash for downstream verification.