formkrafter (Python)

FormKrafter for Python backends. The server validates a submission with the same spec the browser renders, and reaches the same verdict: same error keys (items[0].hs_code), same messages, same warnings as @streamline-pulse/formkrafter-core.

pip install formkrafter            # no dependency
pip install "formkrafter[pydantic]"  # Pydantic models for specs built in code

from formkrafter import validate_form_data

result = validate_form_data(spec, payload, locale="fr")
if not result.valid:
    # {"items[0].declared_value": "Minimum 0", "origin": "Ce champ est obligatoire"}
    return 422, result.errors

What it does

validate_form_data returns a ValidationResult:

• valid, errors (key → message) and warnings, as in the browser; to_dict() gives the core's shape;
• details (key → ErrorDetail(validator, message, value)), so an API can return a stable code and let the client word it: {"items[0].declared_value": {"validator": "min", "value": 0, "message": "Minimum 0"}}.

Every function takes a plain dict or a formkrafter.models.BrickSpec.

Supported

• Validations: required, min/max, minLength/maxLength, pattern, minItems/maxItems, email, url.
• Bricks: panels, inputs, selects (multiple included), collections (data grids, nested at any depth), outputs. On top of those:
  • national-id and tax-id check their idFormat, iban its key;
  • vehicle-plate and company-registry check their format;
  • date-range must not end before it starts;
  • mrz must hold a readable zone whose check digits match.
• Rules: JsonLogic rules are evaluated on the submitted data (plus rule_scope): a field they hide is not checked, as in the browser. Rules that only disable, prefill or require never change the verdict, whatever their language.

One deliberate difference: the browser trusts the valid flag the mrz brick stores, while the server re-reads the zone (raw) it was sent. Honest data gets the same verdict; a forged flag does not pass.

The details that usually make a Python port drift are reproduced:

• Ajv's email and uri formats, copied verbatim;
• the browser's RegExp: $ never matches before a trailing newline, and \d is ASCII;
• String(1e-7) is 1e-7;
• the core compares lengths in code points;
• JsonLogic's ==, < and + coerce like JavaScript ("1" == 1, [2] < 10), and [] is falsy;
• a schema Ajv refuses to compile enforces no rule (with a warning). An idFormat, plateFormat or registryFormat the core does not know is one such case.

Refused

JavaScript never runs server-side. validate_form_data raises SpecNotSupported rather than half-validating a spec where JavaScript decides the verdict:

• custom validators (validator: "custom"): move the check to the server, or to a declarative validation;
• JavaScript rules, or code effects, that hide data-carrying fields: write the condition in JsonLogic.

JavaScript rules that hide nothing (a disabled effect, a note) are accepted.

build_validation_schema and lint_spec work on every spec. assert_supported(spec) checks up front, for instance in the tests that cover the specs a backend serves.

Parity with the core

tests/parity/cases.json holds specs and data samples. The core compiles and validates them:

bun scripts/python-parity.ts      # from the repository root: rewrites tests/parity/expected.json
uv run pytest                     # the port must reach the same schemas, lint issues and verdicts

CI regenerates the fixtures and fails when they are stale, so a change in the core shows up in the Python tests. formkrafter.CORE_VERSION names the core release a version follows.

In your own project

formkrafter.testing checks your specs against the real core, through Node and your web app's installed @streamline-pulse/formkrafter-core:

from formkrafter.testing import assert_matches_core

def test_served_forms_match_the_browser():
    assert_matches_core(SPEC, samples=[VALID, {}, {"items": []}], locales=["fr", "en"], node_project="../web")

export_contract(spec, locales) returns the spec with its schema per locale. Write it where your web tests read it to assert that buildValidationSchema(spec, locale) gives the same.