Jazz Schema Design

Jazz Data Modelling and Schema Design

When to Use This Skill

• Designing data structures for Jazz applications
• Defining CoValue schemas and relationships
• Configuring permissions at the schema level
• Planning schema evolution and migrations
• Choosing between scalar and collaborative types
• Modeling relationships between data entities

Do NOT Use This Skill For

• Writing tests for Jazz applications (use the jazz-testing skill)
• General framework integration questions (use the jazz-ui-development skill)
• Permissions topics outside the schema. Use the jazz-permissions-security skill.

Key Heuristic for Agents: If the user is asking about how to structure their data model, define relationships, configure default permissions, or evolve schemas, use this skill.

Core Concepts

Jazz models data as an explicitly linked collaborative graph, not traditional tables or collections. Data types are defined as schemas, with CoValues serving as the fundamental building blocks.

Schema Definition Basics

Basic Structure

const Author = co.map({
  name: z.string()
});

const Post = co.map({
  title: z.string(),
  content: co.richText(),
});

Key Libraries:

• z.* - Zod schemas for primitive types (e.g., z.string())
• co.* - Jazz collaborative data types (e.g., co.richText(), co.map())

Permissions Model

Permissions are integral to the data model, not an afterthought. Each CoValue has an ownership group with hierarchical permissions.

Permission Levels (cumulative)

1. none - Cannot read content
2. reader - Can read content
3. writer - Can update content (overwrite values, modify lists)
4. admin - Can grant/revoke permissions plus all writer capabilities

Critical Permission Rules

• Only the creator is admin by default - no superuser concept
• Cannot change CoValue ownership group - must modify group membership instead
• Different permissions require separate containers - use distinct CoMaps/CoLists
• Nested CoValues inherit permissions from parent by default
• Define default permissions at schema level during design

Defining Permissions at Schema Level

Use withPermissions() to set automatic permissions when creating CoValues:

const Dog = co.map({
  name: z.string(),
}).withPermissions({
  onInlineCreate: "sameAsContainer",
});

const Person = co.map({
  pet: Dog,
}).withPermissions({
  default: () => Group.create().makePublic(),
});

// Person CoValues are public, Dog shares owner with Person
const person = Person.create({
  pet: { name: "Rex" }
});

Permission Configuration Options

default Defines group when calling .create() without explicit owner.

onInlineCreate Controls behavior when CoValue is created inline (NOT applied to .create() calls):

• "extendsContainer" (default) - New group includes container owner as member, inheriting permissions
• "sameAsContainer" - Reuse container's owner (performance optimization—see below for concerns and considerations)
• "newGroup" - New group with active account as admin
• { extendsContainer: "reader" } - Like "extendsContainer" but override container owner's role
• Custom callback - Create and configure new group as needed

onCreate Callback runs on every CoValue creation (both .create() and inline). Use to configure owner.

Global Permission Defaults

Set defaults for all schemas using setDefaultSchemaPermissions:

import { setDefaultSchemaPermissions } from "jazz-tools";

setDefaultSchemaPermissions({
  onInlineCreate: "sameAsContainer",  // Performance optimization
});

USE EXTREME CAUTION: If you use sameAsContainer, you MUST be aware that the child and parent groups are one and the same. Any changes to the child group will affect the parent group, and vice versa. This can lead to unexpected behavior if not handled carefully, where changing permissions on a child group inadvertently results in permissions being granted to the parent group and any other siblings created with the same parent. As ownership cannot be changed, you MUST NOT USE sameAsContainer if you AT ANY TIME IN FUTURE may wish to change permissions granularly on the child group.

CoValue Types

Use the special types co.account() and co.profile() for user accounts and profiles.

Choosing Scalar vs Collaborative Types

Scalar Types (Zod: z.*)

Use when:

• Full replacement updates expected
• No collaborative editing needed
• Single writer scenario
• Raw performance critical

Examples:

const myCoValue = co.map({
  title: z.string()        // Replace entire title, no collaboration needed
  coords: z.object({
    lat: z.number(),
    lon: z.number()
  })   // Replace entire object, no collaboration needed
});

Note: not all Zod types are available in Jazz. Be sure to always import { z } from 'jazz-tools';, and validate whether the type exists on the export. DO NOT import from zod.

Collaborative Types (Jazz: co.*)

Use when:

• Multiple users edit simultaneously
• Surgical/granular edits needed
• Full edit history tracking valuable
• Collaborative features required

Examples:

const myCoVal = co.map({
  content: co.richText()   // Multiple editors
  items: co.list(Item)     // Add/remove individual items
  config: co.map({
    settingA: z.boolean(),
    settingB: z.number()
  })       // Update specific keys
});

Trade-off: CoValues track full edit history. Slightly slower for single-writer full-replacement scenarios, but benefits almost always outweigh costs.

Relationship Modeling

One-Directional Reference

const Post = co.map({
  title: z.string(),
  author: Author  // One-way reference (like foreign key)
});

Jazz stores referenced ID. Use resolve queries to control reference traversal depth.