# 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.

{% embed url="<https://json-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 →](/novel-web/requests.md)

You can also check the stable API Reference here

{% embed url="<https://docs.novel.dev/novel-server/novel-api/api-reference>" %}

## Route Schemas

Novel automatically picks up a `schema.json`inside 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.&#x20;

{% embed url="<https://fastify.dev/docs/latest/Reference/Validation-and-Serialization/>" %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

## Changelog

* 2024-12-20 - Initial Documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.novel.dev/novel-server/routing/schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.