Home/ Part V — Intermediate Track: From Playground to Real Projects/15. Structured Output: Stop Parsing Vibes/15.4 Using enums and constraints to reduce ambiguity

15.4 Using enums and constraints to reduce ambiguity

Overview and links for this section of the guide.

On this page

Why enums and constraints help so much

Most structured-output failures are not “JSON failures.” They’re “too much freedom” failures.

Enums and constraints reduce freedom by making the model pick from known options and known bounds. This:

  • reduces invalid outputs,
  • reduces surprising outputs,
  • reduces token usage,
  • improves UI rendering consistency,
  • makes testing easier.
Constraints are not “limiting creativity”

In apps, creativity is usually not the goal. Predictability is. You can always add a “creative mode” later as an explicit option.

Enums: turn open-ended text into categories

Use enums for anything that should be a fixed set of values:

  • status outcomes (ok, blocked, invalid_output)
  • confidence levels (high, medium, low)
  • content types (news, opinion, research) if you need them
  • audience (general, technical, executive)

Enums prevent the model from inventing categories (“pretty_sure”, “kinda”).

Bounds: keep outputs short and consistent

Bounds reduce two issues: cost and breakage.

Array bounds

  • maxItems prevents the model from outputting 50 bullets.
  • minItems prevents under-delivery when you need a minimum.

String bounds

  • maxLength keeps bullet strings readable and UI-friendly.
  • Shorter bounds reduce token usage and encourage concision.

Numeric bounds

If you output numbers (scores, counts), use:

  • minimum/maximum
  • explicit types (integer vs number)
Bounds are a UX tool

It’s easier to build a nice UI when you can assume “at most 10 bullets, each under 220 chars.”

Formats and patterns (use sparingly)

Some schema systems support patterns and formats (e.g., “must look like a URL”). These can help, but they also increase complexity and false negatives.

Use sparingly for:

  • IDs (simple pattern)
  • dates (if you have a clear format)
  • URLs (if you truly need them)

For v1 summarization, you usually don’t need patterns—keep it simple.

Examples of constraints for Project 1

For the article summarizer, high-leverage constraints include:

  • summary bullet count: 5–10
  • max bullet length: 220 characters
  • max entities: 12
  • max claims: 8
  • title: null allowed, max 200 chars

These constraints are simple but dramatically reduce output variability.

A constraint checklist

  • Are status fields enums?
  • Are lists bounded (maxItems)?
  • Are strings bounded (maxLength)?
  • Are unknown keys disallowed?
  • Is “unknown” represented as null or empty arrays rather than missing fields?
  • Did you keep the schema shallow and small?

Where to go next