Skip to content

Improve documentation about typed json and prisma-json-types-generator #6994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ The following is a list of community created generators.
- [`prisma-dbml-generator`](https://notiz.dev/blog/prisma-dbml-generator/): Transforms the Prisma schema into [Database Markup Language](https://dbml.dbdiagram.io/home/) (DBML) which allows for an easy visual representation
- [`prisma-docs-generator`](https://github.com/pantharshit00/prisma-docs-generator): Generates an individual API reference for Prisma Client
- [`prisma-json-schema-generator`](https://github.com/valentinpalkovic/prisma-json-schema-generator): Transforms the Prisma schema in [JSON schema](https://json-schema.org/)
- [`prisma-json-types-generator`](https://github.com/arthurfiorette/prisma-json-types-generator): Adds support for [Strongly Typed `Json`](https://github.com/arthurfiorette/prisma-json-types-generator#readme) fields for all databases. It goes on `prisma-client-js` output and changes the json fields to match the type you provide. Helping with code generators, intellisense and much more. All of that without affecting any runtime code.
- [`prisma-json-types-generator`](https://github.com/arthurfiorette/prisma-json-types-generator): Enhances `prisma-client-js` (or `prisma-client`) to provide strongly typed JSON fields for all databases, based on your schema. It improves code generation, Intellisense, and more, without affecting runtime code.
- [`typegraphql-prisma`](https://github.com/MichalLytek/typegraphql-prisma#readme): Generates [TypeGraphQL](https://typegraphql.com/) CRUD resolvers for Prisma models
- [`typegraphql-prisma-nestjs`](https://github.com/EndyKaufman/typegraphql-prisma-nestjs#readme): Fork of [`typegraphql-prisma`](https://github.com/MichalLytek/typegraphql-prisma), which also generates CRUD resolvers for Prisma models but for NestJS
- [`prisma-typegraphql-types-gen`](https://github.com/YassinEldeeb/prisma-tgql-types-gen): Generates [TypeGraphQL](https://typegraphql.com/) class types and enums from your prisma type definitions, the generated output can be edited without being overwritten by the next gen and has the ability to correct you when you mess up the types with your edits.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -976,46 +976,72 @@ These _null enums_ do not apply to MongoDB because MongoDB does not differentiat

</Admonition>

## Typed `Json`
## Typed `Json` Fields

By default, `Json` fields are not typed in Prisma models. To accomplish strong typing inside of these fields, you will need to use an external package like [prisma-json-types-generator](https://www.npmjs.com/package/prisma-json-types-generator) to accomplish this.
Prisma's `Json` fields are untyped by default. To add strong typing, you can use the external package [prisma-json-types-generator](https://www.npmjs.com/package/prisma-json-types-generator).

### Using `prisma-json-types-generator`
1. First, install the package and add the generator to your `schema.prisma`:

First, install and configure `prisma-json-types-generator` [according to the package's instructions](https://www.npmjs.com/package/prisma-json-types-generator#using-it).
```bash
npm install -D prisma-json-types-generator
```

Then, assuming you have a model like the following:
```prisma file=schema.prisma
generator client {
provider = "prisma-client-js"
}

```prisma no-copy
model Log {
id Int @id
meta Json
}
```
generator json {
provider = "prisma-json-types-generator"
}
```

You can update it and type it by using [abstract syntax tree comments](/orm/prisma-schema/overview#comments)
2. Next, link a field to a TypeScript type using an [AST comment](/orm/prisma-schema/overview#comments).

```prisma highlight=4;normal file=schema.prisma showLineNumbers
model Log {
id Int @id
```prisma highlight=4;normal file=schema.prisma showLineNumbers
model Log {
id Int @id

//highlight-next-line
/// [LogMetaType]
meta Json
}
```
//highlight-next-line
/// [LogMetaType]
meta Json
}
```

Then, make sure you define the above type in a type declaration file included in your `tsconfig.json`
3. Then, define `LogMetaType` in a type declaration file (e.g., `types.ts`) that is included in your `tsconfig.json`.

```ts file=types.ts showLineNumbers
declare global {
namespace PrismaJson {
type LogMetaType = { timestamp: number; host: string }
}
```ts file=types.ts showLineNumbers
declare global {
namespace PrismaJson {
type LogMetaType = { timestamp: number; host: string };
}
}

// This file must be a module.
export {};
```

Now, `Log.meta` will be strongly typed as `{ timestamp: number; host: string }`.

### Typing `String` Fields and Advanced Features

You can also apply these techniques to `String` fields. This is especially useful for creating string-based enums directly in your schema when your database does not support enum types.

```prisma
model Post {
id Int @id

/// !['draft' | 'published']
status String

/// [LogMetaType]
meta Json[]
}
```

Now, when working with `Log.meta` it will be strongly typed!
This results in `post.status` being strongly typed as `'draft' | 'published'` and `post.meta` as `LogMetaType[]`.

For a complete guide on configuration, monorepo setup, and other advanced features, please refer to the [official `prisma-json-types-generator` documentation](https://github.com/arthurfiorette/prisma-json-types-generator#readme).

## `Json` FAQs

Expand Down
Loading