Translating business requirements into content models

TL;DR

• Extract content entities (nouns with their own identity and lifecycle) from business briefs before touching the content type builder.
• Map relationships (one-to-many, many-to-many) and translate them to reference fields before defining individual field types.
• Draw a clear boundary between editorial content (belongs in Contentstack) and transactional data (belongs in commerce or external systems).
• Validate models with real sample entries and API responses before committing to a schema.

A content model is only as good as the requirements it encodes. The gap between a stakeholder saying "we need to add gift sets to Veda" and a developer creating content types in Contentstack is where most modeling mistakes originate - not in field configuration, but in translation.

This lesson walks through a complete scenario: taking a real business brief, decomposing it into content entities, defining relationships, choosing field types, and arriving at a set of Contentstack content type definitions that both editors and developers can agree on.

The business brief

Here is the brief, paraphrased from the kind of document you receive at project kickoff:

"Veda wants to add gift sets to the site. A gift set bundles 2-4 products (e.g., a curated earring + necklace pairing). Each gift set has a name, description, hero image, and optional gift message. Gift sets should appear in the Digital Dawn and Charmed Revival product lines. The site needs to support English and Spanish."

That single paragraph contains content entities, relationship types, localization requirements, and implied constraints. Your job is to extract them systematically rather than jumping straight into the content type builder.

Step 1: identify the content entities

Read the brief again and underline the nouns that represent distinct, manageable things. Not UI components. Not page layouts. Things that have their own identity and lifecycle.

From this brief:

Notice what is not on this list: "Gift Set Landing Page" or "Gift Set Card." Those are presentation concerns. You might use a Page content type for layout composition, but the entities above are the content - the structured, reusable content that the CMS exists to manage.

Step 2: determine relationships

With entities identified, map how they connect. Ask: "Does entity A need to know about entity B? In which direction? Is it one-to-one, one-to-many, or many-to-many?"

In Contentstack, all of these translate to Reference fields. A Reference field on the Gift Set content type points to the Product content type (multiple). A Reference field on Gift Set points to the Product Line content type (multiple). See lesson 2.2.1 for details on how references work and when to use them vs modular blocks.

One relationship worth discussing: Gift Set-to-Product is many-to-many. The "Date Night Duo" gift set contains the Matrix Link Bracelet and the Data Drop Earrings. The same Matrix Link Bracelet could appear in multiple gift sets. In Contentstack, you model this by adding a Reference field on Gift Set that allows multiple entries of type Product.

Step 3: define field types for each entity

Now translate each entity into a concrete content type definition. Here is the Gift Set content type as an example:

{
  "content_type": {
    "title": "Gift Set",
    "uid": "gift_set",
    "schema": [
      {
        "display_name": "Gift Set Name",
        "uid": "title",
        "data_type": "text",
        "mandatory": true,
        "unique": true,
        "field_metadata": { "description": "e.g. Date Night Duo" }
      },
      {
        "display_name": "URL",
        "uid": "url",
        "data_type": "text",
        "mandatory": true,
        "field_metadata": { "description": "e.g. /gift-sets/date-night-duo" }
      },
      {
        "display_name": "Description",
        "uid": "description",
        "data_type": "json",
        "field_metadata": { "allow_json_rte": true }
      },
      {
        "display_name": "Hero Image",
        "uid": "image",
        "data_type": "file"
      },
      {
        "display_name": "Gift Message",
        "uid": "gift_message",
        "data_type": "text",
        "field_metadata": { "multiline": true, "description": "Optional message template" }
      },
      {
        "display_name": "Products",
        "uid": "products",
        "data_type": "reference",
        "reference_to": ["product"],
        "multiple": true,
        "mandatory": true
      },
      {
        "display_name": "Product Lines",
        "uid": "product_line",
        "data_type": "reference",
        "reference_to": ["product_line"],
        "multiple": true
      }
    ]
  }
}

Key decisions in this schema:

• title is unique and mandatory. Two gift sets should not share the same name, and every gift set must have one.
• url is mandatory for routing. Gift sets need their own URL path.
• description uses JSON Rich Text Editor for formatted content with headings, lists, and links.
• products is a mandatory multi-reference. A gift set without products is incomplete data.
• product_line links the gift set to the collections it appears in (Digital Dawn, Charmed Revival).

Step 4: decide what NOT to model

This step is as important as the previous three. The brief says "gift sets," and someone in the room will eventually ask: "Can we show real-time inventory? Can customers add gift sets to cart?"

Common pitfall: Adding transactional fields like in_stock or cart_quantity to content types creates data that editors cannot meaningfully manage and that changes based on commerce logic, not editorial decisions.

The answer is: inventory and cart belong in the commerce system. Contentstack manages content. Product availability, pricing, cart state, and checkout belong in external systems - Shopify, commercetools, or a custom commerce backend.

Draw a clear boundary:

This boundary prevents the content model from accumulating fields like in_stock or cart_quantity that editors cannot meaningfully manage and that change based on commerce logic, not editorial decisions. For integration patterns with external systems, see course 7.

Step 5: from whiteboard to Contentstack

The progression matters. Moving directly from a verbal brief to Contentstack's content type builder skips validation steps that catch problems early.

Phase 1 - Whiteboard sketch. Draw boxes for each entity with their fields listed inside. Draw arrows for relationships. This takes 30 minutes and saves days of rework.

Phase 2 - Spreadsheet or table. Formalize the sketch into a table: entity name, field name, field type, required/optional, relationship target. Share this with stakeholders for review.

Phase 3 - Content type creation in Contentstack. Navigate to Settings > Content Types in the Contentstack UI. Create each content type using the content type builder. Add fields using the field palette on the right. Configure field properties (mandatory, unique, description, validation) in the field settings panel.

Phase 4 - Sample entries. Create 2-3 entries per content type using real content, not "test" and "asdf." Real content exposes problems: is the bio field long enough? Does the enum list cover all degree types? Can editors actually assemble a complete program listing?

Phase 5 - API validation. Fetch entries through the Content Delivery API and confirm the JSON structure matches what the frontend team expects. This is where content types reveal themselves as API contracts (see lesson 2.1.2).

Stakeholder alignment

Getting editors and developers to agree on a content model requires shared vocabulary and concrete examples.

Editors care about: Can I find where to create this content? Are the field names clear? Is the entry form manageable (not 50 fields on one screen)? Can I preview what I am creating?

Developers care about: Is the API response predictable? Are references resolvable without excessive include depth? Are field UIDs consistent and programmatically friendly? Is content reusable across channels?

Both care about: Does this model support the site's actual requirements without over-engineering for hypothetical future needs?

A practical alignment technique: create the content types, then sit with an editor and watch them create three entries. Where they hesitate, the model has a usability problem. Where they ask "where does this go?", the model has a discoverability problem. Where they paste content from a Word document and it does not fit, the model has a structural problem.

Common mistakes

1. Modeling pages instead of content

Creating a "Gift Set Page" content type with fields like hero_banner, sidebar_cta, and footer_override mixes content with presentation. Model the Gift Set as content; handle page layout in your frontend or with a separate Page content type that references Gift Sets.

2. Skipping the relationship mapping step

Jumping to field definitions without mapping relationships produces content types that either duplicate data (copying department info into every program) or miss connections (no way to show which faculty teach a program).

3. Treating the content model as final

A content model is a living artifact. You will discover missing fields, unnecessary fields, and relationship gaps after editors start creating real content. Build with the expectation of iteration, not perfection.