BAML Structured Output

BAML (BoundaryML) is a domain-specific language for defining LLM functions with real types, then generating idiomatic client code for your app. This skill helps you author .baml files, run the generator, and rely on Schema-Aligned Parsing (SAP) so model outputs deserialize into your types even when the raw response is imperfect JSON. It's for engineers who are tired of brittle json.loads + retry loops and try/except wrappers around extraction, classification, and agent-tool prompts.

When to use it

• You need an LLM call to return a structured object (extraction, classification, entity tagging, routing) and want a typed result instead of a dict.
• You're hitting parse failures on models that emit markdown fences, trailing commas, unquoted keys, or partial JSON during streaming.
• You want one prompt definition consumed across Python, TypeScript, Go, and Ruby services.
• You want to iterate on prompts with live token/output preview before wiring them into code.

How it works

You write functions in the BAML DSL — class for objects, enum for closed sets, and union types (int | string, Cat | Dog) for variants. A function block declares input args, a return type, the client (model), and a prompt using the {{ ctx.output_format }} and {{ _.role("user") }} helpers. Run baml-cli generate (or let the VSCode extension regenerate on save) to emit a baml_client package with fully typed wrappers. At call time, BAML's Schema-Aligned Parsing coerces the model's text toward your declared schema rather than demanding strict JSON, so it recovers fenced blocks, fixes minor syntax, and fills partials during streaming. Annotate fields with @description to steer the model and @alias to map prompt-facing names to your code names.

Usage example

curl -fsSL --create-dirs -o ~/.claude/skills/baml-structured-output/SKILL.md https://claudeskil.com/skills/baml-structured-output/SKILL.md

// baml_src/resume.baml
class Resume {
  name string
  skills string[] @description("technical skills only")
  years_experience int @alias("yoe")
}

function ExtractResume(text: string) -> Resume {
  client "openai/gpt-4o"
  prompt #"
    Extract the resume.
    {{ ctx.output_format }}
    {{ _.role("user") }} {{ text }}
  "#
}

# after: baml-cli generate
from baml_client import b
resume = b.ExtractResume(raw_text)   # typed Resume, parsed via SAP
print(resume.skills, resume.years_experience)

Tips & gotchas

• Don't hand-edit baml_client/ — it's regenerated; change the .baml source instead.
• Use b.stream.ExtractResume(...) for partial typed objects as tokens arrive; SAP keeps each partial valid.
• Prefer enum over free string for categories — the model is constrained and parsing is more reliable.
• Add test blocks in .baml and run them from the VSCode playground to catch prompt regressions early.

FAQ

Does this force JSON mode or function-calling? No. SAP parses ordinary text output, so it works on models without native structured-output APIs.

Can I use my own model/proxy? Yes — define a client<llm> with the provider and base_url, including Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint.

What happens if the output truly can't match? BAML raises a typed parsing error rather than returning a malformed object, so failures are explicit.