Learn

Build Your First Artifact Definition

Create a first Cuddler Artifact Definition by aligning the governing Domain Specification, shared Artifact Specification, and example data and template files.

Tutorial path

Building a first Artifact Definition

The shortest useful path is to follow the standards in the order they constrain the artifact family.

1Choose the domain

Start from the Domain Specification so the artifact family has the right governing context.

2Apply the shared artifact rules

Read the Artifact Specification before drafting the family.

3Study published examples

Use existing Artifact Definitions to see how the public surface is structured.

4Draft aligned schemas

Keep the data contract and render contract in the same family from the start.

5Validate, then render

Finish by proving the contracts work before the final output step.

The tutorial is about applying the standards correctly, not replacing them.

This tutorial shows the shortest useful path for creating a public Artifact Definition. The goal is not to reinvent the standards; it is to use them in the right order so the result can be validated, versioned, and rendered consistently.

The workflow

  1. Start with the relevant Domain Specification so you know which domain you are working in.
  2. Read the shared Artifact Specification so your artifact follows the common publication rules.
  3. Inspect the matching Artifact Definitions to see how published examples are structured.
  4. Draft your data schema and template schema together so the data contract and render contract stay aligned.
  5. Validate the data JSON first, then validate the template JSON, then render the document.

What to keep in view

  • The Domain Specification tells you what the domain means.
  • The Artifact Specification tells you how a public Artifact Definition must be authored.
  • The example Artifact Document tells you what a successful implementation looks like.

Practical checkpoints

  • Keep meta.schemaVersion aligned across the schema family.
  • Bind the instance "$schema" to the exact canonical schema identity.
  • Treat validation failures as blockers, not warnings to work around.
  • Keep the final rendered output readable without weakening sanitization defaults.

Next step

Once you have a first definition working, move to Create a Data Schema and Create a Template Schema so you can separate data validation from rendering concerns.