Schema

Novel makes use of different schemas across the server and the frontend. It utilizes JSON Schema as well as Zod to enforce different ways of validation and shape.

JSON Schemajson-schema.org

OpenAPI

Novel uses OpenAPI to shape the requests as much as possible. The built-in routes will have described the input and output of each endpoint. This is useful for the web client as request files are generated automatically using the spec.

See Requests →

You can also check the stable API Reference here

API Reference | Noveldocs.novel.dev

Route Schemas

Novel automatically picks up a schema.jsoninside your route directories. If this exists, it will try to apply it to the route options and itwill be available to the automated openapi spec.

Example

• If you have /app/api/user-create/index.ts , adding a schema.json beside index.ts will automatically load it for that route.

Automatic Generation

The public API registered from /app/api is available under the docs endpoint.

https://localhost:7634/docs/openapi/json

Swagger UI

https://localhost:7634/docs/openapi

Scalar Documentation UI

https://localhost:7634/docs/reference

The admin API is also available from the /admin route prefix. Same UI are available under these.

http://localhost:7634/admin/docs/openapi/json

Validation / Serialization

Novel routes follow Fastify's validation and serialization strategy via AJV.

Validation-and-Serialization | Fastifyfastify.dev

When requests and responses do not follow the spec, a ValidationFailedError is thrown.

https://github.com/madewithnovel/novel/blob/main/packages/novel/errors/validation-failed.js

Models

You are able to reference a schema in your routes by using this shorthand when defining your route schema in Fastify

{
    ...
    "$ref": "https://novel.dev/entities/accounts#"
}

Changelog

• 2024-12-20 - Initial Documentation