Object types
Learn about Object types; used to organize and model Objects in your Cosmic Bucket.
The Object type model
The Object type model contains all the information about the Object type including content modeling using Metafields, localization, preview links, and more.
Properties
- Name
id
- Type
- string
- Description
Unique identifier for Object type.
- Name
title
- Type
- string
- Description
Object type title.
- Name
singular
- Type
- string
- Description
Singular title of the Object type.
- Name
slug
- Type
- string
- Description
Object type slugs are unique per Bucket.
- Name
singleton
- Type
- boolean
- Description
Single or multiple Objects in this type.
- Name
emoji
- Type
- string
- Description
Valid Unicode emoji displayed on the Object type table.
- Name
metafields
- Type
- array
- Description
Array of Metafields. See Metafields model.
- Name
options
- Type
- object
- Description
Contains boolean property
slug_field
which controls the display options for theslug
field for Objects in the type.
- Name
localization
- Type
- boolean
- Description
Add localization to the Object type. Default:
false
- Name
locales
- Type
- array
- Description
Array of available locales in the Object type. See available locale codes.
- Name
priority_locale
- Type
- string
- Description
Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.
The Object type model
{
"id": "63bde47897d49d0008a270b3",
"title": "Bikes",
"slug": "bikes",
"singular": "Bike",
"emoji": "🏍️",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
]
}
Get Object types
This endpoint enables you to retrieve a list of your Object types in the Bucket.
Request
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY'
})
await cosmic.objectTypes.find()
Response
{
"object_types": [
{
"id": "63bde47897d49d0008a270b3",
"title": "Bikes",
"slug": "bikes",
"singular": "Bike",
"emoji": "🏍️",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
...
]
},
{
"id": "63bde4c297d49d0008a270b4",
"title": "Cars",
"slug": "cars",
"singular": "Car",
"emoji": "🚗",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
...
]
}
]
}
Get a single Object type
Get a single Object type by slug
.
Required parameters
- Name
slug
- Type
- string
- Description
The Object type slug.
Request
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY'
})
await cosmic.objectTypes.findOne('object-type-slug')
Response
{
"object_type": {
"id": "63bde47897d49d0008a270b3",
"title": "Bikes",
"slug": "bikes",
"singular": "Bike",
"emoji": "🏍️",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
...
]
}
}
Create an Object type
This endpoint enables you to create an Object type in your Bucket.
The data request payload will need to be sent in JSON format with the Content-Type: application/json
header set.
Required parameters
- Name
title
- Type
- string
- Description
Object type title.
Optional parameters
- Name
singular
- Type
- string
- Description
Singular title of the Object type.
- Name
slug
- Type
- string
- Description
Object type slugs are unique per Bucket. Default:
title
converted to slug.
- Name
singleton
- Type
- boolean
- Description
Single or multiple Objects in this type.
- Name
emoji
- Type
- string
- Description
Valid Unicode emoji displayed on the Object type table.
- Name
metafields
- Type
- array
- Description
Array of Metafields. See Metafields Model.
- Name
options
- Type
- object
- Description
Contains boolean property
slug_field
which controls the display options for theslug
field for Objects in the type.
- Name
localization
- Type
- boolean
- Description
Add localization to the Object type. Default:
false
- Name
locales
- Type
- array
- Description
Array of available locales in the Object type. See available locale codes.
- Name
priority_locale
- Type
- string
- Description
Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.
Request
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY',
writeKey: 'BUCKET_WRITE_KEY'
})
await cosmic.objectTypes.insertOne({
title: "Bikes",
slug: "bikes",
emoji: "🏍️",
metafields: [
{
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"required": true
},
{
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"required": false
}
]
})
Response
{
"object_type": {
"id": "63bde47897d49d0008a270b3",
"title": "Bikes",
"slug": "bikes",
"singular": "Bike",
"emoji": "🏍️",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
...
]
}
}
Update an Object type
This endpoint enables you to update an Object type.
If using the NPM module, use the $set
method to update the Object type properties specificed.
Optional parameters
- Name
singular
- Type
- string
- Description
Singular title of the Object type.
- Name
slug
- Type
- string
- Description
Object type slugs are unique per Bucket. Default:
title
converted to slug.
- Name
singleton
- Type
- boolean
- Description
Single or multiple Objects in this type.
- Name
emoji
- Type
- string
- Description
Valid Unicode emoji displayed on the Object type table.
- Name
metafields
- Type
- array
- Description
Array of Metafields. See Metafields Model.
- Name
options
- Type
- object
- Description
Contains boolean property
slug_field
which controls the display options for theslug
field for Objects in the type.
- Name
localization
- Type
- boolean
- Description
Add localization to the Object type. Default:
false
- Name
locales
- Type
- array
- Description
Array of available locales in the Object type. See available locale codes.
- Name
priority_locale
- Type
- string
- Description
Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.
Request
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY',
writeKey: 'BUCKET_WRITE_KEY'
})
await cosmic.objectTypes.updateOne('object-type-slug', {
title: 'Motorcycles',
slug: 'motorcycles',
singular: 'Motorcycle'
})
Response
{
"object_type": {
"id": "63bde47897d49d0008a270b3",
"title": "Motorcycles",
"slug": "motorcycles",
"singular": "Motorcycle",
"emoji": "🏍️",
"created_at": "2023-01-10T22:19:36.128Z",
"modified_at": "2023-03-16T21:09:09.914Z",
"singleton": false,
"options": {
"slug_field": true
},
"metafields": [
{
"id": "c7c50911-3b38-4b22-a307-392eb9f84739",
"title": "Image",
"key": "image",
"type": "file",
"value": "",
"helptext": "",
"required": false,
},
{
"id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
"title": "Headline",
"key": "headline",
"type": "text",
"value": "",
"helptext": "",
"required": false
}
...
]
}
}
Delete an Object type
This endpoint enables you to delete an Object type and all Objects in this type from your Bucket.
Required parameters
- Name
slug
- Type
- string
- Description
Object type slug.
Optional parameters
- Name
trigger_webhook
- Type
- boolean
- Description
Triggers corresponding Object action webhook (See Webhooks).
Request
import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY',
writeKey: 'BUCKET_WRITE_KEY'
})
await cosmic.objectTypes.deleteOne("object-type-slug")
Response
{
"message": "Object type with slug ':slug' deleted successfully from bucket."
}
Metafields
Learn about Metafields; the way you compose your content model for your Objects in Cosmic.
Data Model
Parameter | Required | Type | Description |
---|---|---|---|
type | required | Enum | text, textarea, html-textarea, select-dropdown, object, objects, file, 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 |
Example Metafields
{
"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. Gets converted to url and imgix_url automatically
},
{
"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
}
],
// Repeating items and values
"children": [
{
"type": "repeating_item",
"children": [
{
"type": "text",
"title": "Name",
"key": "name",
"value": "Fiona Apple"
},
{
"type": "text",
"title": "Name",
"key": "name",
"value": "Jon Brion"
}
]
}
]
}
]
}
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 | Required | 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 validations
{
"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
}
]
}