Collection Schemas

Optionally define schemas for your data collections to validate data on create and update operations.

Schemas are optional - if no schema is defined for a collection, data passes through without validation (backwards compatible).

Schema Format

A schema defines the structure and constraints for documents in a collection:

{
  "fields": {
    "title": {
      "type": "string",
      "required": true,
      "minLength": 1,
      "maxLength": 200
    },
    "status": {
      "type": "enum",
      "values": ["draft", "published", "archived"]
    },
    "views": {
      "type": "number",
      "min": 0
    },
    "featured": {
      "type": "boolean"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "author": { "type": "string" },
        "category": { "type": "string" }
      }
    }
  },
  "strict": false
}

Supported Field Types

Common Constraints

• required: true - Field must be present and non-null on create. Skipped for PATCH (partial updates).
• strict: true - (Schema-level) Reject unknown fields not defined in the schema.

API Endpoints

Schema endpoints are available for all storage types (team-data, solo-data, social-data, cms-data):

Example: Define a Schema

# Define schema for a tasks collection
curl -X PUT \
  -H "Authorization: Bearer vm_token" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "fields": {
        "title": { "type": "string", "required": true, "maxLength": 200 },
        "status": { "type": "enum", "values": ["todo", "in_progress", "done"] },
        "priority": { "type": "number", "min": 1, "max": 5 }
      }
    }
  }' \
  https://visimade.com/api/pages/123/team-data/tasks/schema

Client SDK Methods

All client SDKs (TeamData, SoloData, SocialData, CmsData) include schema management methods:

// Define a schema for a collection (page owner only)
await TeamData.defineSchema('tasks', {
  fields: {
    title: { type: 'string', required: true },
    status: { type: 'enum', values: ['todo', 'in_progress', 'done'] }
  }
});

// Get the schema for a collection
const schema = await TeamData.getSchema('tasks');
console.log(schema); // null if not defined

// Remove the schema (page owner only)
await TeamData.removeSchema('tasks');

Validation Errors

When validation fails, the API returns a 400 status with detailed error information:

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "validationErrors": [
    {
      "field": "title",
      "message": "Field is required",
      "code": "required"
    },
    {
      "field": "status",
      "message": "Value must be one of: todo, in_progress, done",
      "code": "enum"
    }
  ]
}

Error Codes

Note: Schemas are optional. If no schema is defined for a collection, data is accepted without validation. This ensures backwards compatibility - existing pages continue to work without changes.