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

ParameterRequiredTypeDescription
typerequiredEnumtext, textarea, html-textarea, select-dropdown, object, objects, file, files, date, radio-buttons, check-boxes, repeater, parent, markdown, json, switch, number, color, emoji
titlerequiredStringYour Metafield title
keyrequiredStringUnique identifier for your Metafield
valuevariesVaries by typeMetafield 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.
requiredBoolA value is required
regexStringRestrict the value to match a regular expresssion
regex_messageStringThe message displayed when the value fails the regex
minlengthNumberAdd minlength to text or textarea Metafields
maxlengthNumberAdd maxlength to text or textarea Metafields
optionsRequired for options, radio, checkbox and switchVaries by typeArray of options for select, radio, and checkbox Metafields and string for switch Metafield with possible values true,false and yes,no
childrenArrayArray of nested Metafields
object_typeStringValid Object type slug. Applies only to object and objects Metafield
repeater_fieldsArrayArray 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.

ParameterRequiredTypeDescription
requiredBoolA value is required
regexStringRestrict the value to match a regular expresssion
regex_messageStringThe message displayed when the value fails the regex
minlengthNumberAdd minlength to text or textarea Metafields
maxlengthNumberAdd 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."
    }
  ]
}