LLM APIs - lesson 4 | HackIndia Skills

Key point

One idea

When your app needs data, do not ask for “JSON please” and hope. Give the Responses API a strict JSON schema so the model must return keys your code can use.

JSON mode only guarantees valid JSON. Structured Outputs with json_schema and strict: true is the safer choice for product features.

Use this for

Structured JSON is useful when the AI result goes into UI cards, a database row, a search filter, or a workflow step.

Example: a campus events app can turn a messy event description into title, date_text, venue, fee_rupees, and tags. Your frontend should not scrape a paragraph to find these.

Your to-do

Design the shape

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Decide the exact fields your app needs before writing the prompt.
Make every field required in the schema.
Use null when a value may be missing, instead of making the field optional.
Set additionalProperties to false so extra keys do not appear.
Keep developer instructions separate from user input.

0 of 5 done

Example

Server route example

This example uses the official server-side JavaScript SDK. Keep your API key in OPENAI_API_KEY, not in browser code.

The model name shown is one documented as supporting Structured Outputs. If your project uses another model, check that it supports Structured Outputs before shipping.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

export async function POST(req) {
  const { eventText } = await req.json();

  const response = await client.responses.create({
    model: "gpt-4o-mini",
    instructions: "Extract campus event details. Return only data that fits the schema. If a value is not present, use null.",
    input: eventText,
    text: {
      format: {
        type: "json_schema",
        name: "campus_event",
        strict: true,
        schema: {
          type: "object",
          additionalProperties: false,
          properties: {
            title: { type: "string" },
            date_text: { type: ["string", "null"] },
            venue: { type: ["string", "null"] },
            fee_rupees: { type: ["number", "null"] },
            tags: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["title", "date_text", "venue", "fee_rupees", "tags"]
        }
      }
    }
  });

  const data = JSON.parse(response.output_text);

  return Response.json({ event: data });
}

Common mistake

Do not paste user text inside instructions. Instructions are your app rules and business logic. User input is the messy content those rules apply to.

Also avoid schemas with optional fields. For Structured Outputs, specify all fields as required. Use a union with null for fields that may be unknown.

Tip

Check AI output

AI can still return data that is technically valid but not useful. Check meaning before saving it.

For example, if fee_rupees is null, your UI can show “Fee not mentioned”. Do not silently treat it as 0, or users may think the event is free.