LangChain4j Structured Output

Structured output is where LangChain4j's declarative style pays off most. You declare a return type on an interface method, and the library derives the schema, constrains the model and deserialises the response. This is how you wire a model into typed application code instead of parsing text by hand.

Typed return values#

The return type of the interface method is the contract:

enum Sentiment { POSITIVE, NEUTRAL, NEGATIVE }
 
record Ticket(String summary, Priority priority, List<String> components) {
    enum Priority { LOW, MEDIUM, HIGH, CRITICAL }
}
 
interface Analyst {
    // Enum — constrained to three values.
    Sentiment sentimentOf(String review);
 
    // Record — schema derived from the fields.
    Ticket triage(String bugReport);
 
    // Boolean — trivial routing logic.
    boolean isSpam(String message);
 
    // List of records.
    List<Ticket> triageAll(String bugReports);
}

Analyst analyst = AiServices.create(Analyst.class, chatModel);
 
if (analyst.isSpam(message)) return;
Ticket ticket = analyst.triage(message);   // a typed object, no parsing

Compare that to parsing free-form text into a Ticket, with retries for malformed JSON. The library handles schema generation, the instruction and deserialisation.

Enums: the most reliable structured output#

An enum return type is exceptionally reliable because the schema lists the only valid answers:

enum Intent { BILLING, TECHNICAL, SALES, OTHER }
 
interface Router {
    @UserMessage("Classify the intent of: {{it}}")
    Intent classify(String message);
}

The model cannot return REFUND_REQUEST — it is not in the enum, so the schema forbids it.

JSON schema mode#

On providers that support it, LangChain4j can use strict JSON schema mode, which constrains the output at the API level rather than through prompt instructions:

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        // Ask the provider to enforce the response schema, not just request it.
        .responseFormat("json_schema")
        .strictJsonSchema(true)
        .build();

This raises structural reliability from "very high with a clear type" to "guaranteed valid against the schema", which matters for high-volume extraction where even a rare parse failure is a real cost.

Validating values#

Structured output guarantees the object matches your type. It does not guarantee the values are correct — that is a separate concern:

record DateRange(LocalDate from, LocalDate to) {
    public DateRange {
        // The model returned two valid dates. That does not make them ordered.
        if (to.isBefore(from)) {
            throw new IllegalArgumentException("end date before start date");
        }
    }
}

Handling parse failures#

Rare with a clear type and low temperature, but not zero. Handle it:

public Optional<Ticket> triageSafely(String report) {
    try {
        return Optional.of(analyst.triage(report));
    } catch (Exception e) {
        log.warn("triage parse failed for report length {}", report.length(), e);
        return Optional.empty();   // degrade rather than crash the request
    }
}

Designing types the model can fill#

The field names are part of the prompt — the model reads them. Design for the model, not only for your database:

• Descriptive names — prepMinutes extracts better than pm.
• Flatter structures — deeply nested types are harder to fill correctly.
• Enums for closed sets — as above.
• Nullable for genuinely optional fields — with an instruction to leave unknowns null rather than guess.

record Invoice(
        String vendor,
        LocalDate date,
        List<LineItem> items,
        BigDecimal total) {
    record LineItem(String description, int quantity, BigDecimal unitPrice) {}
}

When to use structured output#

Use it whenever your code consumes the response — extraction, classification, routing, anything you if or switch on. Use plain text return only when a human reads the output directly. The rule of thumb: if the machine acts on it, type it.

Next#

You have completed Phase 2. You know LangChain4j end to end.

• What is Agentic AI? — Phase 3 begins
• Agent architecture patterns