ms-ai-architect/skills/ms-ai-advisor/references/prompt-engineering/structured-output-formatting.md

Structured Output and JSON Mode

Last updated: 2026-02 Status: GA Category: Prompt Engineering & LLM Optimization

---

Introduksjon

Strukturert output er en teknikk som tvinger LLM-modeller til å følge et spesifikt JSON Schema som du definerer i API-kallet ditt. Dette er en betydelig forbedring over den eldre JSON Mode-funksjonen, som kun garanterte syntaktisk gyldig JSON, men ikke kunne sikre at outputen følger et bestemt skjema.

Strukturert output gjør det mulig å:

• Definere nøyaktig hvilken datastruktur modellen skal returnere
• Eliminere parsing-feil og validerings-overhead
• Bygge robuste multi-steg workflows og integrasjoner
• Bruke type-safe objekter direkte i koden (via Pydantic i Python, for eksempel)

JSON Mode (eldre metode) garanterer kun at outputen er gyldig JSON, men gir ingen kontroll over strukturen. Microsoft anbefaler å bruke structured outputs fremfor JSON mode for alle nye implementasjoner på GPT-4o og nyere modeller.

Viktig begrensning: Strukturert output støttes for øyeblikket ikke med "bring your own data"-scenarier (Azure AI Search-integrasjon), Assistants API, eller Foundry Agents Service.

---

Kjernekomponenter

Response Format Types

Type	Beskrivelse	Anbefalt bruk
text	Standard tekstformat, ingen spesifikk struktur	Generelle tekstrespons, kreativ skriving
json_object	Garanterer syntaktisk gyldig JSON, men ingen schema-validering	Legacy — erstattet av json_schema
json_schema	Tvinger modellen til å følge et JSON Schema med strict mode	Anbefalt for alle strukturerte output-behov

Structured Outputs med JSON Schema

Python-eksempel (Microsoft Entra ID auth):

from pydantic import BaseModel
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=token_provider,
)

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="gpt-4o",  # GPT-4o 2024-08-06 eller nyere
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

event = completion.choices[0].message.parsed
print(event)  # name='Science Fair' date='Friday' participants=['Alice', 'Bob']

REST API-eksempel:

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/chat/completions \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "Extract the event information."},
      {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "CalendarEventResponse",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "date": {"type": "string"},
            "participants": {
              "type": "array",
              "items": {"type": "string"}
            }
          },
          "required": ["name", "date", "participants"],
          "additionalProperties": false
        }
      }
    }
  }'

Function Calling med Structured Outputs

For function calling, aktiver structured outputs ved å sette strict: true i function-definisjonen.

Viktig: Strukturert output støtter ikke parallell function calling. Sett parallel_tool_calls: false når du bruker strict mode.

from pydantic import BaseModel
import openai
from openai import OpenAI

class GetDeliveryDate(BaseModel):
    order_id: str

tools = [openai.pydantic_function_tool(GetDeliveryDate)]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful customer support assistant."},
        {"role": "user", "content": "What's the delivery date for order #12345?"}
    ],
    tools=tools,
    parallel_tool_calls=False  # Påkrevd for structured outputs
)

---

Arkitekturmønstre

1. Data Extraction Pattern

Bruksområde: Trekk strukturert informasjon fra ustrukturert tekst (e-poster, kundehenvendelser, dokumenter).

Fordeler:

• Ingen parsing-logikk nødvendig i applikasjonskoden
• Type-safe objekter direkte fra API-et
• Reduserer feilrate drastisk

Ulemper:

• Krever GPT-4o eller nyere modeller
• Økt token-forbruk sammenlignet med fritekst-output (marginal)

Eksempel:

class CustomerFeedback(BaseModel):
    sentiment: str  # "positive", "neutral", "negative"
    product_mentioned: list[str]
    issues: list[str]
    satisfaction_score: int  # 1-5

completion = client.beta.chat.completions.parse(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Extract feedback details from customer email."},
        {"role": "user", "content": email_text}
    ],
    response_format=CustomerFeedback,
)

2. Multi-Step Workflow Pattern

Bruksområde: Bygge komplekse workflows der hvert steg produserer strukturert output som input til neste steg.

Fordeler:

• Lettere debugging og logging
• Kan cache mellomresultater
• Enklere å parallellisere uavhengige steg

Ulemper:

• Flere API-kall (økt latency og kostnad)
• Må håndtere feil i hvert steg

Eksempel-workflow (fakta-sjekking):

1. Steg 1: Trekk ut faktiske påstander fra tekst → list[Claim]
2. Steg 2: Generer søkespørsmål for hver påstand → list[SearchQuery]
3. Steg 3: Vurder pålitelighet basert på søkeresultater → FactCheckReport

3. Form-Filling Pattern

Bruksområde: Chatbots og assistenter som samler strukturert informasjon over flere meldinger.

Fordeler:

• Garanterer at alle påkrevde felter fylles ut
• Kan validere input underveis
• Enklere å integrere med backend-systemer

Ulemper:

• Kan føles rigid for brukere hvis ikke godt designet
• Krever state management på klientsiden

---

Beslutningsveiledning

Når bruke Structured Outputs vs JSON Mode

Kriterium	Bruk Structured Outputs	Bruk JSON Mode	Bruk fritekst
Trenger eksakt schema?	✅	❌	❌
Kun syntaktisk gyldig JSON?	✅	✅	❌
Kreativ eller fleksibel output?	❌	❌	✅
Integreres direkte med database?	✅	⚠️ (må validere)	❌
Eldre modeller (GPT-3.5)?	❌	✅	✅
GPT-4o eller nyere?	✅	⚠️ (deprecated)	✅

JSON Schema-begrensninger (strict mode)

Begrensning	Detaljer
Nestingdybde	Maks 5 nivåer
Totalt antall properties	Maks 100 properties på tvers av hele schemat
Required fields	Alle fields MÅ være required (bruk ["string", "null"] for optional)
additionalProperties	MÅ være false for alle objekter
Root type	Kan ikke være anyOf
Parallell function calling	Ikke støttet med strict: true
Usupporterte keywords	minLength, maxLength, pattern, minimum, maximum, patternProperties, m.fl.

Støttede typer: String, Number, Boolean, Integer, Object, Array, Enum, anyOf (nested).

Recursive schemas: Støttes via $ref og # (root recursion).

---

Integrasjon med Microsoft-stakken

Microsoft Foundry / Azure OpenAI

API-versjon: Structured outputs introdusert i 2024-08-01-preview, tilgjengelig i GA-versjon v1.

Støttede modeller (per 2026-02):

• GPT-5-serien: gpt-5.1, gpt-5.1-codex, gpt-5-pro, gpt-5-mini, gpt-5-nano
• GPT-4-serien: gpt-4o (2024-08-06, 2024-11-20), gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
• o-serien: o1, o3-mini, o3-pro, o4-mini
• Codex: codex-mini (2025-05-16)

Ikke støttet med:

• Assistants API
• Foundry Agents Service
• "Bring your own data" (Azure AI Search)
• Audio-preview modeller (gpt-4o-audio-preview)

Semantic Kernel

Semantic Kernel støtter structured outputs via AzureAssistantAgent.configure_response_format():

from pydantic import BaseModel

class ResponseModel(BaseModel):
    response: str
    items: list[str]

client, model = AzureAssistantAgent.setup_resources()

definition = await client.beta.assistants.create(
    model=model,
    name="DataExtractor",
    instructions="Extract structured data from text.",
    response_format=AzureAssistantAgent.configure_response_format(ResponseModel),
)

Fordel: Enklere å integrere med plugins og orchestration-logikk.

Power Platform / Copilot Studio

Status: Structured outputs er ikke direkte eksponert i Copilot Studio low-code interface per 2026-02. Må brukes via custom connectors eller Power Automate med HTTP-actions mot Azure OpenAI REST API.

Workaround:

1. Opprett custom connector med OpenAI-endepunkt
2. Send response_format i request body
3. Parse JSON-output i Power Automate

---

Offentlig sektor (Norge)

Dataminimering og GDPR

Strukturert output kan hjelpe med dataminimering (GDPR Art. 5.1c) ved å:

• Kun trekke ut spesifikt definerte datafelter
• Unngå at modellen returnerer persondata som ikke er nødvendig
• Lettere å implementere anonymisering i output-schema

Anbefaling: Definer schema slik at sensitive felter (personnummer, helseopplysninger) kun inkluderes hvis eksplisitt nødvendig.

AI Act (EU)

Strukturert output kan bidra til traceability (Art. 12):

• Logg input-schema og output-schema for hver request
• Enklere å demonstrere at modellen ikke produserer uventet output
• Støtter risikovurdering ved å definere "tillatt" output-format

Forvaltningsloven og forsvarlighetskrav

§ 6 (Forsvarlighetskravet): Strukturert output øker forutsigbarheten i automatiserte vedtak:

• Reduserer risiko for at LLM-output ikke kan valideres
• Gjør det enklere å dokumentere hvordan AI-systemet fungerer
• Støtter krav om transparens i automatiserte beslutninger

Eksempel (saksbehandling):

class CaseAssessment(BaseModel):
    case_id: str
    decision: str  # "approve", "reject", "manual_review"
    legal_basis: list[str]  # Lovparagrafer
    reasoning: str
    confidence_score: float  # 0.0-1.0

# Output er strukturert og kan logges/auditeres

Schrems II og datasuverenitet

Strukturert output endrer ikke hvor data prosesseres, men:

• Kan brukes til å filtrere ut sensitive data før de sendes til Azure OpenAI
• Gjør det enklere å implementere "privacy-preserving prompts"

Anbefaling: Kombiner med Azure Private Endpoint og Customer Managed Keys for maksimal kontroll.

---

Kostnad og lisensiering

Prismodell

Strukturert output medfører ingen ekstra kostnad utover standard token-prising for Azure OpenAI. Du betaler for:

• Input tokens (prompt + schema-definisjon)
• Output tokens (JSON-strukturert output)

Observasjon: Schema-definisjonen (JSON Schema) legges til som del av system-prompt, så den teller mot input tokens. For komplekse schemas med mange properties, kan dette øke kostnadene marginalt (typisk 50-200 tokens per request).

Lisensiering

Krever Azure OpenAI-ressurs med støttet modell (se over). Ingen spesiell lisens eller feature flag nødvendig.

Microsoft 365 Copilot: Structured outputs er ikke tilgjengelig via M365 Copilot API per 2026-02. Må bruke Azure OpenAI direkte.

---

For arkitekten (Cosmo)

Spørsmål å stille kunden

1. Datakvalitet og validering

   • Hvilke datafelter er kritiske, og hvilke er "nice to have"?
   • Trenger dere streng validering av output, eller kan dere tolerere noe fleksibilitet?
   • Finnes det eksisterende JSON schemas dere bruker (OpenAPI, JSON Schema, etc.)?

2. Workflow-kompleksitet

   • Er dette en enkel "input → output"-transformasjon, eller del av en flerstegs pipeline?
   • Trenger dere å cache eller persistere mellomresultater?
   • Skal outputen integreres direkte med database, API, eller annet system?

3. Modenhet og risikotoleranse

   • Hva skjer hvis modellen ikke klarer å generere gyldig output? (fallback-strategi)
   • Har dere logging og monitoring for å oppdage schema-violations?
   • Trenger dere human-in-the-loop for kritiske beslutninger?

4. Ytelse og kostnad

   • Hva er volumet av requests? (viktig for å estimere kostnader)
   • Hva er akseptabel latency? (structured outputs kan være noe tregere enn fritekst)
   • Kan dere cache schemas på klientsiden for å redusere input tokens?

5. Sikkerhets- og compliance-krav

   • Inneholder outputen persondata eller forretningskritisk informasjon?
   • Må outputen logges for audit-trail (Forvaltningsloven)?
   • Trenger dere å filtrere ut sensitive data i output-schema?

Fallgruver å unngå

Fallgruve	Hvorfor det skjer	Hvordan unngå
For komplekse schemas	Over 100 properties eller 5 nestingsnivåer → request feiler	Bryt ned i mindre schemas, bruk multi-step workflow
Alle fields som required	Glemmer at JSON Schema strict mode krever alle fields i required	Bruk ["string", "null"] for optional fields
Glemmer additionalProperties: false	Strict mode krever dette for alle objekter	Valider schema med tool før prod
Parallell function calling	Kombinerer strict: true med parallel_tool_calls: true	Sett parallel_tool_calls: false eksplisitt
JSON Mode vs Structured Outputs	Bruker deprecated json_object for GPT-4o	Migrer til json_schema med strict: true
Manglende feilhåndtering	Anta at modellen alltid returnerer gyldig output	Sjekk finish_reason for "length" eller "content_filter"

Anbefalinger per modenhetsnivå

Nivå 1: Utforsker (PoC)

• Start med enkle schemas (< 10 properties, flat struktur)
• Bruk Pydantic i Python for rask prototyping
• Test mot GPT-4o-mini for kostnadseffektiv utvikling
• Eksperimenter med JSON Mode først hvis dere er usikre på schema-design

Nivå 2: Pilot (Testing i prod-lignende miljø)

• Definer strenge schemas med alle required fields
• Implementer validering av output (selv om structured outputs garanterer schema)
• Logg schema-violations (hvis modellen returnerer finish_reason: "length")
• Mål latency og token-forbruk for å optimalisere

Nivå 3: Produksjon (Skala og drift)

• Bruk caching for schemas som gjenbrukes ofte
• Implementer fallback til JSON Mode hvis strict mode feiler
• Overvåk error rates og juster schemas basert på faktisk bruk
• Dokumenter schema-endringer i API-contract (versjonering)

Nivå 4: Optimalisert (Kontinuerlig forbedring)

• Bruk recursive schemas for dynamiske datastrukturer (trær, grafer)
• Kombiner med function calling for agentic workflows
• Implementer A/B-testing av ulike schema-designs
• Automatiser schema-generering fra eksisterende datamodeller (SQL, OpenAPI, etc.)

---

Kilder og verifisering

Microsoft Learn (Verified)

URL	Tema	Konfidensnivå
Structured Outputs Guide	Hovedguide, API-eksempler, schema-begrensninger	Verified (2026-02)
JSON Mode Guide	JSON Mode (legacy), sammenlikning med structured outputs	Verified (2026-02)
API Reference (v1)	REST API-detaljer, response_format konfigurasjon	Verified (2026-02)
Prompt Engineering Guide	Output structure best practices	Verified (2026-02)

Azure OpenAI API-versjon

• Introduced: 2024-08-01-preview
• GA: v1 (2026-02)

Konfidensvurdering per seksjon

Seksjon	Konfidens	Kilde
Kjernekomponenter	Verified	Microsoft Learn, code samples
Arkitekturmønstre	Baseline	Generalisert fra best practices
Beslutningsveiledning	Verified	Microsoft Learn, API docs
Microsoft-integrasjon	Verified	Microsoft Learn, Semantic Kernel docs
Offentlig sektor	Baseline	GDPR/AI Act-prinsipper, ikke AI-spesifikk guidance
Kostnad og lisensiering	Verified	Azure OpenAI prising (2026-02)
For arkitekten	Baseline	Erfaring og best practices

---

Oppsummering: Structured outputs er anbefalt standard for alle nye implementasjoner som krever strukturert data fra Azure OpenAI. JSON Mode bør kun brukes for legacy-støtte eller der strict schema-validering ikke er nødvendig.