List schemas

By default when you create an item in a list, you can add any JSON data you like. However, let's say you want to enforce a specific structure on the data that is stored in a list. This is where list schemas come in.

You can add a JSON Schema when creating or updating a list.

Note that list schemas are only enforced when creating or updating an item, so they won't retroactively apply to existing items in the list.

If you've got a list containing items and then you add a schema to the list, some of those items might not conform to the schema. This is fine, but as soon as you add a new item or try to update one of the existing items, you'll need to make sure it conforms to the schema.

Here's an example of creating a list with a schema attached:

12345678910111213141516

curl https://api.jsonpad.io/lists \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "name": "List with a schema",
        "description": "This list has a JSON schema attached",
        "pathName": "list-with-schema",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "number" }
          },
          "required": ["name"]
        }
      }'

Now if we try to create an item in the list:

123456789

curl https://api.jsonpad.io/lists/list-with-schema/items \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "name": "John Doe",
          "age": 30
        }
      }'

{id: "eb69f805-fc68-4c60-aeee-4f045b943e24"
createdAt: "2026-09-05T11:29:15.865Z"
updatedAt: "2026-09-05T11:29:15.865Z"
data: {age: 30
name: "John Doe"
}
version: "1"
readonly: false
activated: false
description: ""
size: 28
locked: false
}

This worked! The item conforms to the schema we set on the list. Let's try another one:

12345678

curl https://api.jsonpad.io/lists/list-with-schema/items \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "age": 30
        }
      }'

{name: "VALIDATION_ERROR"
code: 10003
message: "Validation error (requires property \"name\")"
}

This time we received a 400 Bad Request response because the item doesn't conform to the schema.

The response contains further information about what went wrong.

Schemas can be very useful when combined with Indexes since we can make sure that every item in a list contains specific fields, and then we can query the items based on that structure.

2024-11-12