Metafields

Learn about Metafields; the way you compose, extend, and connect the Object content model in Cosmic.

What are Metafields? Metafields are the way to add custom fields to your Objects. They are stored in the Object type and are not stored in the Object. They contain the data model, validation, etc.

What is Metadata? Metadata is the data you add to your Objects using the Metafields model. They contain the data values.

Data model

Parameter	Required	Type	Description
`type`	required	Enum	text, textarea, html-textarea, select-dropdown, object, objects, file, files, date, radio-buttons, check-boxes, repeater, parent, markdown, json, switch, number, color, emoji
`title`	required	String	Your Metafield title
`key`	required	String	Unique identifier for your Metafield
`value`	varies	Varies by `type`	Metafield value. Property required to be present (empty string ok) except for `repeater` and `parent` (should not be present). See example model below for various value types and requirements.
`required`		Bool	A value is required
`regex`		String	Restrict the value to match a regular expresssion
`regex_message`		String	The message displayed when the value fails the regex
`minlength`		Number	Add minlength to text or textarea Metafields
`maxlength`		Number	Add maxlength to text or textarea Metafields
`options`	Required for `options`, `radio`, `checkbox` and `switch`	Varies by `type`	Array of options for select, radio, and checkbox Metafields and string for switch Metafield with possible values `true,false` and `yes,no`
`children`		Array	Array of nested Metafields
`object_type`		String	Valid Object type slug. Applies only to `object` and `objects` Metafield
`repeater_fields`		Array	Array of nested Metafields. Applies only to `repeater` Metafield

Adding and editing Metafields

When adding / editing Metafields to Object types using the API, use the following model for each Metafields type. Any value added to the value property is treated as a default value on each newly created Object.

{
  "metafields": [
    {
      "type": "text",
      "title": "Headline",
      "key": "headline",
      "value": "3030 Palo Alto Blvd.",
      "required": true
    },
    {
      "type": "textarea",
      "title": "Basic Text",
      "key": "basic_text",
      "value": "This home is a must see!",
      "required": true
    },
    {
      "type": "html-textarea",
      "title": "Extended Text",
      "key": "extended_text",
      "value": "<p>Some <strong>HTML content</strong> for <em>dramatic</em> effect!</p>"
    },
    {
      "type": "markdown",
      "title": "Markdown Text",
      "key": "markdown_text",
      "value": "# Hello World!"
    },
    {
      "type": "select-dropdown",
      "title": "State",
      "key": "state",
      "value": "California",
      "options": [
        {
          "key": "CA",
          "value": "California"
        },
        {
          "key": "TX",
          "value": "Texas"
        }
      ]
    },
    {
      "type": "object",
      "title": "Author",
      "key": "author",
      "object_type": "authors",
      "value": "5a4806974fa85fc8a7000002" // Object ID
    },
    {
      "type": "objects",
      "title": "Categories",
      "key": "categories",
      "object_type": "categories",
      "value": ["5a4806974fa85fc8a7000007,5a4806974fa85fc8a7000008"] // Object IDs
    },
    {
      "type": "file",
      "title": "Hero",
      "key": "hero",
      "value": "media-name-property-in-bucket.jpg" // This is the name of your media.
    },
    {
      "type": "files",
      "title": "Gallery",
      "key": "gallery",
      "value": [
        "gallery-image-1.jpg",
        "gallery-image-2.jpg",
        "gallery-image-3.jpg"
      ] // These are the names of your media.
    },
    {
      "type": "date",
      "title": "Listing Start Date",
      "key": "listing_start_date",
      "value": "2020-10-15"
    },
    {
      "type": "json",
      "title": "JSON Data",
      "key": "json_data",
      "value": {
        "strings": "cheese",
        "arrays": ["Bradbury", "Charles", "Ramono", "the last Jedi", "Liotta"],
        "objects": {
          "bools": true,
          "nestable": true
        }
      }
    },
    {
      "type": "radio-buttons",
      "title": "Deposit Required",
      "key": "deposit_required",
      "value": "The Other",
      "options": [
        {
          "value": "This"
        },
        {
          "value": "That"
        },
        {
          "value": "The Other"
        }
      ]
    },
    {
      "type": "check-boxes",
      "title": "Amenities",
      "key": "amenities",
      "value": ["Pool", "Gym"],
      "options": [
        {
          "value": "Pool"
        },
        {
          "value": "Gym"
        },
        {
          "value": "Landscaping"
        }
      ]
    },
    {
      "type": "switch",
      "title": "This is great",
      "key": "this_is_great",
      "value": true,
      "options": "true,false"
    },
    {
      "type": "parent", // ! Value is not allowed for parent Metafield !
      "title": "Call Out Section",
      "key": "call_out_section",
      "children": [
        {
          "type": "text",
          "title": "Headline",
          "key": "headline",
          "value": "You're Going to Love it Here!"
        },
        {
          "type": "html-textarea",
          "title": "Section Content",
          "key": "section_content",
          "value": "<p>You are going to <strong>love</strong> it in Cosmic Village. The best place to raise a team!</p>"
        },
        {
          "type": "file",
          "title": "Hero",
          "key": "hero",
          "value": "big-beautiful-image.jpg"
        }
      ]
    },
    {
      "type": "repeater", // ! Value is not allowed for repeater Metafield !
      "title": "Testimonials",
      "key": "testimonials",
      // Available repeaters
      "repeater_fields": [
        {
          "title": "Name",
          "key": "name",
          "value": "",
          "type": "text",
          "required": false
        },
        {
          "title": "Quote",
          "key": "quote",
          "value": "",
          "type": "text",
          "required": false
        }
      ]
    }
  ]
}

Metafield Validation

You can use optional validation parameters to make sure editors using the web dashboard enter the correct values.

Reference the Metafield model to learn more.

Parameter	Type	Description
`required`	Bool	A value is required
`regex`	String	Restrict the value to match a regular expresssion
`regex_message`	String	The message displayed when the value fails the regex
`minlength`	Number	Add minlength to text or textarea Metafields
`maxlength`	Number	Add maxlength to text or textarea Metafields

Example Metafields with validation

{
  "title": "Users",
  "singular": "User",
  "slug": "users",
  "metafields": [
    {
      "key": "first_name",
      "title": "First Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "last_name",
      "title": "Last Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "email",
      "title": "Email",
      "type": "text",
      "value": "",
      "regex": "/^([a-z0-9_.-]+)@([da-z.-]+).([a-z.]{2,6})$/",
      "regex_message": "You must enter a valid email."
    },
    {
      "key": "avatar",
      "title": "Avatar",
      "type": "file",
      "value": ""
    },
    {
      "key": "tagline",
      "title": "Tagline",
      "type": "text",
      "value": "",
      "maxlength": 50
    }
  ]
}

Fetching Metadata

When fetching Objects from the API, Metafields get converted into key: value pairs on the Object metadata property. See the Objects model for more information.

{
  "metadata": {
    "headline": "3030 Palo Alto Blvd.",
    "basic_text": "This home is a must see!",
    "extended_text": "<p>Some <strong>HTML content</strong> for <em>dramatic</em> effect!</p>",
    "markdown_text": "# Hello World!",
    "state": "California",
    "author": {
      "title": "Author Name",
      "metadata": {
        "image": {
          "url": "https://cdn.cosmicjs.com/author-headshot.jpg",
          "imgix_url": "https://imgix.cosmicjs.com/author-headshot.jpg"
        }
      }
      // May include more nested data
    },
    "categories": [
      {
        "title": "Category 1"
        // May include more nested data
      },
      {
        "title": "Category 2"
        // May include more nested data
      },
    ],
  "hero": "https://cdn.cosmicjs.com/media-name-property-in-bucket.jpg",
  "gallery": [
    {
      "url": "https://cdn.cosmicjs.com/gallery-image-1.jpg",
      "imgix_url": "https://imgix.cosmicjs.com/gallery-image-1.jpg"
    },
    {
      "url": "https://cdn.cosmicjs.com/gallery-image-2.jpg",
      "imgix_url": "https://imgix.cosmicjs.com/gallery-image-2.jpg"
    },
    {
      "url": "https://cdn.cosmicjs.com/gallery-image-3.jpg",
      "imgix_url": "https://imgix.cosmicjs.com/gallery-image-3.jpg"
    },
  ],
  "listing_start_date": "2020-10-15",
  "json_data": {
    "strings": "cheese",
    "arrays": ["Bradbury", "Charles", "Ramono", "the last Jedi", "Liotta"],
    "objects": {
      "bools": true,
      "nestable": true
    }
  },
  "deposit_required": "The Other",
  "amenities": ["Pool", "Gym"],
  "this_is_great": true,
  "call_out_section": {
    "headline": "You're Going to Love it Here!",
    "section_content": "<p>You are going to <strong>love</strong> it in Cosmic Village. The best place to raise a team!</p>",
    "hero": {
      "url": "https://cdn.cosmicjs.com/big-beautiful-image.jpg",
      "imgix_url": "https://imgix.cosmicjs.com/big-beautiful-image.jpg"
    }
  },
  "testimonials": [
    {
      "name": "Fiona Apple",
      "quote": "This is the best place in the LA area!"
    },
    {
      "name": "Jon Brion",
      "quote": "I came for the great music, I stayed for the good vibes."
    }
  ]
}