JSON Mode Guide
Learn how to use DeepSeek's JSON mode to generate structured, parseable JSON responses for your applications.
Overview
JSON mode ensures that the model's response is valid JSON, making it perfect for:
- API integrations: Generate structured data for APIs
- Data extraction: Extract information in a consistent format
- Configuration generation: Create config files and settings
- Structured responses: Ensure predictable output format
- Database operations: Generate data for database insertion
Basic Usage
Enabling JSON Mode
python
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.deepseek.com/v1"
)
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON."
},
{
"role": "user",
"content": "Generate a user profile for John Doe, age 30, from New York."
}
],
response_format={"type": "json_object"}
)
print(response.choices[0].message.content)Example Response
json
{
"name": "John Doe",
"age": 30,
"location": {
"city": "New York",
"state": "NY",
"country": "USA"
},
"profile": {
"occupation": "Software Engineer",
"interests": ["technology", "reading", "travel"],
"contact": {
"email": "john.doe@email.com",
"phone": "+1-555-0123"
}
}
}Schema-Guided JSON Generation
Defining JSON Schema
python
def generate_with_schema(prompt: str, schema: dict):
"""Generate JSON response following a specific schema"""
schema_description = f"""
Generate a JSON response that follows this exact schema:
{json.dumps(schema, indent=2)}
Make sure all required fields are included and data types match the schema.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant that generates valid JSON following the provided schema."
},
{
"role": "user",
"content": f"{schema_description}\n\nUser request: {prompt}"
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example schema
user_schema = {
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"email": {"type": "string", "format": "email"},
"age": {"type": "integer", "minimum": 0},
"preferences": {
"type": "object",
"properties": {
"theme": {"type": "string", "enum": ["light", "dark"]},
"notifications": {"type": "boolean"},
"language": {"type": "string"}
},
"required": ["theme", "notifications"]
},
"tags": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["id", "name", "email", "age"]
}
# Generate user data
user_data = generate_with_schema(
"Create a user profile for a 25-year-old developer named Alice",
user_schema
)
print(json.dumps(user_data, indent=2))Complex Schema Example
python
# E-commerce product schema
product_schema = {
"type": "object",
"properties": {
"product": {
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"description": {"type": "string"},
"price": {
"type": "object",
"properties": {
"amount": {"type": "number", "minimum": 0},
"currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]}
},
"required": ["amount", "currency"]
},
"categories": {
"type": "array",
"items": {"type": "string"}
},
"specifications": {
"type": "object",
"additionalProperties": {"type": "string"}
},
"availability": {
"type": "object",
"properties": {
"in_stock": {"type": "boolean"},
"quantity": {"type": "integer", "minimum": 0},
"warehouse_locations": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["in_stock", "quantity"]
}
},
"required": ["id", "name", "description", "price", "categories"]
}
},
"required": ["product"]
}
# Generate product data
product = generate_with_schema(
"Create a product listing for a wireless Bluetooth headphone",
product_schema
)Data Extraction with JSON Mode
Text to Structured Data
python
def extract_structured_data(text: str, fields: list):
"""Extract structured data from unstructured text"""
fields_description = "\n".join([f"- {field}" for field in fields])
prompt = f"""
Extract the following information from the text and return as JSON:
{fields_description}
If a field is not found, use null as the value.
Text to analyze:
{text}
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a data extraction assistant. Extract information and return it as valid JSON."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example usage
email_text = """
From: john.smith@company.com
To: sales@example.com
Subject: Product Inquiry - Wireless Headphones
Date: 2024-01-15
Hi,
I'm interested in purchasing wireless Bluetooth headphones for my team of 25 people.
We need them for our remote work setup. Our budget is around $2,500 total.
Please send me a quote and delivery timeline.
Best regards,
John Smith
Product Manager
Tech Solutions Inc.
Phone: (555) 123-4567
"""
extracted_data = extract_structured_data(
email_text,
[
"sender_email",
"sender_name",
"sender_title",
"company",
"phone",
"product_interest",
"quantity",
"budget",
"purpose"
]
)
print(json.dumps(extracted_data, indent=2))Resume Parsing
python
def parse_resume(resume_text: str):
"""Parse resume and extract structured information"""
resume_schema = {
"personal_info": {
"name": "string",
"email": "string",
"phone": "string",
"location": "string",
"linkedin": "string"
},
"summary": "string",
"experience": [
{
"company": "string",
"position": "string",
"start_date": "string",
"end_date": "string",
"description": "string",
"achievements": ["string"]
}
],
"education": [
{
"institution": "string",
"degree": "string",
"field": "string",
"graduation_year": "string",
"gpa": "string"
}
],
"skills": {
"technical": ["string"],
"soft": ["string"],
"languages": ["string"]
},
"certifications": [
{
"name": "string",
"issuer": "string",
"date": "string"
}
]
}
prompt = f"""
Parse this resume and extract information according to the following structure:
{json.dumps(resume_schema, indent=2)}
Resume text:
{resume_text}
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a resume parsing assistant. Extract information from resumes and return structured JSON data."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)API Response Generation
REST API Response Builder
python
def generate_api_response(endpoint: str, method: str, scenario: str):
"""Generate API response examples"""
prompt = f"""
Generate a realistic API response for:
- Endpoint: {endpoint}
- Method: {method}
- Scenario: {scenario}
Include appropriate HTTP status, headers, and response body.
Follow REST API best practices.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are an API designer. Generate realistic API responses in JSON format."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example usage
api_response = generate_api_response(
"/api/v1/users",
"GET",
"successful retrieval of user list with pagination"
)
print(json.dumps(api_response, indent=2))Error Response Generation
python
def generate_error_response(error_type: str, context: str):
"""Generate standardized error responses"""
prompt = f"""
Generate a standardized error response for:
- Error type: {error_type}
- Context: {context}
Include error code, message, details, and any relevant metadata.
Follow standard error response patterns.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate standardized error responses in JSON format with proper error codes and messages."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
error_response = generate_error_response(
"validation_error",
"user registration with invalid email format"
)Configuration and Settings
Application Configuration
python
def generate_app_config(app_type: str, environment: str, requirements: list):
"""Generate application configuration files"""
requirements_text = "\n".join([f"- {req}" for req in requirements])
prompt = f"""
Generate a configuration file for:
- Application type: {app_type}
- Environment: {environment}
- Requirements:
{requirements_text}
Include all necessary settings, environment variables, and best practices.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate application configuration in JSON format with proper structure and comments."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
config = generate_app_config(
"web_application",
"production",
[
"database connection",
"redis caching",
"email service",
"file storage",
"logging",
"security settings"
]
)Database Schema Generation
python
def generate_database_schema(description: str, tables: list):
"""Generate database schema in JSON format"""
tables_text = "\n".join([f"- {table}" for table in tables])
prompt = f"""
Generate a database schema for: {description}
Tables needed:
{tables_text}
Include:
- Table definitions with columns
- Data types and constraints
- Primary and foreign keys
- Indexes
- Relationships between tables
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate database schema in JSON format with proper table definitions, relationships, and constraints."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
schema = generate_database_schema(
"e-commerce platform",
["users", "products", "orders", "order_items", "categories", "reviews"]
)Data Transformation
Format Conversion
python
def convert_data_format(data: str, source_format: str, target_format: str):
"""Convert data between different formats"""
prompt = f"""
Convert this {source_format} data to {target_format} format:
{data}
Ensure the conversion is accurate and maintains all data integrity.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": f"Convert data from {source_format} to {target_format} format. Return valid JSON."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example: CSV to JSON
csv_data = """
name,age,city,occupation
John Doe,30,New York,Engineer
Jane Smith,25,Los Angeles,Designer
Bob Johnson,35,Chicago,Manager
"""
json_data = convert_data_format(csv_data, "CSV", "JSON")Data Aggregation
python
def aggregate_data(data_description: str, aggregation_rules: list):
"""Generate aggregated data summaries"""
rules_text = "\n".join([f"- {rule}" for rule in aggregation_rules])
prompt = f"""
Create an aggregated summary of: {data_description}
Apply these aggregation rules:
{rules_text}
Return the results in a structured JSON format.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate data aggregation summaries in JSON format with proper statistical calculations."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
sales_summary = aggregate_data(
"monthly sales data for Q4 2023",
[
"total revenue by month",
"average order value",
"top 5 products by sales",
"customer acquisition metrics",
"regional performance breakdown"
]
)Validation and Error Handling
JSON Validation
python
import json
from jsonschema import validate, ValidationError
def validate_json_response(response_text: str, schema: dict = None):
"""Validate JSON response and handle errors"""
try:
# Parse JSON
data = json.loads(response_text)
# Validate against schema if provided
if schema:
validate(instance=data, schema=schema)
return {
"valid": True,
"data": data,
"error": None
}
except json.JSONDecodeError as e:
return {
"valid": False,
"data": None,
"error": f"Invalid JSON: {str(e)}"
}
except ValidationError as e:
return {
"valid": False,
"data": data,
"error": f"Schema validation failed: {str(e)}"
}
# Example usage
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON."
},
{
"role": "user",
"content": "Generate a product catalog entry"
}
],
response_format={"type": "json_object"}
)
validation_result = validate_json_response(
response.choices[0].message.content,
product_schema
)
if validation_result["valid"]:
print("Valid JSON:", validation_result["data"])
else:
print("Validation error:", validation_result["error"])Retry with Correction
python
def generate_json_with_retry(prompt: str, schema: dict = None, max_retries: int = 3):
"""Generate JSON with automatic retry on validation errors"""
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output valid JSON."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
# Validate response
validation_result = validate_json_response(
response.choices[0].message.content,
schema
)
if validation_result["valid"]:
return validation_result["data"]
else:
# Add error feedback for next attempt
prompt += f"\n\nPrevious attempt failed with error: {validation_result['error']}"
except Exception as e:
if attempt == max_retries - 1:
raise e
prompt += f"\n\nPrevious attempt failed with error: {str(e)}"
raise Exception(f"Failed to generate valid JSON after {max_retries} attempts")
# Example usage
try:
product_data = generate_json_with_retry(
"Generate a product listing for a smartphone",
product_schema
)
print("Generated product:", json.dumps(product_data, indent=2))
except Exception as e:
print(f"Failed to generate valid JSON: {e}")Advanced Patterns
Conditional JSON Generation
python
def generate_conditional_json(base_prompt: str, conditions: dict):
"""Generate JSON with conditional fields based on criteria"""
conditions_text = "\n".join([
f"- If {condition}: {action}"
for condition, action in conditions.items()
])
prompt = f"""
{base_prompt}
Apply these conditional rules:
{conditions_text}
Return the result as JSON.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate JSON with conditional fields based on the specified criteria."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
user_profile = generate_conditional_json(
"Generate a user profile for a premium subscriber",
{
"user is premium": "include premium_features array",
"user age > 18": "include payment_methods",
"user has purchases": "include purchase_history summary",
"user location is EU": "include gdpr_consent fields"
}
)Nested JSON Generation
python
def generate_nested_json(structure_description: str, depth_levels: dict):
"""Generate complex nested JSON structures"""
depth_text = "\n".join([
f"Level {level}: {description}"
for level, description in depth_levels.items()
])
prompt = f"""
Generate a nested JSON structure for: {structure_description}
Structure levels:
{depth_text}
Ensure proper nesting and relationships between levels.
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate complex nested JSON structures with proper hierarchy and relationships."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
# Example
org_structure = generate_nested_json(
"company organizational structure",
{
1: "company information",
2: "departments",
3: "teams within departments",
4: "employees within teams",
5: "employee details and roles"
}
)Performance Optimization
Batch JSON Generation
python
def generate_batch_json(prompts: list, batch_size: int = 5):
"""Generate multiple JSON responses in batches"""
results = []
for i in range(0, len(prompts), batch_size):
batch = prompts[i:i + batch_size]
batch_prompt = "\n\n".join([
f"Request {j+1}: {prompt}"
for j, prompt in enumerate(batch)
])
full_prompt = f"""
Generate JSON responses for the following requests.
Return an array of JSON objects, one for each request:
{batch_prompt}
"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Generate an array of JSON objects, one for each request."
},
{
"role": "user",
"content": full_prompt
}
],
response_format={"type": "json_object"}
)
batch_results = json.loads(response.choices[0].message.content)
results.extend(batch_results.get("responses", []))
return results
# Example
prompts = [
"Generate a user profile for Alice",
"Generate a product listing for a laptop",
"Generate a blog post metadata",
"Generate a meeting agenda",
"Generate a project status report"
]
batch_results = generate_batch_json(prompts)Streaming JSON Generation
python
def generate_streaming_json(prompt: str):
"""Generate JSON with streaming for large responses"""
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"},
stream=True
)
json_content = ""
for chunk in response:
if chunk.choices[0].delta.content:
json_content += chunk.choices[0].delta.content
# You can process partial content here if needed
return json.loads(json_content)
# Example
large_dataset = generate_streaming_json(
"Generate a comprehensive dataset of 100 sample users with detailed profiles"
)Best Practices
JSON Mode Guidelines
- Always include JSON instruction: Mention JSON in system message
- Use clear schema: Provide explicit structure requirements
- Validate responses: Always validate generated JSON
- Handle errors gracefully: Implement retry logic for failures
- Optimize for performance: Use batch processing for multiple requests
Common Pitfalls
python
# ❌ Bad: No JSON instruction
response = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "Generate user data"}],
response_format={"type": "json_object"}
)
# ✅ Good: Clear JSON instruction
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON."
},
{
"role": "user",
"content": "Generate user data in JSON format"
}
],
response_format={"type": "json_object"}
)
# ❌ Bad: No validation
data = json.loads(response.choices[0].message.content)
# ✅ Good: With validation
try:
data = json.loads(response.choices[0].message.content)
# Additional schema validation
validate(instance=data, schema=your_schema)
except (json.JSONDecodeError, ValidationError) as e:
print(f"JSON error: {e}")Troubleshooting
Common Issues
- Invalid JSON: Ensure system message mentions JSON output
- Missing fields: Be specific about required fields in prompt
- Wrong data types: Specify expected data types clearly
- Inconsistent format: Use schema validation for consistency
Debug Helper
python
def debug_json_generation(prompt: str, expected_schema: dict = None):
"""Debug JSON generation issues"""
print(f"Prompt: {prompt}")
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON."
},
{
"role": "user",
"content": prompt
}
],
response_format={"type": "json_object"}
)
content = response.choices[0].message.content
print(f"Raw response: {content}")
validation_result = validate_json_response(content, expected_schema)
print(f"Validation result: {validation_result}")
return validation_result
# Usage
debug_json_generation(
"Generate a user profile",
user_schema
)