Folders

API Reference: Folders

Folders are a central organizational concept in FoxNose, designed to help you structure and manage your content efficiently. Think of folders as enhanced database tables that can be nested and support multiple content types. Unlike traditional systems, FoxNose folders can contain different types of data while maintaining clear organization and access controls.

FoxNose offers two distinct folder types, each optimized for different use cases:

Composite folders - Flexible containers for mixed content types
Collection folders - Structured containers with enforced data models

Understanding the differences between these folder types will help you choose the right approach for your specific needs.

Composite Folders

Composite folders are designed for flexibility and variety. They allow you to store different types of content together, each with its own structure and purpose.

Key Characteristics

Mixed Content Types: Store documents, forms, pages, and components together
Flexible Schemas: Each resource can have a different structure
Nested Schemas: Components can reference and inherit from other components
Moderate Scale: Best suited for small to medium-sized datasets

Nested Schemas

One of the most powerful features of composite folders is nested schemas. This allows you to create reusable components that other components can reference, eliminating duplicate field definitions:

📁 Components
├── 📄 Contact Form (name, email, phone, message)
├── 📄 Seo Data (title, description, keywords, og_image)
└── 📄 Landing Page → References: Contact Form + Seo Data
    ├── Hero Section (headline, subtitle, cta_button)
    ├── Contact Form (nested: name, email, phone, message)
    └── SEO Data (nested: title, description, keywords, og_image)

When you save the Landing Page, FoxNose validates against the complete merged schema, ensuring all nested fields are properly structured.

When to Use Composite Folders

Composite folders work best when you need:

Diverse Content: Mixing different types of content (pages, forms, components)
Flexible Structure: Different resources need different fields and formats
Component Reuse: Common elements shared across multiple resources
Rapid Development: Quick iteration without strict schema constraints

Collection Folders

Collection folders are designed for consistency and scale. They enforce a single data model across all resources, ensuring uniformity and enabling powerful search capabilities.

Key Characteristics

Uniform Structure: All resources follow the same data model
Strict Hierarchy: Collection folders can only contain other collection folders
Advanced Search: Full query syntax with joins and complex filtering
Scalable: Optimized for large datasets and complex relationships

When to Use Collection Folders

Collection folders are ideal for:

Large Datasets: Hundreds or thousands of similar records
Consistent Structure: All resources share the same fields and format
Complex Queries: Need to search and filter across multiple related collections
Business Processes: Managing workflows, applications, and structured business data

Strict Referencing System

Collections support a strict reference system that creates dependency relationships between resources. This is particularly useful when certain data cannot exist independently and must be owned by a parent resource.

Example 1: Beauty Salon Appointments

Managing appointment scheduling where time slots must belong to specific specialists and cannot exist independently. Time slots are meaningless without being assigned to a specific specialist.

📁 Specialists
├── 📄 Maria
├── 📄 Anna
└── 📁 Slots
    ├── 📄 10:00 Available (belongs to Maria)
    ├── 📄 11:00 Booked - Haircut (belongs to Maria)
    ├── 📄 14:30 Booked - Hair Color (belongs to Maria)
    ├── 📄 15:00 Available (belongs to Anna)
    └── 📄 16:00 Booked - Manicure (belongs to Anna)

Example 2: Medical Center Consultations

Organizing medical appointments where consultation slots are tied to specific doctors and their specializations. Medical consultations must belong to a particular doctor.

📁 Doctors
├── 📄 Dr. Smith
├── 📄 Dr. Johnson
└── 📁 Appointments
    ├── 📄 Mon 9:00 - Heart Checkup (belongs to Dr. Smith)
    ├── 📄 Mon 11:00 - Cardiac Screening (belongs to Dr. Smith)
    └── 📄 Tue 15:00 - Skin Analysis (belongs to Dr. Johnson)

Example 3: Online Learning Platform

Structuring educational content where lessons and assignments must belong to specific courses and cannot exist without their parent course context. Course materials only make sense within their specific course context.

📁 Courses
├── 📄 JavaScript Basics
├── 📄 Advanced React
└── 📁 Lessons
    ├── 📄 Variables & Functions (belongs to JavaScript Basics)
    ├── 📄 DOM Manipulation (belongs to JavaScript Basics)
    ├── 📄 Component Architecture (belongs to Advanced React)
    └── 📄 State Management (belongs to Advanced React)

In these examples:

Deleting the parent automatically handles dependent resources
API endpoints reflect the ownership: /specialists/TnMHhM4QTDeu/slots/aooxoscltikj

The strict referencing ensures data integrity for business processes where relationships are critical and prevents orphaned data that doesn't make sense without its parent context.

When to Use Each Folder Type

Understanding when to use each folder type becomes clearer with practical examples that show both approaches:

Choosing the Right Folder Type

Use Case	Composite Folders	Collection Folders
Website Components	✅ Different layouts and structures	❌ Too restrictive
Configuration Files	✅ Each config has unique structure	✅ Multiple entities with same config structure
Interface Translations	✅ Different sections, shared terms	❌ Too much structural variety
Custom Fields Management	❌ Inconsistent field structure	✅ Standardized field definitions
Landing Pages	✅ Flexible layouts	❌ Each page is unique
Support Tickets	❌ Inconsistent tracking	✅ Standard process needed
Product Catalog	❌ Hard to search/filter	✅ Complex attributes and filtering
Online Learning	❌ Inconsistent course structure	✅ Standardized lesson management
Project Management	❌ Varied project types	✅ Consistent tracking and reporting

Key Decision Factors:

Choose Composite Folders: When you need flexibility, varied structures, and component reuse
Choose Collection Folders: When you need consistency, scalability, and advanced search capabilities
The choice depends on whether you prioritize adaptability (composites) or standardization (collections)

Example 1: Configuration Management

Use Composite Folders when storing global application settings where each configuration type has different structure and requirements.

📁 App Config (Composite)
├── 📄 Database Config (host, port, credentials, pool_size)
├── 📄 API Config (endpoints, rate_limits, timeout)
├── 📄 Email Config → References: Server Settings
│   ├── SMTP Settings (nested: host, port, encryption)
│   └── Templates (welcome_template, reset_template)
└── 📄 UI Config (theme, layout, feature_flags)

Use Collection Folders when managing individual user configurations that follow the same structure pattern.

📁 User Settings (Collection: UserConfig Model)
├── 📄 User john_doe (theme: dark, language: en, notifications: true)
├── 📄 User jane_smith (theme: light, language: es, notifications: false)
└── 📄 User alex_chen (theme: auto, language: zh, notifications: true)

Example 2: Interface Translations

Use Composite Folders when managing application translations where different sections need different terms but share common vocabulary.

📁 App Translations (Composite)
├── 📄 Common Terms (save, cancel, delete, confirm)
├── 📄 Navigation Menu → References: Common Terms
│   ├── Menu Items (home, about, contact)
│   └── Actions (nested: save, cancel from Common Terms)
├── 📄 User Dashboard (welcome_message, stats_labels)
└── 📄 Error Messages (validation_errors, system_errors)

Example 3: Custom Field Management

Use Collection Folders when managing custom fields for entities like clients, projects, or products where each field follows the same structure but can have different types and configurations.

📁 Projects (Collection: Project Model)
├── 📄 Project Alpha
├── 📄 Project Beta
└── 📁 Custom Field Sets (Collection: FieldSet Model)
    ├── 📄 Alpha Field Set (belongs to Project Alpha)
    ├── 📄 Beta Field Set (belongs to Project Beta)
    └── 📁 Field Values (Collection: FieldValue Model)
        ├── 📄 Alpha Field Set Values
        └── 📄 Beta Field Set Values

This approach solves a common problem in relational databases where adding custom fields to existing entities is complex and inflexible. With collections, you can easily define field schemas using "one of" patterns for different field types while maintaining consistency across three levels of dependent data.

Example 4: Website Components

Use Composite Folders when managing reusable interface components with varying structures that share common elements.

📁 Components (Composite)
├── 📄 Contact Form (name, email, phone, message)
├── 📄 Seo Data (title, description, keywords, og_image)
└── 📄 Landing Page → References: Contact Form + Seo Data
    ├── Hero Section (headline, subtitle, cta_button)
    ├── Contact Form (nested: name, email, phone, message)
    └── SEO Data (nested: title, description, keywords, og_image)

Search and Filtering Capabilities

Both folder types support search operations, but with different capabilities:

Feature	Composite Folders	Collection Folders
Basic Filtering	✅ Standard field-based filters	✅ Standard field-based filters
Full-Text Search	✅ Search across all content	✅ Search across all content
Advanced Queries	❌ Limited to basic operations	✅ Complex conditions and operators
Join Operations	❌ Cannot combine multiple folders	✅ Combine data from related collections
Component Specification	⚠️ Must specify component type	✅ Uniform structure, no specification needed
Relationship Queries	⚠️ Only through reference fields	✅ Search based on strict references

Key Takeaways:

Composite folders are great for basic search within varied content types
Collection folders excel at complex queries across structured, related data
Choose collections when you need advanced search capabilities and structured data relationships