Note: This article specifically refers to the OpenAI API using the Responses API and Structured Outputs (JSON Schema). The examples here assume you are calling the OpenAI API directly from your application (such as Salesforce via Apex callouts).
Let’s clear up a common misconception first:
The OpenAI API does not expose a built-in switch like:
narrative_type = "executive_summary"
There is no parameter that magically tells the model to return bullets, tables, summaries, or decision matrices.
What the OpenAI API does provide is something much more powerful:
Structured Outputs using JSON Schema.
With Structured Outputs, you define the shape of the response, and the model is required to produce JSON matching that schema.
This means “narrative types” are actually schema contracts you define, and your application (for example a Salesforce LWC) can render each section predictably.
The Foundation: One Request Pattern, Many Narrative Shapes
With the OpenAI Responses API, structured outputs are requested using:
text.format.type = "json_schema"
Example minimal request:
{
"model": "gpt-5",
"input": [
{
"role": "system",
"content": [
{
"type": "text",
"text": "You are a precise enterprise analyst. Return only JSON that matches the schema."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Analyze the dataset and return the requested narrative fields."
}
]
}
],
"text": {
"format": {
"type": "json_schema",
"name": "NarrativeEnvelope",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"narrative": { "type": "string" }
},
"required": ["narrative"]
}
}
}
}
Why this matters:
- JSON Schema Structured Outputs are the modern evolution of “JSON mode”.
- They allow deterministic parsing.
- They prevent the model from returning arbitrary prose.
- They create stable contracts between your AI layer and your UI.
Narrative Types You Can Standardize
Each “narrative type” is simply a schema pattern you request.
Below are several useful narrative structures for enterprise systems.
1. Freeform Narrative
Purpose
Human-readable explanation.
Best for:
- emails
- case notes
- chatter posts
{
"properties": {
"narrative": {
"type": "string",
"description": "Human-readable narrative summary."
}
},
"required": ["narrative"]
}
2. Executive Summary
Purpose
Leadership-level overview without implementation detail.
{
"properties": {
"executiveSummary": {
"type": "string",
"description": "High-level summary for executives."
}
},
"required": ["executiveSummary"]
}
3. TL;DR
Purpose
Ultra-short output for previews, cards, or list views.
{
"properties": {
"tldr": {
"type": "string",
"description": "1–2 sentence TL;DR."
}
},
"required": ["tldr"]
}
4. Key Points (Bullet List)
Purpose
Scannable insights.
Perfect for UI panels.
{
"properties": {
"keyPoints": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["keyPoints"]
}
5. Action Items
Purpose
Operational next steps.
{
"properties": {
"actionItems": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"action": { "type": "string" },
"ownerRole": { "type": "string" },
"priority": {
"type": "string",
"enum": ["Low", "Medium", "High", "Critical"]
}
},
"required": ["action", "priority"]
}
}
},
"required": ["actionItems"]
}
6. Risks & Assumptions
Useful for decision transparency and governance.
{
"properties": {
"risks": {
"type": "array",
"items": { "type": "string" }
},
"assumptions": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["risks", "assumptions"]
}
7. Recommendation With Rationale
Great for architecture reviews and strategic guidance.
{
"properties": {
"recommendation": { "type": "string" },
"rationale": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["recommendation", "rationale"]
}
8. Tabular Narrative
Useful when driving UI tables (LWC datatables).
{
"properties": {
"table": {
"type": "object",
"additionalProperties": false,
"properties": {
"columns": {
"type": "array",
"items": { "type": "string" }
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": { "type": "string" }
}
}
},
"required": ["columns", "rows"]
}
},
"required": ["table"]
}
9. Decision Matrix
Ideal for comparing architecture patterns.
{
"properties": {
"decisionMatrix": {
"type": "array",
"items": {
"type": "object",
"properties": {
"option": { "type": "string" },
"pros": { "type": "array", "items": { "type": "string" } },
"cons": { "type": "array", "items": { "type": "string" } },
"score": {
"type": "number",
"minimum": 0,
"maximum": 10
}
},
"required": ["option", "pros", "cons"]
}
}
},
"required": ["decisionMatrix"]
}
10. FAQ Output
Perfect for knowledge articles and help panels.
{
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"q": { "type": "string" },
"a": { "type": "string" }
},
"required": ["q", "a"]
}
}
},
"required": ["faq"]
}
Recommended Pattern for Salesforce UIs
For enterprise applications, a single schema envelope works best.
Example:
{
"type": "object",
"additionalProperties": false,
"properties": {
"tldr": { "type": "string" },
"executiveSummary": { "type": "string" },
"narrative": { "type": "string" },
"keyPoints": {
"type": "array",
"items": { "type": "string" }
},
"actionItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": { "type": "string" },
"priority": {
"type": "string",
"enum": ["Low", "Medium", "High", "Critical"]
}
},
"required": ["action", "priority"]
}
}
},
"required": ["tldr", "executiveSummary", "narrative"]
}
Benefits:
- deterministic parsing
- one AI call per UI page
- reusable LWC renderers
- clean storage in Salesforce records
Narrative Types and Token Consumption
Different narrative structures have very different token profiles.
High token usage
- freeform narrative
- rationale explanations
- large tables
Medium token usage
- action items
- decision matrices
- FAQs
Low token usage
- TL;DR
- bullet points
- timelines
Tables are the largest token risk because tokens scale with:
rows × columns × value length
Always limit rows in prompts.
Why max_tokens Must Always Be Set
The OpenAI API does not automatically enforce safe output limits for your application.
If your prompt invites expansion, the model will continue generating until it hits internal limits.
This can cause:
- truncated JSON
- incomplete objects
- Salesforce callout timeouts
- unexpected cost spikes
Production rule
Always set max_tokens.
Example:
{
"model": "gpt-5",
"max_tokens": 1200,
"input": [...],
"text": {
"format": {
"type": "json_schema",
"schema": { }
}
}
}
Treat max_tokens the same way you treat Salesforce governor limits.
Key Design Principles for Architects
- Treat AI responses as schema contracts, not free text.
- Keep narratives short for UI, longer for exports.
- Make tables optional.
- Limit bullets and lists.
- Always set max_tokens.
In practice:
Narrative design is cost design.
The structure you request directly determines runtime cost, latency, and reliability.
Final Take
If you’re building Salesforce + OpenAI solutions, stop thinking:
“Prompt returns text.”
Start thinking:
“Prompt returns a schema contract.”
Once you adopt that mindset, narrative types become predictable, reusable UI components instead of brittle AI text blobs.
-
Prompt Design for AI: Persona, Temperature, and Tone
Over the past few months I’ve been building a Salesforce-based tool that aggregates CRM data,…
-
Designing Narrative Output Types with the OpenAI API
Note: This article specifically refers to the OpenAI API using the Responses API and Structured…
-
Named Credentials & External Credentials: The Backbone of Secure Salesforce Integrations
Named Credentials and External Credentials in Salesforce streamline integrations by centralizing authentication, eliminating secrets in…
Leave a Reply