Headless Laravel Forms: Designing a Stable Schema and Submission API
Headless Laravel Forms: Designing a Stable Schema and Submission API
Returning a form's JSON column does not create a headless form platform. A real API needs a public compatibility contract, server-authoritative validation, authentication and abuse controls, uploads, idempotency, error semantics, and a migration policy for clients you do not deploy.
Start with an iframe when the consumer can host the complete Laravel/Livewire form. Build a headless API only when native mobile UI, offline behavior, a deeply integrated SPA, or multiple non-Laravel clients justify owning another rendering stack.
Separate schema format from form revision
Expose both:
{
"schema_format": "1.0",
"form_revision": "01K...",
"form": { "code": "job-application", "title": "Apply" },
"fields": []
}
schema_format tells a client how to interpret the document. form_revision identifies the immutable published definition that must validate and label the submission. A client can support format 1.0 while receiving many business revisions.
Every submission and draft should send the revision it rendered. Reject or explicitly migrate a stale/retired revision rather than silently validating against the current form.
Publish capabilities, not server internals
Design a small field vocabulary with stable machine identifiers:
{
"code": "contact_email",
"type": "email",
"label": "Work email",
"required": true,
"constraints": { "max_length": 254 }
}
Do not leak PHP class names, Filament component configuration, Eloquent models, table names, or arbitrary Laravel validation strings. Clients need portable behavior, while the server retains its implementation freedom.
Conditional rules need a documented expression language with bounded depth/operators. If a client cannot implement a new capability, define whether it hides the field, falls back, or refuses the form. Unknown required behavior should not be guessed.
Keep the server authoritative
The client renders hints and validates for feedback. The submit endpoint reloads the immutable revision and compiles trusted server rules. Never accept a schema or rule set from the submit payload.
Return structured validation errors with stable field codes and machine error categories plus localized human messages:
{
"error": "validation_failed",
"fields": {
"contact_email": [
{ "code": "email", "message": "Enter a valid email address." }
]
}
}
Do not make clients parse English text to understand errors.
Choose access and origin controls separately
CORS tells browsers which origins may read a response; it is not authentication and does not stop non-browser clients. Public forms may use an opaque public key plus rate limits and bot controls. Private forms need user/tenant authorization. Administrative schema endpoints need stronger abilities than anonymous submit.
Allowlist exact production origins where credentials or private data are involved. Avoid reflecting arbitrary Origin values. If cookies are used cross-origin, account for CSRF and browser third-party-cookie policy. Token-based APIs need narrow abilities, expiry/rotation, and safe storage.
Make submission retry-safe
Mobile networks and SPAs retry. Require an idempotency key per logical submission, store a request hash, and enforce a unique scope in the database. A same-key/same-body retry returns the original result; same key with a changed body is a conflict.
Dispatch notifications and integrations after the submission transaction commits. The idempotency guide covers the complete state model.
Design uploads as a separate protocol
Large files should not be embedded as base64 in JSON. Common choices are multipart submission for small files or a two/three-step flow:
- request an authorized temporary upload slot;
- upload directly to private object storage;
- submit a server-issued upload token with the form;
- verify ownership, status, type, size, and expiry before attachment.
Unclaimed uploads need cleanup. A token must not allow attaching another user's or tenant's object. File validation and scanning remain server responsibilities; see the upload security checklist.
Plan compatibility before launch
Document additive and breaking changes. A practical policy:
- adding an optional field/capability is additive only if clients can safely ignore it;
- adding a required unsupported capability is breaking;
- changing field codes or option values is breaking for stored drafts;
- editing a published revision creates a new revision;
- schema-format changes receive a new major and overlap window.
Use HTTP caching with ETag/checksum for immutable revisions. Do not cache private/tenant schema responses under a public key.
Observability without answer leakage
Log form/revision IDs, client version, status, latency, error categories, and request IDs. Avoid raw answers, authorization headers, upload tokens, and secrets. Track unsupported-capability failures so client upgrades are driven by evidence.
Contract tests
- every published schema validates against the format meta-schema;
- old supported clients can parse additive fixtures;
- unknown required capability fails safely;
- client validation and server rules agree on shared fixtures;
- tampered revision and cross-tenant identifiers fail;
- duplicate keys create one submission;
- upload tokens are scoped, expire, and cannot be replayed across users;
- localized errors retain stable codes;
- CORS never grants an unconfigured origin credentials;
- immutable revisions return stable ETags.
The embedding guide helps decide when an iframe is enough. A headless API is worthwhile when client-native rendering is a real requirement—and credible when it behaves as a versioned product rather than an accidental serialization of server objects.