api.visionapi.vision
Home
Documentation
Resources & Relationships
Resource Fields

Resource Fields

Learn how to define fields for your api.vision resources, including types, validations, and special features.

Field Basics

Each resource in api.vision consists of a collection of fields. Fields define the structure and constraints of your data.

Field Definition

A typical field definition includes:

{
  "resources": {
    "users": {
      "fields": {
        "id": { "type": "id" },
        "username": { 
          "type": "string", 
          "required": true,
          "unique": true,
          "minLength": 3,
          "maxLength": 20
        },
        "email": { 
          "type": "string", 
          "format": "email", 
          "required": true 
        },
        "age": { 
          "type": "integer", 
          "minimum": 13, 
          "default": 18 
        },
        "role": { 
          "type": "string", 
          "enum": ["user", "admin", "editor"], 
          "default": "user" 
        },
        "createdAt": { 
          "type": "datetime", 
          "readOnly": true 
        }
      }
    }
  }
}

Field Types

api.vision supports a wide range of field types:

TypeDescriptionExample
idPrimary identifier for the resource"id": { "type": "id" }
stringText value"name": { "type": "string" }
integerWhole number"age": { "type": "integer" }
numberFloating-point number"price": { "type": "number" }
booleanTrue/false value"active": { "type": "boolean" }
dateDate only (without time)"birthDate": { "type": "date" }
datetimeDate and time"createdAt": { "type": "datetime" }
timeTime only (without date)"openingTime": { "type": "time" }
arrayList of values"tags": { "type": "array", "items": { "type": "string" } }
objectNested object"address": { "type": "object", "properties": { "street": { "type": "string" } } }
relationRelationship to another resource"author": { "type": "relation", "resource": "users" }
fileFile reference"avatar": { "type": "file" }
uuidUUID string"externalId": { "type": "uuid" }
enumValue from a predefined set"status": { "type": "string", "enum": ["active", "inactive"] }

Field Attributes

Fields can have various attributes to define their behavior:

AttributeDescriptionExample
requiredWhether the field is required"required": true
defaultDefault value if none is provided"default": "user"
uniqueWhether the field must be unique across all resources"unique": true
readOnlyWhether the field can only be read, not written"readOnly": true
writeOnlyWhether the field can only be written, not read (like passwords)"writeOnly": true
nullableWhether the field can be null"nullable": true
descriptionHuman-readable description of the field"description": "User's email address"
exampleExample value for the field"example": "john@example.com"

Type-Specific Validations

Different field types support specific validation attributes:

String Validations

AttributeDescriptionExample
minLengthMinimum string length"minLength": 3
maxLengthMaximum string length"maxLength": 20
patternRegular expression pattern"pattern": "^[a-z0-9]+$"
formatPredefined format validation"format": "email"
enumList of allowed values"enum": ["admin", "user", "guest"]

Number and Integer Validations

AttributeDescriptionExample
minimumMinimum value"minimum": 0
maximumMaximum value"maximum": 100
exclusiveMinimumValue must be greater than (not equal to) minimum"exclusiveMinimum": true
exclusiveMaximumValue must be less than (not equal to) maximum"exclusiveMaximum": true
multipleOfValue must be a multiple of this number"multipleOf": 5

Array Validations

AttributeDescriptionExample
itemsSchema for array items "items": { "type": "string" }
minItemsMinimum number of items"minItems": 1
maxItemsMaximum number of items"maxItems": 10
uniqueItemsWhether items must be unique"uniqueItems": true

Object Validations

AttributeDescriptionExample
propertiesSchema for object properties"properties": { "street": { "type": "string" } }
requiredList of required properties"required": ["street", "city"]
additionalPropertiesWhether additional properties are allowed"additionalProperties": false

Special Field Features

Computed Fields

Define fields that are calculated based on other fields:

"fullName": {
  "type": "string",
  "computed": true,
  "expression": "firstName + ' ' + lastName"
}

Auto-Generated Values

Configure fields to be automatically generated:

"slug": {
  "type": "string",
  "generator": "slug",
  "source": "title"
}

"createdAt": {
  "type": "datetime",
  "generator": "timestamp",
  "readOnly": true
}

"uuid": {
  "type": "uuid",
  "generator": "uuid"
}

Custom Validators

Add custom validation logic:

"password": {
  "type": "string",
  "writeOnly": true,
  "validator": {
    "name": "password",
    "options": {
      "minLength": 8,
      "requireNumbers": true,
      "requireSpecialChars": true
    }
  }
}

Field Transformers

Automatically transform field values:

"email": {
  "type": "string",
  "format": "email",
  "transform": "lowercase"
}

"title": {
  "type": "string",
  "transform": "trim"
}

Comprehensive Example

Here's a more complex example showing various field features:

{
  "resources": {
    "products": {
      "fields": {
        "id": { 
          "type": "id" 
        },
        "sku": { 
          "type": "string", 
          "required": true, 
          "unique": true,
          "pattern": "^[A-Z]{2}\d{6}$",
          "description": "Product SKU in format XX000000"
        },
        "name": { 
          "type": "string", 
          "required": true, 
          "minLength": 3,
          "maxLength": 100
        },
        "slug": {
          "type": "string",
          "generator": "slug",
          "source": "name",
          "unique": true
        },
        "description": { 
          "type": "string", 
          "nullable": true 
        },
        "price": { 
          "type": "number", 
          "required": true,
          "minimum": 0,
          "exclusiveMinimum": true
        },
        "images": { 
          "type": "array", 
          "items": { "type": "string", "format": "uri" },
          "minItems": 1,
          "maxItems": 10
        },
        "categories": {
          "type": "relation",
          "resource": "categories",
          "relation": "belongsToMany"
        },
        "specs": { 
          "type": "object", 
          "properties": {
            "weight": { "type": "number" },
            "dimensions": {
              "type": "object",
              "properties": {
                "width": { "type": "number" },
                "height": { "type": "number" },
                "depth": { "type": "number" }
              }
            },
            "color": { "type": "string" }
          }
        },
        "inStock": { 
          "type": "boolean", 
          "default": true 
        },
        "stockQuantity": { 
          "type": "integer", 
          "minimum": 0,
          "default": 0
        },
        "status": { 
          "type": "string", 
          "enum": ["draft", "published", "archived"], 
          "default": "draft" 
        },
        "tags": { 
          "type": "array", 
          "items": { "type": "string" },
          "uniqueItems": true
        },
        "createdAt": { 
          "type": "datetime", 
          "readOnly": true,
          "generator": "timestamp"
        },
        "updatedAt": { 
          "type": "datetime", 
          "readOnly": true,
          "generator": "timestamp",
          "onUpdate": true
        }
      }
    }
  }
}

Best Practices

  • Define clear, consistent field types across related resources
  • Use appropriate validations to ensure data integrity
  • Add descriptions to fields to improve documentation
  • Use computed fields for values that can be derived
  • Apply sensible defaults where appropriate
  • Mark sensitive fields as writeOnly to prevent exposure
  • Use field transformers to ensure consistent data formatting
Previous
Defining Resources
Next
Relationships