Skip to main content

Interfaces

Interfaces provide reusable field configurations that can be shared across multiple collections in TrackVision AI. They ensure consistency, reduce duplication, and simplify maintenance of common field patterns.

What are Interfaces?​

An interface is a predefined set of fields with their configurations that can be applied to multiple collections. When you apply an interface to a collection, all the fields from that interface are automatically added to the collection with their specified properties and validation rules.

System Interfaces​

TrackVision AI includes several built-in interfaces that provide standard functionality across collections.

User Created​

Tracks which user created each item and when it was created.

Fields:

  • user_created: Reference to the creating user (UUID)
  • date_created: Timestamp of creation (DateTime)

Usage:

{
  "collection": "products",
  "interfaces": ["user_created"]
}

User Updated​

Tracks which user last modified each item and when.

Fields:

  • user_updated: Reference to the last updating user (UUID)
  • date_updated: Timestamp of last modification (DateTime)

Usage:

{
  "collection": "products", 
  "interfaces": ["user_updated"]
}

Sort​

Enables manual ordering of collection items.

Fields:

  • sort: Integer field for custom sorting (Integer)

Usage:

{
  "collection": "menu_items",
  "interfaces": ["sort"]
}

Archive​

Provides soft deletion functionality without permanently removing data.

Fields:

  • status: Item status - published, draft, archived (String)
  • archived: Boolean flag for archived state (Boolean)

Usage:

{
  "collection": "articles",
  "interfaces": ["archive"]
}

Custom Interfaces​

Create your own interfaces for common field patterns used across multiple collections.

Address Interface​

Reusable address fields for locations, contacts, and shipping.

{
  "name": "address",
  "description": "Standard address fields",
  "fields": [
    {
      "field": "street_address",
      "type": "string",
      "required": true,
      "width": "full"
    },
    {
      "field": "city",
      "type": "string", 
      "required": true,
      "width": "half"
    },
    {
      "field": "state_province",
      "type": "string",
      "width": "quarter"
    },
    {
      "field": "postal_code",
      "type": "string",
      "width": "quarter"
    },
    {
      "field": "country",
      "type": "string",
      "required": true,
      "default_value": "US",
      "width": "half"
    }
  ]
}

Contact Information Interface​

Common contact fields for people and organizations.

{
  "name": "contact_info",
  "description": "Standard contact information fields",
  "fields": [
    {
      "field": "email",
      "type": "string",
      "validation": {
        "format": "email"
      },
      "width": "half"
    },
    {
      "field": "phone",
      "type": "string",
      "validation": {
        "format": "phone"
      },
      "width": "half"
    },
    {
      "field": "website",
      "type": "string",
      "validation": {
        "format": "url"
      },
      "width": "full"
    }
  ]
}

SEO Metadata Interface​

Search engine optimization fields for content collections.

{
  "name": "seo_meta",
  "description": "SEO metadata fields",
  "fields": [
    {
      "field": "meta_title",
      "type": "string",
      "note": "Recommended length: 50-60 characters",
      "validation": {
        "max_length": 60
      }
    },
    {
      "field": "meta_description", 
      "type": "text",
      "note": "Recommended length: 150-160 characters",
      "validation": {
        "max_length": 160
      }
    },
    {
      "field": "meta_keywords",
      "type": "string",
      "note": "Comma-separated keywords"
    },
    {
      "field": "canonical_url",
      "type": "string",
      "validation": {
        "format": "url"
      }
    }
  ]
}

Interface Management​

Creating Interfaces​

Interfaces can be created through:

  1. Admin Interface: Visual interface builder
  2. API Endpoints: REST or GraphQL mutations
  3. Configuration Files: JSON schema definitions
  4. Database Migrations: Programmatic creation

Applying Interfaces​

Apply interfaces to collections during creation or modification:

{
  "collection": "blog_posts",
  "interfaces": [
    "user_created",
    "user_updated", 
    "seo_meta",
    "archive"
  ],
  "fields": [
    {
      "field": "title",
      "type": "string",
      "required": true
    },
    {
      "field": "content",
      "type": "text",
      "required": true
    }
  ]
}

Updating Interfaces​

When you update an interface definition:

  • Changes propagate to all collections using that interface
  • Field additions are applied automatically
  • Field removals require manual confirmation
  • Type changes may require data migration

Interface Inheritance​

Multiple Interfaces​

Collections can implement multiple interfaces:

{
  "collection": "products",
  "interfaces": [
    "user_created",
    "user_updated",
    "sort",
    "archive",
    "seo_meta"
  ]
}

Interface Conflicts​

If multiple interfaces define the same field name:

  • Last applied interface takes precedence
  • Manual field definitions override interface fields
  • Validation rules are merged when compatible

Field Overrides​

Override interface field properties in collection definition:

{
  "collection": "products",
  "interfaces": ["address"],
  "fields": [
    {
      "field": "country",
      "default_value": "CA",
      "note": "Products ship from Canada"
    }
  ]
}

Best Practices​

Interface Design​

  1. Single Responsibility: Each interface should serve one clear purpose
  2. Logical Grouping: Group related fields together
  3. Naming Convention: Use descriptive, consistent names
  4. Documentation: Provide clear descriptions and usage examples

Field Configuration​

  1. Sensible Defaults: Provide reasonable default values
  2. Appropriate Validation: Include necessary validation rules
  3. User Experience: Consider field widths and grouping
  4. Performance: Avoid unnecessary complex field types

Maintenance​

  1. Version Control: Track interface changes over time
  2. Impact Analysis: Understand which collections use each interface
  3. Migration Planning: Plan data migrations for breaking changes
  4. Testing: Test interface changes across all using collections

Reusability​

  1. Generic Design: Make interfaces flexible for multiple use cases
  2. Optional Fields: Use required sparingly to maximize reusability
  3. Conditional Logic: Implement smart defaults and conditional requirements
  4. Documentation: Provide usage guidelines and examples

Migration Considerations​

When modifying interfaces that are already in use:

Safe Changes​

  • Adding optional fields
  • Updating field descriptions or notes
  • Adding validation rules (if data already complies)
  • Changing display properties (width, grouping)

Breaking Changes​

  • Removing fields
  • Changing field types
  • Adding required fields
  • Modifying validation rules

Migration Strategy​

  1. Assessment: Identify all collections using the interface
  2. Data Analysis: Check existing data compatibility
  3. Backup: Create data backups before changes
  4. Gradual Rollout: Apply changes incrementally
  5. Validation: Verify data integrity after migration