Model/Block model
The way you define the kind of content you can edit inside a DatoCMS project passes through the concept of models and block models. For backward-compatibility reasons, the API refers to both as "item types".
Models
Models are much like database tables — they define the structure of your main content types (e.g., blog posts, products, landing pages). Each model is composed of fields with custom validations. Records created from models exist independently and can be referenced by other records through link fields.
Block Models
Block models define complex and repeatable structures that can be embedded inside records. They are the foundation behind features like Modular Content and Structured Text.
Key differences:
- Models create standalone records that can be referenced and have independent value
- Block models create blocks that only exist within parent records and cannot be referenced via link fields
- Block models defined in the library can be reused across different models
- When a record gets deleted, all the blocks it contains are deleted with it
- Blocks do not count towards your plan's records limit
You can distinguish between models and block models using the modular_block attribute: true indicates a block model, false indicates a regular model.
Object payload
RFC 4122 UUID of item type expressed in URL-safe base64 format
"DxMaW10UQiCmZcuuA-IkkA"
Must be exactly "item_type".
Name of the model/block model
"Blog post"
API key of the model/block model
"post"
Whether the model is single-instance or not. This property only applies to models, not block models
Whether editors can sort records via drag & drop or not. Must be false for block models
Whether this is a block model or not. Block models define structures that can be embedded inside records, while regular models create standalone records
Whether editors can organize records in a tree or not. Must be false for block models
If an ordering field is set, this field specifies the sorting direction. This property does not apply to block models
Ascending order
Descending order
Specifies the model's sorting method. Cannot be set in concurrency with ordering_field. This property does not apply to block models
"created_at"
Order by date of creation
Order by date of last update
Order by date of first publication
Order by date of last publication
Whether draft/published mode is active or not. Must be false for block models
Whether we require all the project locales to be present for each localized field or not
The way the model/block model collection should be presented to the editors
"compact"
Compact view
Tabular view
A hint shown to editors to help them understand the purpose of this model/block model
"Blog posts will be shown in our website under the Blog section"
Whether inverse relationships fields are expressed in GraphQL or not. Must be false for block models
Whether draft records can be saved without satisfying the validations or not. Must be false for block models
If this model is single-instance, this tells whether the single-instance record has already been created or not. This property only applies to models, not block models
The record instance related to this model. This relationship only applies to single-instance models, not block models
The list of fields for this model/block model
The list of fieldsets for this model/block model
The field to use as presentation title
The field to use as presentation image
The field to use as fallback title for SEO purposes. This relationship does not apply to block models
The field to use as fallback image for SEO purposes. This relationship does not apply to block models
The field to use as fallback description for SEO purposes. This relationship does not apply to block models
The field upon which the collection is sorted. This relationship does not apply to block models
The workflow to enforce on records
The way the model collection should be presented to the editors
This field contains a typo and will be removed in future versions: use collection_appearance instead
"compact"
Compact view
Tabular view
If this model is single-instance, this tells whether the single-instance record has already been created or not. This property only applies to models, not block models
This field will be removed in future versions: instead, use the equivalent has_singleton_item field in the meta collection