Proposal: content:validate hook for blocking save with structured validation errors

[jdevalk]

Problem

content:beforeSave can mutate a content record but cannot reject the save. Today the only way to stop bad content from being saved is to throw from beforeSave, which surfaces to the admin UI as an opaque server error rather than a structured, field-scoped validation message.

Concrete motivator: an SEO plugin wants to enforce:

• Exactly one <h1> per post
• Non-duplicate title and description across published content
• Valid JSON-LD / schema shape

These are validation, not mutation. Failing a save from beforeSave loses the structured "field X failed because Y" information the admin UI needs.

Proposed hook

New hook content:validate. Dedicated validation phase. Runs after beforeSave mutations and before the DB write. Multiple plugins can register; pipeline collects all errors from all plugins (so the author sees every issue at once, not one-at-a-time whack-a-mole).

export interface ContentValidateEvent {
  content: Record<string, unknown>; // post-beforeSave shape
  collection: string;
  isNew: boolean;
}

export interface ContentValidationError {
  /** Dot-path into the content record, or null for record-level */
  field: string | null;
  /** Stable machine-readable code for i18n/UI handling */
  code: string;
  /** Human-readable default message (fallback if UI has no localization) */
  message: string;
  severity?: "error" | "warning"; // default "error"
}

export type ContentValidateHandler = (
  event: ContentValidateEvent,
  ctx: PluginContext,
) => ContentValidationError[] | null | Promise<ContentValidationError[] | null>;

Dispatch semantics:

• All registered handlers run (no short-circuit).
• If any handler returns an error-severity result, the save is rejected.
• Warnings don't block, but are surfaced to the UI.
• Errors from all plugins are concatenated and returned to the caller.

API surface to the admin

Save API response on validation failure:

{
  "ok": false,
  "error": "validation",
  "validation": [
    { "field": "title", "code": "seo.duplicate_title", "message": "Another post already uses this title.", "severity": "error", "source": "emdash-plugin-seo" }
  ]
}

source is added by core (plugin id of the handler that produced the error) — plugins don't need to set it themselves.

HTTP status: 422 Unprocessable Entity.

Integration site

In the save pipeline (wherever content:beforeSave is dispatched today). After that dispatch and before repo.save(), call the new content:validate dispatcher; if it returns any error-severity items, short-circuit with a 422 and the structured payload.

Autosave should skip content:validate — drafts are allowed to be invalid. Publish transitions run it.

Open questions

1. Draft vs. publish. Run always, or only on publish? Proposal: run on any save of a status === "published" record; skip for drafts. Plugins that want draft-time validation can gate on event.content.status themselves.
2. Async batch validation. Cross-record checks (duplicate title detection) need a scan. Is it OK to hit the DB from inside this hook, or should we expose an index API? For v1: plugins use ctx.content.list() / ctx.db and cache. Optimization later.
3. Warnings UX. Do we surface warnings in the admin UI now, or defer and only ship the blocking error path?
4. Webhook / API saves. Same validation pipeline, or skippable with ?skipValidation=true for trusted tooling? Proposal: same pipeline, no skip — if trusted tooling needs to bypass, it should use an internal flag that's not URL-exposed.

References

• Existing hook: content:beforeSave (packages/core/src/plugins/types.ts — ContentBeforeSaveHandler)
• Hook dispatcher: packages/core/src/plugins/hooks.ts

Needed for emdash-plugin-seo build-time / pre-publish validation. Happy to implement once shape + dispatch semantics are approved.

[ascorbic]

Hey! You can do this by setting errorPolicy: "abort" on the hook and throwing an exception. The missing part is surfacing the error to the user.