Learn

Add a New Artifact Type

Create a new Cuddler Artifact Definition family with aligned schemas, examples, and published guidance.

Procedure

Adding a new artifact type cleanly

This work succeeds when the schema, examples, and published surface all describe the same artifact family.

1Start from the domain

Use the governing Domain Specification to confirm where the new artifact belongs.

2Apply shared authoring rules

Confirm the Artifact Specification requirements before drafting anything.

3Define the data contract

Make the fields explicit enough for authors and assistants to fill correctly.

4Define the template contract

Validate rendering separately from the data model.

5Publish aligned examples and pages

Keep the examples, route, and bundle in the same version family.

A new artifact type is a release family, not only a schema file.

Adding a new artifact type is mostly a discipline exercise. The work succeeds when the schema, examples, and publication surface all describe the same thing in the same version family.

  1. Start from the governing Domain Specification for the domain the artifact belongs to.
  2. Confirm the shared Artifact Specification rules that govern how Artifact Definitions are authored and published.
  3. Define the new artifact family with a data schema that is explicit about the fields an assistant or author must fill in.
  4. Add a template schema that validates the render contract separately from the data contract.
  5. Publish aligned examples that validate against the exact schema versions they claim to use.
  6. Add the public Artifact Definition page and downloads together so the route and bundle stay in sync.

What Good Looks Like

  • The artifact type has a clear purpose that a reader can explain in one sentence.
  • The schema tells a generator what belongs in each property, not just what type the property is.
  • The example data and template files validate against the exact published URLs.
  • The page visible to humans explains where the artifact fits in the public standards hierarchy.

Avoid

  • Creating a schema first and inventing the process later.
  • Publishing examples that are “close enough” but not exact matches for the published schema identity.
  • Mixing implementation guidance with normative contract text.