fields.md

Fields

Fields define the shape of your resource data. Each field has a name, a type, and optional properties that control validation, sorting, search, and automatic value generation.

Field Types

Snaapi supports 10 field types:

Type	Description	When to use
string	Short text value (up to database column limit)	Titles, names, slugs, email addresses
number	Numeric value (integer or floating-point)	Prices, counts, ratings, quantities
boolean	true or false	Flags like "in stock", "published", "verified"
json	Arbitrary JSON object or array	Metadata, settings, or flexible structured data
datetime	ISO 8601 date-time string	Event dates, deadlines, scheduled times
timestamp	Unix timestamp (numeric)	Unix-style timestamps for system interop
uuid	UUID v4 string	External IDs or references not managed by Snaapi
text	Long-form text (unlimited length)	Blog post bodies, descriptions, comments
enum	One of a predefined set of string values	Statuses, categories, roles, or any fixed choices
relation	Foreign key reference to another resource	Linking resources together (see Relations)

Enum Fields

Enum fields must include an enumValues array listing every allowed value:

{
  "name": "status",
  "type": "enum",
  "enumValues": ["draft", "published", "archived"]
}

Relation Fields

Relation fields must include a relations object specifying the target resource, field, and relation type. See the Relations documentation for details.

Field Properties

Properties control how a field behaves within a resource:

Property	Type	Default	Description
required	boolean	false	Whether the field must be provided on create
sortable	boolean	false	Whether the field can be used in sort operations
searchable	boolean	false	Whether the field is included in full-text search
unique	boolean	false	Whether values must be unique across all records
defaultValue	any	—	Value used when the field is omitted on create

Additional optional metadata:

• description — Human-readable description (up to 500 characters)
• displayName — Label for UI rendering (up to 200 characters)
• contentType — Semantic hint for UI and data generation (see Content Types)

Validation Rules

You can attach validation rules to string and number fields via the validations array. Each rule is checked at write time.

String Validations

Rule	Parameters	Description
minLength	value (number)	Minimum character count
maxLength	value (number)	Maximum character count
regex	pattern, optional flags	Must match the regular expression
email	—	Must be a valid email address
url	—	Must be a valid URL
startsWith	value (string)	Must start with the given prefix
endsWith	value (string)	Must end with the given suffix
includes	value (string)	Must contain the given substring

Number Validations

Rule	Parameters	Description
minValue	value (number)	Minimum allowed value (inclusive)
maxValue	value (number)	Maximum allowed value (inclusive)
integer	—	Must be a whole number

Example

{
  "name": "username",
  "type": "string",
  "required": true,
  "unique": true,
  "validations": [
    { "rule": "minLength", "value": 3 },
    { "rule": "maxLength", "value": 30 },
    { "rule": "regex", "pattern": "^[a-zA-Z0-9_]+$" }
  ]
}

Generation Transforms

A field can be automatically generated from another field at write time using the generatedFrom configuration. This is useful for deriving slugs, normalized values, or prefixed identifiers.

Transform	Description
slug	Converts the source value to a URL-friendly slug
lowercase	Converts the source value to lowercase
uppercase	Converts the source value to uppercase
trim	Removes leading and trailing whitespace
prefix	Prepends a fixed string (set via prefix option)
suffix	Appends a fixed string (set via suffix option)

Configuration

{
  "name": "slug",
  "type": "string",
  "generatedFrom": {
    "sourceField": "title",
    "transform": "slug"
  }
}

The sourceField must reference another field in the same resource. The optional prefix and suffix strings (up to 200 characters each) are applied after the transform.

Worked Example: Putting It All Together

The following resource definition for an articles resource demonstrates fields with validations, generation transforms, content types, and various field properties working together:

{
  "name": "articles",
  "description": "Editorial articles with auto-generated slugs",
  "fields": [
    {
      "name": "title",
      "type": "string",
      "required": true,
      "searchable": true,
      "sortable": true,
      "displayName": "Article Title",
      "description": "The headline displayed to readers",
      "validations": [
        { "rule": "minLength", "value": 5 },
        { "rule": "maxLength", "value": 200 }
      ]
    },
    {
      "name": "slug",
      "type": "string",
      "unique": true,
      "sortable": true,
      "generatedFrom": {
        "sourceField": "title",
        "transform": "slug"
      }
    },
    {
      "name": "body",
      "type": "text",
      "required": true,
      "searchable": true,
      "contentType": "richtext",
      "description": "Full article content in rich text"
    },
    {
      "name": "excerpt",
      "type": "string",
      "description": "Short summary shown in listings",
      "validations": [
        { "rule": "maxLength", "value": 300 }
      ]
    },
    {
      "name": "cover_image",
      "type": "string",
      "contentType": "image",
      "validations": [
        { "rule": "url" }
      ]
    },
    {
      "name": "status",
      "type": "enum",
      "enumValues": ["draft", "in_review", "published", "archived"],
      "defaultValue": "draft",
      "sortable": true
    },
    {
      "name": "read_time_minutes",
      "type": "number",
      "description": "Estimated reading time",
      "validations": [
        { "rule": "integer" },
        { "rule": "minValue", "value": 1 }
      ]
    },
    {
      "name": "featured",
      "type": "boolean",
      "defaultValue": false,
      "sortable": true,
      "description": "Whether this article appears on the homepage"
    },
    {
      "name": "author_id",
      "type": "relation",
      "required": true,
      "relations": {
        "resource": "users",
        "field": "id",
        "type": "many-to-one"
      }
    }
  ]
}

This single resource uses:

• Validations on title (length limits), excerpt (max length), cover_image (URL format), and read_time_minutes (integer, minimum value).
• Generation transforms to auto-create a URL-friendly slug from the title.
• Content types on body (richtext) and cover_image (image) so the Admin Console renders the right editor widgets.
• Field properties including required, unique, searchable, sortable, and defaultValue across different fields.
• A relation linking each article to its author via many-to-one.