cosmosdb-data-modeling

Azure Cosmos DB Data Modeling

Best practices for designing document schemas in Azure Cosmos DB, prioritized by impact.

When to Apply

Reference these guidelines when:

• Designing document schemas for Cosmos DB containers
• Deciding between embedding and referencing related data
• Handling polymorphic data in shared containers
• Planning schema evolution and versioning
• Configuring JSON serialization for Cosmos DB documents

Rules

• model-embed-related - Embed related data retrieved together
• model-reference-large - Reference data when items get too large
• model-avoid-2mb-limit - Keep items well under 2MB limit
• model-id-constraints - Follow ID value length and character constraints
• model-nesting-depth - Stay within 128-level nesting depth limit
• model-numeric-precision - Understand IEEE 754 numeric precision limits
• model-denormalize-reads - Denormalize for read-heavy workloads
• model-schema-versioning - Version your document schemas
• model-type-discriminator - Use type discriminators for polymorphic data
• model-json-serialization - Handle JSON serialization correctly
• model-relationship-references - Use ID references with transient hydration

Full Compiled Document

For all rules expanded: AGENTS.md