datocms-content-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DatoCMS Content Modeling

DatoCMS内容建模

Principles for designing structured content in DatoCMS that's reusable, editor-friendly, and survives redesigns. This skill answers "how should I model X?" — not "how do I create the model?".

为DatoCMS设计可复用、编辑器友好且能适应重设计的结构化内容的原则。本技能解答的是**“我应该如何建模X？”——而非“我如何创建该模型？”**。

When to apply

适用场景

New project content model layout
Model vs block decisions
Choosing
```
single_block
```
,
```
rich_text
```
,
```
structured_text
```
for block fields
Reusable model link vs embedded block
Taxonomy design: categories, tags, hierarchies, facets
Refactor page-shaped, redesign-fragile, duplication-heavy schemas
Diagnose record-size/block-count/nesting-depth limits; design around locale-multiplied block volume
Admin UI organization: Content tab menu (editors), Schema tab menu (devs), saved views via
```
item_type_filter
```
Model behavior/presentation config: singleton, sortable, tree, draft-mode, all-locales-required;
```
presentation_title_field
```
vs
```
title_field
```
;
```
collection_appearance
```
; ordering

Field config: validators,

appearance

choices (

string_select

enum

framed

frameless

single_block

link_select

link_embed

); editor parameters (slug auto-fill,

structured_text

nodes/marks, SEO previews,

required_alt_title

)

新项目内容模型规划
模型与区块的决策选择
为区块字段选择
```
single_block
```
、
```
rich_text
```
、
```
structured_text
```
可复用模型链接与嵌入区块的选择
分类法设计：分类、标签、层级结构、分面
重构页面型、易受重设计影响、重复内容过多的schema
诊断记录大小/区块数量/嵌套深度限制；针对多语言环境下的区块容量进行设计适配
管理UI组织：内容标签页菜单（面向编辑器）、Schema标签页菜单（面向开发者）、通过
```
item_type_filter
```
创建保存视图
模型行为/展示配置：singleton、可排序、树形结构、草稿模式、all-locales-required；
```
presentation_title_field
```
与
```
title_field
```
对比；
```
collection_appearance
```
；排序设置
字段配置：验证器、
```
appearance
```
选项（
```
string_select
```
+
```
enum
```
、带框架与无框架
```
single_block
```
、
```
link_select
```
与
```
link_embed
```
）；编辑器参数（slug自动填充、
```
structured_text
```
节点/标记、SEO预览、
```
required_alt_title
```
）

Core principles

核心原则

Content is data, not pages. Structure for meaning, not presentation.
Single source of truth. Avoid content duplication.
Don't recreate built-ins. Record meta (
```
created_at
```
,
```
published_at
```
, …), asset meta (
```
alt
```
,
```
title
```
,
```
custom_data
```
,
```
focal_point
```
), and ordering (
```
position
```
) all exist already — never add sibling fields, on records or blocks. See
```
references/separation-of-concerns.md
```
and
```
references/model-configuration.md
```
§ Behaviour — ordering.
Future-proof. Design for unknown channels and redesigns.
Editor-centric. Optimize for editors, not developers. Always add hints to fields, fieldsets, models unless obvious — schema is editor UI. See
```
references/separation-of-concerns.md
```
§ Hints.

内容是数据，而非页面。依据内容含义而非展示形式进行结构化设计。
单一数据源。避免内容重复。
不要重复造轮子。记录元数据（
```
created_at
```
、
```
published_at
```
等）、资源元数据（
```
alt
```
、
```
title
```
、
```
custom_data
```
、
```
focal_point
```
）以及排序（
```
position
```
）均已内置——切勿在记录或区块中添加同类字段。详见
```
references/separation-of-concerns.md
```
与
```
references/model-configuration.md
```
§ 行为——排序。
面向未来。为未知渠道与重设计场景进行设计。
以编辑器为中心。优先优化编辑器体验而非开发者体验。务必为字段、字段集、模型添加提示，除非含义十分明确——schema本身就是编辑器UI。详见
```
references/separation-of-concerns.md
```
§ 提示。

Routing

后续流程

Once modeling decision made:

Implementation —
```
datocms-cli
```
(migrations, default) or
```
datocms-cma
```
(user opts out of migrations / wants immediate schema mutation).
Querying / rendering —
```
datocms-cda
```
for GraphQL reads and Structured Text query fragments;
```
datocms-frontend-integrations
```
for framework rendering.
Validator and cascade-strategy mechanics —
```
datocms-cma/references/schema.md
```
(link/structured-text validators,
```
on_reference_delete_strategy
```
, etc.).
Building or editing actual DAST tree —
```
datocms-cma/references/editing-records.md
```
(full DAST grammar, dastdown round-trip, typed guards).

建模决策确定后：

实现 —— 使用
```
datocms-cli
```
（迁移，默认方式）或
```
datocms-cma
```
（用户选择不使用迁移 / 需立即修改schema）。
查询/渲染 —— 使用
```
datocms-cda
```
进行GraphQL读取与Structured Text查询片段；使用
```
datocms-frontend-integrations
```
进行框架渲染。
验证器与级联策略机制 —— 参考
```
datocms-cma/references/schema.md
```
（链接/结构化文本验证器、
```
on_reference_delete_strategy
```
等）。
构建或编辑实际DAST树 —— 参考
```
datocms-cma/references/editing-records.md
```
（完整DAST语法、dastdown往返转换、类型守卫）。

References

参考资料

Mandatory — never propose models, blocks, or fields from memory. Before any structured question or schema suggestion, load every reference whose decision is in scope.

Match decision → file:

```
references/separation-of-concerns.md
```
— naming/shaping for meaning, not appearance; redesign test; record-meta + file/gallery-meta + position duplication anti-patterns.
```
references/models-vs-blocks.md
```
— model vs block; structural rules (no orphans, no link-field references, locale inheritance); per-record limits (300 KB / 500 blocks / 5 levels); locale multiplier.
```
references/block-fields-and-structured-text.md
```
—
```
single_block
```
vs
```
rich_text
```
(Modular Content) vs
```
structured_text
```
; inline-vs-block-vs-itemLink-vs-inlineItem matrix; DAST cheatsheet; native nodes (
blockquote
,
code
,
list
,
heading
,
thematicBreak
,
link
) — never recreate as blocks; image/gallery/video block shape (no
```
caption
```
sibling); container-shape effects on limits.
```
references/content-reuse.md
```
— link fields, project-level Blocks Library, built-in
```
seo
```
, frameless single-block, tree taxonomies, fieldset grouping, block-library hygiene.
```
references/taxonomy-classification.md
```
— flat tags, tree models, faceted classification via multiple links, cascade strategies.
```
references/ui-organization.md
```
— Content tab
```
menu_item
```
(editors), Schema tab
```
schema_menu_item
```
(devs), saved views via
```
item_type_filter
```
, emoji conventions, IA heuristics.

references/model-configuration.md

— singleton, draft mode,

all_locales_required

, sortable/tree/ordering,

inverse_relationships_enabled

presentation_title_field

presentation_image_field

collection_appearance

, CDA SEO fallbacks; create-then-wire mechanic.

```
references/field-configuration.md
```
— validators (enum, format, length, unique,
```
slug_title_field
```
,
```
required_alt_title
```
,
```
required_seo_fields
```
,
```
transformable_image
```
, dimensions, structured-text size);
```
appearance
```
editors (
```
string_select
```
+enum, markdown/wysiwyg/textarea, framed vs frameless
```
single_block
```
,
```
link_select
```
vs
```
link_embed
```
, structured_text nodes/marks/heading_levels, SEO previews, slug
```
url_prefix
```
, color presets).

强制要求 —— 切勿凭记忆提议模型、区块或字段。在提出任何结构化问题或schema建议前，加载所有与决策范围相关的参考资料。

决策对应参考文件：

```
references/separation-of-concerns.md
```
—— 依据含义而非外观进行命名/设计；重设计测试；记录元数据 + 文件/图库元数据 + 排序字段重复的反模式。
```
references/models-vs-blocks.md
```
—— 模型与区块对比；结构规则（无孤立节点、无链接字段引用、多语言继承）；单记录限制（300 KB / 500区块 / 5层级）；多语言乘数效应。
```
references/block-fields-and-structured-text.md
```
——
```
single_block
```
、
```
rich_text
```
（模块化内容）与
```
structured_text
```
对比；内联-区块-itemLink-inlineItem矩阵；DAST速查表；原生节点（
blockquote
、
code
、
list
、
heading
、
thematicBreak
、
link
）——切勿重构为区块；图片/图库/视频区块形态（无
```
caption
```
同级字段）；容器形态对限制的影响。
```
references/content-reuse.md
```
—— 链接字段、项目级区块库、内置
```
seo
```
、无框架单区块、树形分类法、字段集分组、区块库规范。
```
references/taxonomy-classification.md
```
—— 扁平标签、树形模型、通过多链接实现分面分类、级联策略。
```
references/ui-organization.md
```
—— 内容标签页
```
menu_item
```
（面向编辑器）、Schema标签页
```
schema_menu_item
```
（面向开发者）、通过
```
item_type_filter
```
创建保存视图、表情符号规范、信息架构启发法。

references/model-configuration.md

—— singleton、草稿模式、

all_locales_required

、可排序/树形/排序设置、

inverse_relationships_enabled

、

presentation_title_field

、

presentation_image_field

、

collection_appearance

、CDA SEO回退机制；先创建后关联的机制。

```
references/field-configuration.md
```
—— 验证器（enum、格式、长度、唯一性、
```
slug_title_field
```
、
```
required_alt_title
```
、
```
required_seo_fields
```
、
```
transformable_image
```
、尺寸、结构化文本大小）；
```
appearance
```
编辑器（
```
string_select
```
+enum、markdown/wysiwyg/textarea、带框架与无框架
```
single_block
```
、
```
link_select
```
与
```
link_embed
```
、structured_text节点/标记/标题层级、SEO预览、slug
```
url_prefix
```
、颜色预设）。