Choose Structured Outputs vs. Plain Text

Keyboard access and focus keep a single streamed answer usable. The next problem is what happens once that answer needs to carry more than plain text, real data a UI can act on. Rendering a suggested-changes card takes more than readable text. Each card usually needs stable fields like title, severity, filePath, and an action payload so a button can dispatch the right update. If the app asks for plain text, one representative output might be a bulleted list where the order and wording drift between runs, which forces a regex to guess which substring is the file name and which line implies the action.

If the app asks for JSON that matches the card component props, one representative output might keep the same keys even when the phrasing inside title changes, which keeps rendering and action wiring stable. This lesson stays focused on choosing structure only when it reduces a real UI risk.

Use the comparison below to inspect how the two approaches fail under pressure, such as streaming, retries, and small format drift.

When the UI depends on fields, the most important difference is the failure shape. Plain text tends to fail silently when parsing guesses wrong, while schema shaped JSON tends to fail loudly when a required field is missing or has the wrong type, which gives the frontend a clear point to fall back.

UI risks that structure reduces

Once plain text flows into a renderer, the first risk is parsing brittleness. A list like High severity: Fix auth bug in api.js looks stable until the model outputs api/auth.js on one run, or moves severity into parentheses, and a heuristic like split(‘:’) starts producing undefined for filePath, which can crash a card component that expects a string.

A second risk is unsafe rendering pressure. When a design calls for bolded phrases or links, teams often reach for dangerouslySetInnerHTML or markdown rendered directly into the DOM, and untrusted output can introduce unexpected tags or attributes. Rendering plain text as text nodes or rendering validated fields into known components reduces the chance of accidentally treating output as HTML.

The third risk is unreliable actions. If the UI binds a button click to an id it extracted from text, a misparse can bind the action to the wrong visible item, so clicking Fix config might apply changes intended for Fix tests because the parser matched the wrong line.

Note: Use structured outputs when the UI must read stable fields to render components or to execute an action, not when the UI only needs to display prose.

Choosing structure by feature shape

With those risks named, the next step is to decide based on what the feature actually ships to the screen. A chat answer panel is primarily a blob of text, so plain text works as long as the renderer treats it as text and avoids HTML interpolation. If you add a little structure, keep it minimal, like { "answer": "..." }, and still treat answer as free form.

Meeting notes plus an action items list often lands in the middle, because notes want free form paragraphs while action items want stable fields for checkboxes and assignees. A hybrid boundary is usually enough, where notes stays a string and actionItems is an array of objects with keys like task, owner, and dueDate, because the checklist UI reads those fields to render rows and bind completion toggles. The content can still be wrong, but the UI stops guessing where one task ends and the next begins.

Form autofill drafts push hardest toward structured outputs because each value maps directly onto an input element and a submit payload. The minimal schema should mirror the form state you own, such as { "companyName”: "...", "address": { "line1": "...", "postalCode": "..." } }, while keeping long explanations out of the schema as a separate rationale string that you display in a side panel.

Those three examples, chat panel, meeting notes, and form autofill, sit at increasing levels of structure for a reason: the more a click depends on a field, the more that field needs a guarantee. Run the sorting exercise to practice labeling features as plain text, structured outputs, or hybrid, and tie each choice to the primary UI risk it reduces.

The reliable check is whether a user can click something that changes state. If a click dispatch depends on fields, the structure is usually worth the overhead.

A decision framework you can apply

After picking an approach, the practical next step is to start from one component API you control and write down the exact props that must be present to render safely. For a SuggestedChangeCard, that might be title, severity, filePath, summary, and an action object that includes the data your handler needs, and anything the UI only displays can remain free form inside a string field.

Use a requirement driven decision instead of a preference based one.

• If latency and iteration speed dominate and the UI only displays text, prefer plain text.

• If the UI must render multiple fields or bind user actions, prefer structured outputs or a hybrid with a small schema boundary.

• If cost is tight, start with plain text and add structure only around the parts that break parsing or actions in real logs.

• If context length is the constraint, keep schemas small and keep long narrative content in a free form field.

Even when a schema matches your component props, the request and the field set still need careful wording and periodic rechecks against your own component definitions before shipping, because the schema constrains shape but does not guarantee correct content.