DEV Community: dmitryvz

Stop parsing GPT's JSON by hand: structured output with the Responses API and Zod

dmitryvz — Tue, 09 Jun 2026 13:45:08 +0000

I shipped a feature that sends a photo to a vision model and gets back structured feedback — three labeled fields, every time, no exceptions. The hard part wasn't the prompt. It was getting the model to return JSON I could actually trust without writing a defensive parser around every call.

If you've ever written this, you know the pain:

const text = response.choices[0].message.content;
const json = JSON.parse(text); // 🙏 please be valid

That line works in the demo and fails in production. The model wraps the JSON in json fences. It adds a "Sure! Here's your analysis:" preamble. It returns colorCoordination one day and color_coordination the next. Every one of those is a thrown exception or a silent undefined three layers down.

Here's how I got rid of that entire class of bug using OpenAI's Responses API and Zod — with the actual code from a side project I built, an AI outfit-feedback app.

The contract: define the shape once, in Zod

The whole trick is that you describe the output shape as a schema, hand it to the API, and the API guarantees the response conforms to it. No fences, no preamble, no key drift. The model is constrained at decode time, not politely asked in the prompt.

Start with the schema. This is the exact shape my app expects back for one outfit:

import { z } from 'zod';

const outfitZod = z.object({
  fit: z.string().nullable().optional(),
  colorCoordination: z.string().nullable().optional(),
  occasionSuitability: z.string().nullable().optional(),
  error: z.string().nullable().optional(),
});

export type OutfitFeedback = z.infer<typeof outfitZod>;

Notice two things:

One schema, two jobs. It defines the wire format and gives me a TypeScript type for free via z.infer. The shape can't drift between what the API returns and what my code thinks it returns — they're the same source of truth.
An error field lives in the schema. This is how I let the model say "I can't analyze this image" inside the structured contract instead of breaking out of it with free text. More on that below — it's the part most tutorials skip.

Wiring the schema into the call

OpenAI ships a helper, zodTextFormat, that converts your Zod schema into the JSON Schema the API wants. You pass it in the text.format field of a Responses API call:

import OpenAI from 'openai';
import { zodTextFormat } from 'openai/helpers/zod';

const openai = new OpenAI({ apiKey: /* your api key */ });

export async function sendPromptToGPT(imageUrl: string): Promise<OutfitFeedback> {
  const response = await openai.responses.parse({
    model: 'gpt-5-nano', // any vision-capable model works; swap in whatever you use
    input: [
      { role: 'system', content: systemPrompt },
      {
        role: 'user',
        content: [{ type: 'input_image', image_url: imageUrl, detail: 'auto' }],
      },
    ],
    text: {
      format: zodTextFormat(outfitZod, 'outfit_response'),
    },
  });

  const parsed = response.output_parsed;
  if (!parsed) {
    throw new Error('Invalid response format from GPT');
  }

  return parsed;
}

The two lines that matter:

openai.responses.parse(...) — .parse is the structured-output variant of .create. It runs the response through your schema and hands back the validated object.
response.output_parsed — already typed as OutfitFeedback. No JSON.parse. No casting. No as any. If the model's output didn't fit the schema, this is where you'd find out, not 200 lines downstream when a .toUpperCase() blows up on undefined.

The image goes in as a content part with type: 'input_image'. The Responses API accepts both public URLs and base64 data URLs here, which matters later.

The part tutorials skip: modeling failure inside the schema

Real inputs are messy. Someone uploads a blurry photo, a screenshot of a spreadsheet, a picture with no person in it. The naive move is to let the model "handle it" in prose — which immediately breaks your structured contract, because now you're back to parsing free text to figure out whether the call succeeded.

Instead, I made failure a first-class citizen of the schema. Look back at it: error sits right next to fit and colorCoordination. The system prompt then tells the model exactly when to use it:

Return one of two shapes only:

Success: fit, colorCoordination, and occasionSuitability.

Error: error only.

If the image cannot be analyzed at all (no person present, extremely poor quality), set error to "Can not analyze the image." and omit all other fields.

Now "I can't do this" is a normal, typed, schema-valid response. My handler reads cleanly:

const parsed = response.output_parsed;
if (!parsed) {
  throw new Error('Invalid response format from GPT');
}

// The model told us, in-schema, that it couldn't analyze the image
if (parsed.error) {
  return { error: parsed.error };
}

// Belt and suspenders: a "success" response must actually be complete
if (!parsed.fit || !parsed.colorCoordination || !parsed.occasionSuitability) {
  return { error: 'Incomplete feedback received. Please try again.' };
}

return parsed;

That last check is deliberate. Structured output guarantees the response matches the schema — but my fields are .optional(), so an empty {} technically matches. The schema enforces shape, not business completeness. Keeping those two concerns separate is the whole game: let the API guarantee structure, and write the handful of lines that guarantee meaning. Don't try to make Zod express "exactly these three fields together OR just this one" — you'll fight the type system and the model. A flat schema plus two if statements is clearer and never lies to you.

Why `.nullable().optional()` and not `.string()`

This bites people, so it's worth a beat. With strict structured output, every key you declare may be required to appear. A model that has nothing to say for a field will happily emit null — and a bare z.string() rejects null, turning a perfectly reasonable response into a validation error.

z.string().nullable().optional() accepts the string you want, the null the model sometimes sends, and the absent key in the error case. You trade a little strictness at the schema layer for robustness, then recover the strictness in code with the completeness check above. That's the right division of labor.

What this buys you

Before, every call site needed a try/catch around JSON.parse, a regex to strip code fences, and a key-normalization step. All of it was load-bearing and none of it was tested, because how do you reliably reproduce "the model added a markdown fence today"?

After:

Zero hand-parsing. output_parsed is the object, typed.
One source of truth. The Zod schema is the API contract and the TS type.
Failure is data. Unanalyzable input is a typed error field, not an exception.
Refactors are safe. Rename colorCoordination in the schema and TypeScript walks you to every consumer.

The reliability jump is the real payoff. The feature went from "works until a user uploads something weird" to "handles weird input as a normal code path."

Try it

This pattern runs in production in https://stylebias.app — upload a photo, get back the three structured fields you saw above, rendered straight from output_parsed. If you're building anything that turns an image or a document into structured data, the Responses-API plus Zod combo is the cleanest approach I've found.

If you've solved this a different way — function calling, a grammar, an instructor-style wrapper — drop it in the comments.

Server-sent events in NestJS in depth

dmitryvz — Fri, 10 Nov 2023 08:46:32 +0000

Server-sent events (SSE) offer an efficient way to implement real-time updates in web applications by allowing servers to push data to connected clients.

Traditionally, a web page has to send a request to the server to receive new data; that is, the page requests data from the server. With server-sent events, it's possible for a server to send new data to a web page at any time, by pushing messages to the web page. (MDN)

In other words, the client establishes a permanent connection with the server, allowing the server to send data to the client. All modern browsers support SSE so you don't have to bring another JS library.

We use SSE at ClapDuel to update counters on page in real-time.

NestJS offers SSE out of box. Here is an example from the docs:

@Sse('sse')
sse(): Observable<any> {
  return interval(1000).pipe(map((_) => ({ data: { hello: 'world' } })));
}

Basically, you need to prepend controller action with @Sse decorator and return an observable(RxJs).

In a real application, you'll use SSE to send data when specific events occur. For instance, in a chat application, you'd send information about a new message to all connected users when a new message is posted.

In the context of NestJS, this means that a user is sending data to Action A while all users are connected to the SSE action. You need to inform the SSE action that something has happened in Action A. This can be done in many ways. In this article we will explore two solutions:

RxJs observables
EventEmitter

Here's an example that extends the one from the documentation, using observables:

private readonly sseStream = new Subject()

@Post()
actionA() {
  this.sseStream.next({type: 'new-message', data: 'Hello'})
}

@Sse('sse')
sse(): Observable<any> {
  return this.sseStream;
}

Although very simple, this approach has one major drawback - inside the SSE action the connection is already established, so, for example, you cannot decline the connection with a 403 or 404 error.

In next example we will implement SSE manually. Thanks to NestJS, manual implementation is made more straightforward with the built-in SseStream class.

@Get('sse')
sse(@Req() request, @Res() response) {
  const stream = new SseStream(request);
  return stream.pipe(response);
}

Note that we have replaced the @Sse decorator with the @Get decorator. Now we have full control over the request and response, making it possible to reject incoming requests and close connection with client if necessary.

SseStream class is just a transformational stream that will handle all headers required for SSE and will transform data you write in it into valid SSE message.

Now lets see how we can rewrite example using EventEmitter.

private readonly eventStream = new EventEmitter()

@Post()
actionA() {
  this.eventStream.emit('new-message', 'Hello')
}

@Get('sse')
sse(@Req() request, @Res() response) {
  const sseStream = new SseStream(request)
  this.eventStream.on('new-message', onNewMessage);
  response.on('close', () => {
    this.eventStream.off('new-message', onNewMessage)
  });
  return sseStream.pipe(response)

  function onNewMessage(data) {
    sseStream.write({type: 'new-message', data})
  }
}

Pay attention to the response.on('close') line, which is important for freeing up resources when the connection is closed. Don't worry if you encounter a MaxListenersExceededWarning: Possible EventEmitter memory leak detected warning.

Conclusion

NestJS simplifies the integration of SSE into your applications, offering both built-in support and manual implementation.

Using Yup to validate user input in a NestJS project

dmitryvz — Wed, 20 Sep 2023 18:17:24 +0000

This article assumes that you are familiar with NestJS framework.

The Importance of Validation
Validation is a crucial step in ensuring the integrity and security of your application. While NestJS documentation offers the class-validator library for validation, it can sometimes be challenging to work with. Lets explore an alternative validation approach using Yup in a NestJS project.

Using class-validator
In a typical NestJS project, you might define your DTOs (Data Transfer Objects) with class-validator decorators to perform validation. In my project users can submit posts with title and variable amount of teams. A team has one field - title. In accordance with Nestjs docs I created a DTO for post data and added validation to it:

class Team {
  @IsDefined({message: 'Bad request'})
  @IsString({message: 'Bad request'})
  @MinLength(TITLE_MIN_LENGTH, {
    message: 'Too short',
  })
  @MaxLength(TITLE_MAX_LENGTH, {
    message: 'Too long',
  })
  name: string;
}

class PostBody {
  @IsDefined({message: 'Bad request'})
  @IsString({message: 'Bad request'})
  @MinLength(TITLE_MIN_LENGTH, {
    message: 'Too short',
  })
  @MaxLength(TITLE_MAX_LENGTH, {
    message: 'Too long',
  })
  title: string;

  @IsDefined({message: 'Bad request'})
  @IsArray({message: 'Bad request'})
  @ArrayMinSize(MIN_TEAMS)
  @ArrayMaxSize(MAX_TEAMS)
  @ValidateNested()
  @Type(() => Team)
  teams: Team[];
}

Pretty hard to find where the real DTO is, huh?

My primary concern was that the ArrayMinSize and ArrayMaxSize validators were not functioning correctly. Users could submit any number of teams, and the DTO would still pass validation. This is a known issue with class-validator, and although workarounds exist, none of them seemed optimal.

Introducing Yup
After conducting some research I decided to switch to a library that works for all of my use cases out of box. I have looked at most popular validation libraries and found out that Yup covers all my needs:

Validates my DTOs.
Easy schema definition syntax.
Ability to incorporate error messages directly into validation rules.

Yup functions similarly to class-validator. It requires you to define validation rule schemas, allowing to separate the DTO from validation. The DTO is now a plain JavaScript object:

class PostBody {
  title: string;
  teams: Team[];
}

Validation rules can be defined as constants and can be reused across various validation scenarios. Lets define rule for validating title:

const titleSchema = string()
  .strict()
  .typeError('Bad request')
  .trim()
  .min(TITLE_MIN_LENGTH, `Too short`)
  .max(TITLE_MAX_LENGTH, `Too long`)

And now to the main point - validation for an array of objects:

const teamsSchema = array()
  .strict()
  .typeError('Bad request')
  .min(MIN_TEAMS, 'Bad request')
  .max(MAX_TEAMS, 'Bad request')
  .of(
    object({
      name: titleSchema,
    }),
  )

Schema for validating the entire post:

const postSchema = object({
  title: titleSchema,
  teams: teamsSchema,
})

Note the reuse of titleSchema in postSchema and in teamsSchema. DRY in action.

Declaring validation rules as constants enables us to create similar schemas without the need to redundantly redeclare the rules. For instance, we can define a "post create" schema that accepts all fields and a "post update" schema that accepts only the title field.

To integrate Yup validation into a NestJS project, we'll need a custom validation pipe:

class YupValidationPipe implements PipeTransform {
  constructor(private schema: ObjectSchema<any>) {}

  transform(value: any) {
    return this.schema.validateSync(value);
  }
}

Now we can use the YupValidationPipe in a controller action to validate incoming data easily:

async createPost(
  @GetUser() user: User, 
  @Body(new YupValidationPipe(postSchema)) post: PostBody
) { ... }

Conclusion
While initially seeking a library solely for required validation, my transition to Yup yielded unexpected advantages:

Cleaner and more concise DTO code.
Rule reusability.
Convenient error message handling within validation rules, facilitating user-friendly error displays (an uncommon feature in many libraries).

Of course, integrating Yup into my NestJS project required some additional effort, but it ultimately proved to be a more efficient solution compared to troubleshooting issues with class-validator.

Visit clapduel.com to see the code in action.