Organizing Content with Collections

In FoxNose, a Collection is more than just a directory—it's the blueprint for your data model and, automatically, for your API. Getting the collection structure right is the key to a scalable and maintainable project, as it solves several common problems up front:

• API Design: A collection's alias directly becomes a segment in your API URL, making your API structure a clean reflection of your data model.
• Data Scoping: Collections live inside a single Environment, so you can safely manage production data separately from staging or development.
• Content Structure: Collections give your content a single, consistent schema for predictable data. Collections can also embed Components as nested fields when you need reusable content blocks within a single resource.
• Data Integrity: Nesting collections can enforce parent-child relationships, preventing orphaned data and simplifying queries for related content.

The content stored within these collections can then be seamlessly delivered via the Flux API, allowing you to expose different collections through various APIs to suit your application's needs.

Collections: For Predictable Data Lists

• The Job: You need to manage a list of items that all have the same, predictable structure (e.g., blog posts, products, users). You value consistency and easy querying of uniform data.
• Rule of thumb: Define a schema that captures the fields every resource in the collection must have.
• How it works: A collection is tied to a single schema version. Every resource you add to it has the exact same fields, ensuring data consistency and simplifying data retrieval. You can still embed Components as nested fields where you need a reusable content block on a few resources.

Example: An "Articles" Collection

📁 Articles (alias: articles)
├── Schema Version v1
│   ├── title (string, required)
│   ├── summary (text, vectorizable)
│   └── author (reference → People)
├── 📄 article-1
├── 📄 article-2
└── 📄 article-3

In this example:

• Every article resource follows the same defined schema.
• References (e.g., author) can connect to other collections, enabling powerful joins and population in Flux API searches.
• You can evolve the schema over time by publishing new versions, ensuring backward compatibility.

Modeling Collection Relationships

Once you have your basic collections, you'll need to connect them. FoxNose provides two primary ways to model relationships, each solving a different problem:

• Nested Collections with strict_reference: Use this for compositional ownership, when one object cannot exist without its parent (like comments belonging to a post). This approach guarantees data integrity (no orphaned data) and automatically creates clean, hierarchical API URLs.
• Reference Fields: Use this for many-to-many or shared relationships, where you want to link to a shared entity from multiple places (like an author who writes many posts). This is done by adding a reference field to your schema.

For a deep dive into modeling dependent data and leveraging strict_reference for hierarchical APIs, refer to the Strict-Reference Modeling guide.

Strategic Collection Design

Making the right collection choices early on prevents future headaches. Here are key recommendations:

• Start with the schema, not the API: Capture the fields every resource needs first. Add nested-component fields where you genuinely need a reusable content block; don't over-decompose.
• Nesting for Ownership, References for Relationships:
  • When data must belong to a parent (e.g., employee to a company), use nested collections with strict_reference. This guarantees data integrity and clean API paths.
  • For many-to-many connections or linking to shared entities (e.g., tags, authors), use Reference Fields within your schemas. This avoids duplication and maintains flexibility.
• Build Data Model First, Connect to Flux Last: Focus on solidifying your collection structure, schemas, and relationships. Once your content model is robust, then connect your collections to a Flux API. This "schema-first" approach ensures your APIs are well-designed and stable.

Related Guides

• Management API – Collection endpoints → For creating, updating, and importing collections programmatically.
• Flux API – List Resources and Search → To deliver collection content.
• Quick Start → To see how collections, schemas, and Flux APIs come together in a new project.