Collection field types

Each field on a collection version has a type. The type decides what a record stores under the field's slug, which settings the field takes, and what a write is refused for.

{
  "fields": [
    {
      "slug": "name",
      "title": "Name",
      "type": "text",
      "required": true,
      "max": 80
    },
    {
      "slug": "size",
      "title": "Size",
      "type": "select",
      "options": [
        { "value": "s", "label": "Small" },
        { "value": "m", "label": "Medium" }
      ]
    },
    {
      "slug": "seats",
      "title": "Seats",
      "type": "integer",
      "min": 1,
      "max": 500
    },
    { "slug": "budget", "title": "Budget", "type": "money", "currency": "usd" },
    { "slug": "office", "title": "Office", "type": "location" }
  ]
}

A record written against that version:

{
  "name": "Acme",
  "size": "m",
  "seats": 40,
  "budget": { "amount": 250000, "currency": "usd" },
  "office": { "address": { "city": "Berlin", "country": "DE" } }
}

The types

Note the name bool, not boolean. A type the version does not know is refused when the version is saved.

What every field has

The console offers a default value for text, rich text, number, checkbox, date, color, link and email fields. A choice, a whole number, money, a location and a file start empty.

Limits

The platform's ceilings, whatever a field says:

Text, email, link and color

min and max count characters. An email value must look like an email address, and a link value must start with http:// or https://.

pattern is a regular expression the whole value must match, on text, email, link and color fields. Two rules keep a pattern safe to run on what strangers send:

• A field with a pattern sets a max of 1,000 or less.
• A pattern that could take very long to test is refused when the version is saved: no backreference (\1), and no repeated group that itself repeats or holds a choice ((a+)+, (a|aa)*). [A-Z]{3}-\d+, (foo|bar) and (ab)+ are fine.

{
  "slug": "postcode",
  "title": "Postcode",
  "type": "text",
  "max": 10,
  "pattern": "[0-9]{5}"
}

Number and whole number

A string that reads as a number is stored as one: "5" is stored as 5. integer refuses anything that is not a whole number. min and max bound the value, and may be negative.

Checkbox and date

A bool field takes true or false, or the strings "true" and "false", and stores the boolean. A date field takes a date string ("2026-11-03" or a full ISO timestamp) and stores it as sent; a bare number is refused.

Choice and multiple choice

Both need options: 1 to 200 of them, each with a distinct value and a label. The record stores the value; the label is for people.

A multi-select value is a list of distinct option values. Its min and max count how many are picked.

{
  "slug": "tags",
  "title": "Tags",
  "type": "multi-select",
  "max": 3,
  "options": [
    { "value": "new", "label": "New" },
    { "value": "sale", "label": "On sale" }
  ]
}

{ "tags": ["new", "sale"] }

Money

A money value is { "amount": 1999, "currency": "usd" }: the amount in the currency's minor units (cents for US dollars, whole yen for yen), never negative, and a lower case ISO 4217 code for a currency in circulation.

A collection's money field must name its currency; saving a version with a money field and no currency is refused. A value in any other currency is refused, so every record of the field is in the same currency. min and max bound the amount, in minor units.

Location

A location is an address, a map point, or both:

{
  "office": {
    "address": {
      "line1": "Unter den Linden 1",
      "city": "Berlin",
      "postalCode": "10117",
      "country": "DE"
    },
    "point": { "lat": 52.517, "lng": 13.389 }
  }
}

The address takes any of line1, line2, city, state, postalCode and country, each a string of up to 200 characters. country is an ISO 3166 two-letter code and is stored upper case. point takes exactly lat (-90 to 90) and lng (-180 to 180). Any other key is refused.

File

A file field holds images as your assets, never the bytes. Its settings, what a record stores and how to write one are on the overview.

When a write is refused

A record written through the API is checked against its version's fields. The first problem answers 400 with the field and what is wrong:

{ "error": true, "message": "Seats must be at most 500" }

A public form submission answers every problem at once:

{
  "success": false,
  "message": "Validation failed",
  "errors": ["Seats must be at most 500", "Budget must be in USD"]
}

Keys that are not fields of the version are dropped, not refused. An empty value ("", null or []) on an edit clears the field.

Check values in your own app

The SDK runs the same checks, so a form can say what is wrong before it sends. The server checks again, and its answer counts.

import { checkFieldValues, type FieldDefinition } from '@buildbase/sdk';

export function checkOrder(
  fields: FieldDefinition[],
  data: Record<string, unknown>
) {
  const { values, errors } = checkFieldValues(fields, data);
  // errors: [{ slug: 'seats', code: 'too_large', message: '...' }]
  return errors.length ? { errors } : { values };
}

Each error has a code your app can put in its own words:

Next Steps

• Collections overview - versions, file fields and endpoints.
• Records API - read and delete stored records.
• Forms - collect records from a public endpoint.