Define the document
Use the Ace Grid schema fields version and kind, then provide view data with stable column keys, typed values, and stable row IDs. Provenance, validation issues, metadata, and a constrained command list can travel with the result. An application envelope may add a result ID or generation timestamp, but those fields should not be confused with the Ace Grid schema contract. Reject unknown privileged fields.
Define failure behavior
Return field paths and human-readable validation errors, preserve the raw response for diagnosis, and support version negotiation. A valid schema proves shape only; the application still verifies sources, freshness, permissions, and business rules.
Define command governance
Commands should name an allowed operation and reference row IDs, not contain executable code. The server re-authorizes the user, validates current row versions, applies the mutation, records an audit event, and returns structured outcomes.
Plan compatibility and recovery
Decide how the application handles an older schema version, an unsupported command, missing citations, partial rows, and malformed values. A robust consumer can reject the unsafe portion, render a text fallback, and preserve diagnostic context. Do not coerce unknown output into plausible-looking cells because that hides model and integration failures from reviewers.
Limit resource consumption
Set maximum rows, columns, text lengths, nested values, citations, and commands. Validate before allocating expensive renderers or applying view state. Large valid payloads can still exhaust browser memory or create unusable responses. For large results, return a query or server-backed data reference rather than embedding every record in the model response.
Test schema evolution
Create fixtures for the current version, previous supported versions, unknown future versions, malformed documents, and deprecated fields. Decide whether older results are migrated, rendered read-only, or rejected. Keep validation deterministic and log compatibility outcomes. Schema evolution should not silently change the meaning of commands or permissions.
Product evidence
Structured-output contracts
@ace-grid/schema-ai includes JSON schemas for model providers or local inference tools and schemas for render, update, and command workflows.
A versioned grid result with provenance and validation
import {
createGridAiResultSchema,
validateGridSchemaDocument,
} from "@ace-grid/schema-ai";
const result = createGridAiResultSchema({
kind: "render_table",
title: "Accounts requiring review",
view: {
version: 1,
kind: "view",
data: {
columnDefs: [
{ key: "account", title: "Account" },
{ key: "risk", title: "Risk", type: "number" },
],
rows: assistantRows,
},
},
provenance: {
source: "ai",
provider: "internal-assistant",
generatedAt: new Date().toISOString(),
citations: sourceRecords.map((record) => ({
label: record.title,
url: record.url,
})),
},
});
const validation = validateGridSchemaDocument(result);
if (!validation.valid) {
return { status: "rejected", issues: validation.issues };
}
return { status: "ready", result: validation.value };Limitations and tradeoffs
- Keep ordinary conversational answers as text when a structured grid does not improve review or action.
- Do not treat schema validity as proof that generated values are true, current, or authorized.
Common questions
What must a grid output schema contain?
Use a version, stable column keys and types, stable row IDs, bounded values, optional view state, provenance, issues, and an allow-listed command model when actions are supported.
How should an unsupported schema version be handled?
Reject unsafe fields, preserve diagnostic context, and render a readable fallback rather than coercing unknown output into plausible cells.