Working with JSON Fields

1. Defining JSON Fields

metadata Json   @default("{}")
tags     Json?

await prisma.user.create({
  data: {
    email: "a@b.io",
    metadata: { plan: "pro", flags: ["beta"], score: 42 }
  }
});

Type	JSON.stringify
Object	Stored as JSON object
Array	Stored as JSON array
null	Use `Prisma.JsonNull` for JSON null, `Prisma.DbNull` for SQL NULL

Filter	Example
`path`	`{ metadata: { path: ["plan"], equals: "pro" } }`
`string_contains`	`{ metadata: { path: ["bio"], string_contains: "dev" } }`
`array_contains`	`{ metadata: { path: ["flags"], array_contains: "beta" } }`

await prisma.user.findMany({
  where: { metadata: { path: ["flags"], array_contains: ["beta", "alpha"] } }
});

Approach	Example
Path equals not null	`{ metadata: { path: ["plan"], not: Prisma.AnyNull } }`
Raw SQL	`WHERE metadata ? 'plan'` (PG)

await prisma.user.update({
  where: { id: 1 },
  data: { metadata: { plan: "enterprise", flags: ["beta", "neo"] } }
});

Warning: Prisma overwrites the entire JSON value. To merge keys, fetch existing JSON, spread, and write back, or use a raw jsonb_set SQL.

Pattern	Approach
Full replace	Pass new object
Partial update	Read–merge–write or raw `jsonb_set`

Tool	Use
Zod	Validate at API boundary
JSON Schema	Combine with Ajv for cross-language contracts
TS types	Declare `type Metadata = { plan: "free"\|"pro" }` and cast