If you have schemas for API pages that are repeated across multiple endpoints, you can use schema files to avoid duplication.

Schema files are Markdown files that define the schema for either a request body or a response body.

Creating a schema file

Inside the folder you have your API endpoints, add a /schemas folder. This is where you will store your schema files.

Schema file names can be anything as they're not used by the system, but it's recommended to use a descriptive name that matches the schema.

In the frontmatter, add an api.schema key with the name of the schema the file describes, in this case CreateUser. This is the name you reference in the endpoint page frontmatter.

In the file body, you define the schema for the request body or response body using a simple key-value format.

Here's an example of a simple schema file:

---
api:
  schema: User
---

email: string
name: string
role?: string

You can also reference other schemas inside schemas.

---
api:
  schema: Member
---

id: string
user: User

The schema here is the same as you would define in page frontmatter.

So you can add descriptions for each field:

---
api:
  schema: Member
---

id: string
  User ID (UUID)
user: User

or

---
api:
  schema: Member
---

id:
  type: string
  description: User ID (UUID)
user: User

Using a schema file

In your API endpoint frontmatter, you can reference schema files using a schema key.

Instead of defining the schema in the frontmatter, you reference the schema with the name you added in api.schema in the schema file.

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema:
            email: string
            name: string
            role?: string
          example:
            email: user@example.com
            name: Jane Doe
            role: member
---

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema: CreateUser
          example:
            email: user@example.com
            name: Jane Doe
            role: member
---

In responses, use schemas like this:

---
api:
  endpoint:
    get /v1/user/{userId}:
      params:
        query:
          userId: string
      responses:
        200:
          schema: User
---

To reference an array of objects in a response using schemas, you can do this:

---
api:
  endpoint:
    get /v1/users:
      responses:
        200:
          schema:
            users: User[]
---