Advanced JSON-LD Patterns
The @graph Pattern for Multi-Entity Pages
Single-page applications and complex pages benefit from representing multiple entities with relationships:
{
"@context": "https://schema.org",
"@graph": [
{
"@id": "https://example.com/#organization",
"@type": "Organization",
"name": "Company Name",
"url": "https://example.com"
},
{
"@id": "https://example.com/#website",
"@type": "WebSite",
"url": "https://example.com",
"publisher": { "@id": "https://example.com/#organization" }
},
{
"@id": "https://example.com/article-1",
"@type": "Article",
"publisher": { "@id": "https://example.com/#organization" },
"isPartOf": { "@id": "https://example.com/#website" },
"author": { "@id": "https://example.com/#author-jane" }
},
{
"@id": "https://example.com/#author-jane",
"@type": "Person",
"name": "Jane Smith",
"worksFor": { "@id": "https://example.com/#organization" }
}
]
}
Benefits for AI Agents:
- Centralized entity definitions reduce ambiguity
- @id references enable efficient entity resolution
- Clear relationships improve knowledge extraction
- Reduced duplication improves parsing accuracy
Context and Vocabulary Extensions
AI agents benefit from custom vocabularies that provide domain-specific context:
{
"@context": [
"https://schema.org",
{
"agent": "https://example.com/vocab/agent#",
"requiresAuth": { "@id": "agent:requiresAuth", "@type": "xsd:boolean" },
"rateLimit": { "@id": "agent:rateLimit", "@type": "xsd:integer" },
"processingTime": { "@id": "agent:processingTime", "@type": "xsd:duration" },
"capability": { "@id": "agent:capability", "@type": "xsd:string" }
}
],
"@type": "WebAPI",
"name": "Content Analysis API",
"agent:requiresAuth": true,
"agent:rateLimit": 1000,
"agent:processingTime": "PT2S",
"agent:capability": ["text-analysis", "sentiment-detection"]
}
Best Practices:
- Use @vocab for clean property names
- Define XSD data types for validation
- Document custom vocabularies publicly
- Maintain versioning for vocabulary evolution
Role-Based Multi-Typing
Entities often serve multiple roles simultaneously:
{
"@context": "https://schema.org",
"@type": ["SoftwareApplication", "EducationalApplication", "AIModel"],
"name": "Code Assistant Pro",
"applicationCategory": "DeveloperApplication",
"educationalLevel": "Beginner to Advanced",
"aiCapabilities": {
"@type": "PropertyValue",
"name": "AI Capabilities",
"value": ["code-generation", "debugging", "documentation"]
}
}
AI Agent Benefits:
- Multi-type recognition enables nuanced understanding
- Role detection improves content routing
- Capability assessment determines appropriate actions
Dynamic Data Representation
For frequently changing data, include freshness signals:
{
"@context": [
"https://schema.org",
{
"live": "https://example.com/vocab/live#",
"updateFrequency": "live:updateFrequency",
"lastUpdate": "live:lastUpdate",
"dataSource": "live:dataSource"
}
],
"@type": "FinancialProduct",
"name": "High-Yield Savings",
"interestRate": 4.5,
"live:updateFrequency": "daily",
"live:lastUpdate": "2026-03-19T10:30:00Z",
"live:dataSource": "live-api-banking-v2"
}
Temporal Validity Patterns:
{
"@context": [
"https://schema.org",
{
"validFrom": { "@id": "https://example.com/vocab#validFrom", "@type": "xsd:dateTime" },
"validThrough": { "@id": "https://example.com/vocab#validThrough", "@type": "xsd:dateTime" }
}
],
"@type": "Offer",
"price": 99.99,
"validFrom": "2026-01-01T00:00:00Z",
"validThrough": "2026-12-31T23:59:59Z",
"availability": "InStock"
}
