mdcms-schema-refine

MDCMS Schema Refine

Edit mdcms.config.ts to shape the content model and push the change to the server. This is the skill for post-init schema work — whether that's correcting a brownfield-inferred schema, extending a greenfield scaffold, or evolving a mature project.

When to use this skill

• After mdcms-brownfield-init when the inferred schema needs corrections or additions.
• After mdcms-greenfield-init when the scaffolded post type is not enough for the real content model.
• Any time the user asks to add/edit a type, add/edit a field, or link two types via a reference.

Not for importing content, embedding Studio, or editing individual documents — those are different skills.

Prerequisites

• A working mdcms.config.ts and a reachable MDCMS server (run mdcms-brownfield-init or mdcms-greenfield-init first if not).
• The user must be logged in for the target (server, project, environment). mdcms schema sync writes to the server and fails with 401/unauthorized otherwise. If mdcms status prints an auth error, run mdcms login (interactive) or set MDCMS_API_KEY (non-interactive) before continuing — see mdcms-content-sync-workflow Step 0 for full guidance.
• Read the current config before editing so you understand the shape you're changing.

Core concepts

• Type — a content kind (e.g. post, page, author). Declared via defineType(name, { directory, fields, ... }).
• Field — a Zod validator attached to a frontmatter key. Typical shapes: z.string().min(1), z.number().optional(), z.boolean().default(false), z.array(z.string()), z.enum([...]).
• Reference — fieldTypes.reference("<target-type>") makes a field point to a document of another type. References are resolved by the SDK and surfaced in Studio as pickers.
• Localized type — localized: true on defineType makes every document live in multiple locale variants grouped by a shared translation group id.
• Environment-scoped fields — .env("staging") chained onto a Zod validator makes a field only apply in that environment. Use sparingly.