Categories and Publication Lifecycle

Categories

• category key is UUID
• category slug is stable and generated or maintained
• categories can be is_system
• form category assignment accepts UUID key or slug

Forbidden category names

Use formforge.categories.forbidden_names to block reserved category names in management operations. Name matching is normalized before validation: comparison is case-insensitive and ignores leading/trailing spaces. The rule is enforced on both category creation and category update.

'categories' => [
    'forbidden_names' => ['Internal', 'System'],
],

If a forbidden name is sent to POST /api/formforge/v1/categories or PATCH /api/formforge/v1/categories/{categoryKey}, the API returns 422 Unprocessable Entity. Validation includes an error on category.

Revision lifecycle

• create creates revision 1
• patch creates a new draft revision
• publish creates a new published revision
• unpublish creates a new draft revision
• delete soft-deletes revisions

Publishability

A form can be published only when:

• title is non-empty
• at least one page exists
• at least one field exists

Publication settings

Form schemas can carry publication-related settings that the runtime and client builder both understand:

• publish_at
• pause_at
• response_limit
• submission_code_required
• submission_code

These settings control when a form opens, when it stops accepting responses, and whether a PIN is required before submission.

• publish_at opens the form at a specific date and time
• pause_at stops the form from accepting new responses at a specific date and time
• response_limit closes the form after the configured number of submissions
• submission_code_required and submission_code protect the form with a PIN