​
Why Use Structured Output?

Structured output lets you define the exact format you expect in the model’s response, making it easier to parse, validate, and integrate downstream.

​
Prerequisites

  • An API key from Prem Studio
  • Python ≥ 3.8 or Node.js ≥ 18
  • premai or openai SDK installed

​
Supported Models

The list of supported models is constantly evolving. For the most up-to-date list of models that support structured JSON output, please visit the models list page. Models that support JSON output are clearly marked with a json tag on the models page.

​
Generate Structured Output with Prem

This quick guide is gonna show you how to extract structured data from a raw CV using the Prem SDK. You’ll define a clear schema (e.g. name, email, education, work experience) and let the model return a clean JSON object that matches it. Why it’s useful: It turns messy, unstructured CV text into structured data automatically — no regex, no manual parsing. When to use it: Perfect for dev teams building HR tools, job platforms, or internal automation scripts that need to process and understand user-submitted resumes.
1

Setup Environment

npm install premai
npm install --save-dev @types/node
export PREMAI_API_KEY=your_api_key
2

Define Output Structure and Example Text to Parse

type PersonCV = {
    name: string;
    email?: string;
    phone?: string;
    address?: string;
    education?: string[];
    work_experience?: string[];
    skills?: string[];
    awards_and_honors?: string[];
};

const schema = {
    name: "PersonCV",
    schema: {
        type: "object",
        properties: {
        name: { type: "string" },
        email: { type: "string" },
        phone: { type: "string" },
        address: { type: "string" },
        education: { type: "array", items: { type: "string" } },
        work_experience: { type: "array", items: { type: "string" } },
        skills: { type: "array", items: { type: "string" } },
        awards_and_honors: { type: "array", items: { type: "string" } }
        },
        required: ["name"]
    }
};

const cvText = `
    John Doe
    123 Main Street, Anytown, USA | [email protected] | 555-123-4567

    Education
    Bachelor of Science in Computer Science, University of Example, 2020-2024
    Relevant Coursework: Data Structures, Algorithms, Database Management

    Work Experience
    Software Engineer Intern, Example Corp, Summer 2023
    - Assisted in developing and testing software applications.
    - Wrote and maintained technical documentation.

    Skills
    Programming Languages: Python, Java, C++
    Databases: SQL, NoSQL
    Operating Systems: Windows, Linux

    Awards and Honors
    Dean's List, University of Example, 2021-2024
    `;
3

Initialize Client

import PremAI from "premai";

const client = new PremAI({
    apiKey: process.env.PREMAI_API_KEY || "",
});
4

Format Messages and Send Request with Expected Output Schema

const messages: ChatCompletionsParams.Message[] = [
    { role: "system", content: "You are a helpful assistant that can parse a person's info and return a structured object." },
    { role: "user", content: cvText }
] as any;

const response = await client.chat.completions({
    model: "phi-4",
    messages,
    response_format: {
        type: "json_schema",
        json_schema: schema
    },
});
5

Parse the Output

const raw = response.choices[0].message.content || "";

const start = raw.indexOf("{");
const end = raw.lastIndexOf("}") + 1;
const content = raw.slice(start, end);

const parsed: PersonCV = JSON.parse(content);

console.log(JSON.stringify(parsed, null, 2));
The json_repair.loads() function automatically handles malformed JSON and extracts valid JSON from text that may contain extra content before or after the JSON block. This is much more robust than using json.loads() and manual string extraction, which can fail with malformed JSON responses.

​
Full Copy-Paste Example

import { ChatCompletionsParams } from "premai/resources/chat";
import PremAI from "premai";

type PersonCV = {
    name: string;
    email?: string;
    phone?: string;
    address?: string;
    education?: string[];
    work_experience?: string[];
    skills?: string[];
    awards_and_honors?: string[];
};

const schema = {
    name: "PersonCV",
    schema: {
        type: "object",
        properties: {
        name: { type: "string" },
        email: { type: "string" },
        phone: { type: "string" },
        address: { type: "string" },
        education: { type: "array", items: { type: "string" } },
        work_experience: { type: "array", items: { type: "string" } },
        skills: { type: "array", items: { type: "string" } },
        awards_and_honors: { type: "array", items: { type: "string" } }
        },
        required: ["name"]
    }
};

const cvText = `
    John Doe
    123 Main Street, Anytown, USA | [email protected] | 555-123-4567

    Education
    Bachelor of Science in Computer Science, University of Example, 2020-2024
    Relevant Coursework: Data Structures, Algorithms, Database Management

    Work Experience
    Software Engineer Intern, Example Corp, Summer 2023
    - Assisted in developing and testing software applications.
    - Wrote and maintained technical documentation.

    Skills
    Programming Languages: Python, Java, C++
    Databases: SQL, NoSQL
    Operating Systems: Windows, Linux

    Awards and Honors
    Dean's List, University of Example, 2021-2024
`;

const client = new PremAI({
    apiKey: process.env.PREMAI_API_KEY || "",
});

const messages: ChatCompletionsParams.Message[] = [
    { role: "system", content: "You are a helpful assistant that can parse a person's info and return a structured object." },
    { role: "user", content: cvText }
] as any;

const response = await client.chat.completions({
    model: "phi-4",
    messages,
    response_format: {
        type: "json_schema",
        json_schema: schema
    },
});

const raw = response.choices[0].message.content || "";

const start = raw.indexOf("{");
const end = raw.lastIndexOf("}") + 1;
const content = raw.slice(start, end);

const parsed: PersonCV = JSON.parse(content);

console.log(JSON.stringify(parsed, null, 2));

​
Pro Tips

  • We use the json-repair package to automatically handle malformed JSON and extract valid JSON from model responses, making the parsing much more robust than using json.loads().
  • For even more advanced structured output handling, consider using the instructor package which provides additional validation and retry mechanisms.
  • If the model doesn’t follow your schema correctly, simplify the schema by reducing nesting or optional fields.
  • Be explicit in your instructions (e.g., “Return only valid JSON without any explanation or extra text.”)
  • Include examples in your prompt (few-shot prompting) to help the model understand the expected format more accurately.

​
Other Common Use-Cases

  • Extracting metadata from documents
  • Structured answers for UI rendering
  • Converting text into application-specific formats