Back to blog

Headless Laravel Forms: Designing a Stable Schema and Submission API

Manuk Minasyan · · 5 min read
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:

  1. request an authorized temporary upload slot;
  2. upload directly to private object storage;
  3. submit a server-issued upload token with the form;
  4. 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:

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

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.

Related posts