Model Your Content: Metafields and Schema

Every API response you get out of Cosmic is shaped by decisions someone made in the content model. This lesson covers making those decisions deliberately: creating an object type, adding fields to it, connecting it to other content, and seeing exactly how each choice shows up in the JSON your site consumes.

This is dashboard work. No code, though the last step shows you the API response your changes produce.

---

Before You Start

• A Cosmic bucket you can edit

• Admin or developer access. Editors and contributors cannot change content models

• A desktop browser. The metafield editor is not available on mobile

---

What a Metafield Is

A metafield is one piece of information attached to a piece of content. A blog post has a title and a slug built in; everything else you want on it, an excerpt, a hero image, an author, a publish date, is a metafield you add.

Your content model is just the list of those fields and their types. Get it right and your API responses are clean and predictable. Get it wrong and you spend the next year working around it in your frontend.

---

Step 1: Create an Object Type

1. Open your bucket and click Objects in the top nav

2. In the sidebar, expand Object types and click Add Object Type

You will land on a three-step wizard: Basic settings, Content model, and Additional settings.

---

Step 2: Decide Multiple or Singleton

The first choice on Basic settings is between Multiple and Singleton, and it is the one people most often get wrong.

Choose Multiple when you will have many of the thing. Blog posts, products, team members, case studies. You get a list you can add to.

Choose Singleton when there is exactly one. A homepage, a global site settings record, an About page. Singletons cannot be duplicated, which is the point: nobody can accidentally create a second homepage.

Then fill in the rest:

The slug is what you will type in code as , so it is worth a moment's thought. It is awkward to change once a site depends on it.

Click Next.

---

Step 3: Add Metafields

You are now on Content model. Title and Slug already exist; everything else comes from the Add Metafield palette on the right.

There is no "add field" button. You click a type in the palette, or drag it into the drop zone, and it appears in your model.

The palette is grouped. The types you will use most:

For each field you add, set two things:

• Title is what editors see, so write it for them. "Hero image", not "img_1"

• Key is what appears in the API. It auto-fills from the title and you can override it

A few choices worth making on purpose:

Text Input vs Text Area. Text Input is one line, Text Area is many. Use Text Input for a meta description so nobody pastes six paragraphs into it.

Rich Text vs Markdown. Rich Text gives editors a formatting toolbar; Markdown gives them a plain text box. Both return markdown, so your frontend renders them the same way, and Rich Text can additionally return tokens for embedded blocks. Pick based on who writes the content rather than what your frontend expects: non-technical editors want the toolbar, developers usually prefer the plain box.

Select vs Text Input. If a field should only ever hold one of a few values, make it a Select and define the options. A free text field for "category" turns into , , and within a month.

Add at least three fields, then click Next, then Save on the last step. You should see Object type added!

---

Step 4: Mark the Fields That Matter as Required

By default every field is optional, which means content can be published with an empty hero image and no meta description.

On any metafield, open the three-dots menu and choose Validation. Turn on Required for the fields a page cannot render without. Text fields also offer Min Length and Max Length, which is a practical way to keep meta descriptions inside the length search engines display.

The same menu has Help Text, which puts a note under the field in the editor. One sentence explaining what a field is for prevents a lot of misuse.

---

Step 5: Connect Content With Relationships

Relationships are how one piece of content points at another, instead of repeating its details.

Single Object links to exactly one. A post has one author.

Multi Objects links to several. A post has several tags.

When you add either one, an object type dropdown appears. It defaults to All types, which lets an editor link to anything in the bucket. Set it to the specific type you mean. An author field that can accept a product is a bug waiting to happen.

The reason to use a relationship rather than typing the author's name into a text field is that the author exists once. Change their bio, and every post reflects it. With text fields you would be editing fifty posts.

Relationships return an ID by default. Your frontend asks for the full related object by adding to a query, which is the same used in the Next.js and Astro lessons.

---

Step 6: Look at the API Response

This is the step that makes the whole model concrete.

Open your object type for editing and click API Tools in the header. A drawer opens with REST, Node.js, and Curl tabs, plus a Response section showing live JSON.

Every key you see in is a metafield key you set in Step 3. That is the entire relationship between the two: your content model is the shape of your API response.

This is also where the parameter from the build lessons starts to make sense. Looking at the full response, you can see how much of it a given page actually needs. A list page rendering titles and thumbnails does not need full post bodies, and is how you stop asking for them.

To see actual content rather than the model, use API Tools from an individual object instead of from the object type.

---

A Tip for Changing Your Mind Later

You are not locked in. Add a metafield to an existing type and it is available in the API immediately, with no migration and no downtime.

The one thing to know is that existing objects will not have a value for the new field until someone fills it in. If you add a required "Hero image" to a type with forty published posts, those posts keep their current data, but the field will be empty until it is set, and your frontend needs to handle that. Ship the field, backfill the content, then make it required.

This is a real advantage over a relational database, where the same change means a migration. Use it. Model what you need today rather than guessing at every field you might want in two years.

---

Going Further

Two field types handle repeating structures. Repeater lets an editor add any number of a group of fields, which suits things like FAQ entries or a list of feature bullets where each item has a heading and a body. Parent groups related fields together in the editor without changing the data shape much, which is mostly a tidiness tool for long models.

There is also a Create button with a sparkles icon at the top of the new object type form, tooltipped Use AI to create your content model. Describe the type you want in plain language and it builds the fields. Useful for a first draft of a model, though you should still read what it produced before saving.

---

Do This in Your Project

1. Go to Objects, expand Object types, and click Add Object Type

2. Choose Multiple, name it , and confirm the slug reads

3. On Content model, add three fields from the palette: a Text Area for a bio, an Image for a headshot, and a Text Input for a website URL

4. Open the three-dots menu on the bio field and mark it Required under Validation

5. Click Next, then Save

6. Open your posts type and add a Single Object field called Author, with the object type dropdown set to Authors

7. Open API Tools on the posts type and find the new key in the response

That last step is the one to actually do. Seeing your field appear in the JSON connects the dashboard work to the code from the previous two lessons.

---

Up Next

Lesson 7: Migrate from WordPress or Webflow

Stage 3 is for anyone whose content already lives somewhere else. Lesson 7 covers moving it into Cosmic without losing the URLs you already rank for.