Create a Data Schema

A good Data Schema does more than describe shape. It explains what each field means, how specific the content should be, and what the generator should avoid. That keeps the authoring process disciplined before rendering even starts.

Build the schema in layers

1. Identify the governing Domain Specification and the relevant artifact type.
2. Write the minimum required properties first so the document can be validated early.
3. Add clear field guidance for any value that an assistant might otherwise guess.
4. Keep the schema identity exact so the published "$schema" matches the canonical "$id".

What matters most

• Use the schema to make content expectations explicit.
• Keep required fields narrow enough to prevent ambiguity.
• Describe constraints in plain language where possible.
• Make the schema easy to validate without depending on renderer behavior.

Common mistakes

• Leaving a field name to imply its meaning instead of documenting it.
• Mixing render instructions into a data-only contract.
• Allowing version drift between the schema file and example data.