JSON-LD Best Practices
Follow these practices for effective JSON-LD implementation.
Practice 1: Use Proper Context and Type
Always include complete context and type declarations.
Correct Implementation:
{
"@context": "https://schema.org",
"@type": "Article"
}
Common Mistakes:
// Missing context
{
"@type": "Article"
}
// Missing type
{
"@context": "https://schema.org"
}
// Wrong context URL
{
"@context": "http://schema.org", // Should be https://
"@type": "Article"
}
Why This Matters:
- Provides namespace for schema vocabulary
- Enables proper data interpretation
- Prevents data parsing errors
- Required for AI model understanding
Practice 2: Include All Required Properties
Never omit required properties for your schema type.
Article Schema Required Properties:
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Complete JSON-LD Guide for AI Search",
"author": {
"@type": "Organization",
"name": "Texta"
},
"datePublished": "2026-03-17"
}
Check Required Properties:
- Refer to schema.org documentation
- Use validation tools to catch missing properties
- Document required properties for each schema type
- Create templates for common schema implementations
Practice 3: Use Complete Property Sets
Include recommended and optional properties for comprehensive data.
Complete Article Schema:
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Complete JSON-LD Guide for AI Search",
"description": "Comprehensive guide to JSON-LD implementation for AI search optimization",
"author": {
"@type": "Person",
"name": "John Smith",
"jobTitle": "Senior SEO Strategist",
"worksFor": {
"@type": "Organization",
"name": "Texta",
"url": "https://texta.ai"
}
},
"publisher": {
"@type": "Organization",
"name": "Texta",
"logo": {
"@type": "ImageObject",
"url": "https://texta.ai/logo.png"
}
},
"datePublished": "2026-03-17",
"dateModified": "2026-03-17",
"image": {
"@type": "ImageObject",
"url": "https://texta.ai/blog/json-ld-guide.jpg",
"width": 1200,
"height": 630
},
"about": ["JSON-LD", "Structured Data", "AI Search"],
"keywords": ["json-ld", "ai search", "structured data"],
"articleSection": "Implementation & Tactics",
"wordCount": 2500
}
Benefits of Complete Properties:
- AI models extract richer context
- Better citation accuracy
- Improved source positioning
- Enhanced knowledge graph building
Practice 4: Use Proper Data Types
Ensure property values use correct data types.
Data Type Guidelines:
Text (String):
{
"headline": "Article Title", // String
"description": "Content description" // String
}
Dates (ISO 8601):
{
"datePublished": "2026-03-17", // Date only
"dateModified": "2026-03-17T10:30:00Z", // Date and time
"timeRequired": "PT15M" // Duration
}
Numbers:
{
"wordCount": 2500, // Integer
"ratingValue": 4.8, // Float
"bestRating": 5, // Integer
"worstRating": 1 // Integer
}
URLs (Absolute):
{
"url": "https://texta.ai/blog/article", // Full URL
"sameAs": ["https://linkedin.com/company/texta"], // Array of URLs
"logo": {
"@type": "ImageObject",
"url": "https://texta.ai/logo.png" // Full image URL
}
}
Booleans:
{
"isAccessibleForFree": true, // Boolean
"isFamilyFriendly": false // Boolean
}
Enumerations:
{
"inLanguage": "en", // Language code
"availability": "https://schema.org/InStock", // Enumeration URL
"itemCondition": "https://schema.org/NewCondition"
}
Practice 5: Use Nested Structures for Relationships
Express relationships using nested objects.
Author with Nested Organization:
{
"author": {
"@type": "Person",
"name": "John Smith",
"jobTitle": "Senior SEO Strategist",
"worksFor": {
"@type": "Organization",
"name": "Texta",
"url": "https://texta.ai",
"logo": {
"@type": "ImageObject",
"url": "https://texta.ai/logo.png"
}
},
"knowsAbout": ["SEO", "AI Search", "Structured Data"]
}
}
Product with Nested Offer:
{
"@type": "Product",
"name": "Texta Pro",
"offers": {
"@type": "Offer",
"url": "https://texta.ai/pricing",
"price": "299.00",
"priceCurrency": "USD",
"priceValidUntil": "2026-12-31",
"availability": "https://schema.org/InStock",
"seller": {
"@type": "Organization",
"name": "Texta"
}
}
}
Why Nested Structures Matter:
- Express complex relationships clearly
- AI models understand entity connections
- Enables knowledge graph building
- Improves citation context accuracy
Practice 6: Use Array Notation for Multiple Values
Use arrays for properties with multiple values.
Multiple Authors:
{
"author": [
{
"@type": "Person",
"name": "John Smith",
"jobTitle": "Senior SEO Strategist"
},
{
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Content Strategist"
}
]
}
Multiple Topics:
{
"about": [
{
"@type": "Thing",
"name": "JSON-LD"
},
{
"@type": "Thing",
"name": "Structured Data"
},
{
"@type": "Thing",
"name": "AI Search"
}
]
}
Multiple SameAs URLs:
{
"sameAs": [
"https://linkedin.com/company/texta",
"https://twitter.com/texta",
"https://github.com/texta",
"https://www.facebook.com/texta"
]
}
Practice 7: Validate JSON Syntax
Ensure valid JSON before implementation.
Valid JSON Rules:
- Use double quotes (not single quotes)
- Quote property names
- Quote string values
- No trailing commas
- Proper nesting with braces and brackets
- Escape special characters (quotes, backslashes)
Invalid JSON Examples:
// Single quotes (invalid)
{'name': 'Texta'}
// Unquoted property names (invalid)
{name: "Texta"}
// Trailing comma (invalid)
{
"name": "Texta",
}
// Unescaped quotes (invalid)
{
"description": "Texta's "amazing" platform" // Unescaped quotes
}
Correct JSON:
{
"name": "Texta",
"description": "Texta's \"amazing\" platform"
}
Validation Tools:
- JSONLint.com
- Schema.org Validator
- Google Rich Results Test
- Browser console (for syntax errors)
Practice 8: Optimal Placement in HTML
Place JSON-LD strategically within your HTML.
Preferred Placement:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Page Title</title>
<!-- Place JSON-LD in head if possible -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Your Title",
"author": {
"@type": "Organization",
"name": "Your Brand"
},
"datePublished": "2026-03-17"
}
</script>
</head>
<body>
<!-- Content here -->
<!-- Alternative: early in body -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Your Brand"
}
</script>
</body>
</html>
Placement Guidelines:
- Best: In
<head> section (before content loads)
- Good: Early in
<body> (after opening body tag)
- Acceptable: Within content where it makes sense contextually
- Avoid: Multiple unrelated schemas in same script block
- Critical: Ensure JSON-LD loads before page render completes
Practice 9: Multiple Schema Types Properly
Combine multiple schema types correctly.
Option 1: Separate Script Blocks:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Article Title",
"author": {...},
"datePublished": "2026-03-17"
}
</script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [...]
}
</script>
Option 2: Single Block with Array:
<script type="application/ld+json">
[
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Article Title"
},
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [...]
}
]
</script>
Best Practice:
- Use separate script blocks for clarity
- Group related schemas together
- Avoid duplicate information across schemas
- Test each schema type independently
Practice 10: Data Accuracy and Freshness
Ensure JSON-LD data is accurate and current.
Accuracy Guidelines:
- Match Content: Schema data must match visible page content
- Real Information: No fake or misleading data
- Complete Profiles: Fill all available properties accurately
- Update Regularly: Keep data current as content changes
Freshness Considerations:
- Update
dateModified when content changes
- Refresh pricing/availability in Offer schemas
- Add new reviews to Review schemas
- Update author information as needed
- Modify product descriptions when features change
