Reader guide
Read the Artifact Specification when you need shared rules for authoring an Artifact Definition with an exact Data Schema that tells AI which JSON fields and data types to return.
- Use this when
- You are defining or reviewing a public Artifact Definition and need one contract for authoring, machine guidance, metadata, conformance, attribution, and publication.
- What it controls
- Cross-cutting rules that apply to every public Artifact Definition, regardless of whether the artifact role is Data, Template, or Process.
- What it does not do
- It does not decide whether your work belongs in Data, Template, or Process, and it does not define one specific artifact type by itself.
- Read next
- Pair this document with one relevant Document Role Specification. Then author a definition bundle or open the published Artifact Definition for the artifact type you need.
This flagship shared authoring standard defines the metadata, conformance, attribution, publication, and machine-guidance rules every public Cuddler Artifact Definition must satisfy.
Overview
The Artifact Specification is the shared rulebook for public Cuddler Artifact Definitions in release 1.0.0. It defines how Artifact Definitions are authored, what metadata they must expose, how they identify both their governing Document Role and the shared Artifact Specification, and what attribution and confidentiality rules apply across the publication model.
Artifact Definitions remain specific artifact-type definitions. A Document Role tells you what job the artifact plays in the system and complies with the Specification Root. The Artifact Specification tells you how to publish that artifact definition cleanly and consistently, and each public Artifact Definition must comply with both.
For an application consuming AI-generated data, the practical result is an exact Data Schema that defines the expected JSON fields, types, formats, and allowed values. The AI receives that contract before generation, and validation blocks output that does not match before the application uses it.
How AI agents use this specification
A definition-building agent uses the Artifact Specification and one Document Role Specification together with source context and domain examples. The standards take precedence over examples, and every knowable rule becomes a definitive constraint or structured for-ai instruction instead of an assumption hidden in a side prompt.
The resulting synchronized definition bundle gives a downstream document-building agent an exact contract to follow. Only the Data member is authored as a family-specific schema. The Template and Process documents consume Cuddler’s published role schemas, while the current definition file identifies the active bundle.
- Governing inputs Artifact Specification, one Document Role Specification, source context, and domain evidence.
- Definition-building agent
Authors exact constraints, schema-node
for-aiguidance, and the synchronized definition bundle. - Governed contract Data Schema, sanitized example, aligned Template and Process documents, and current definition file.
- Document-building agent Uses the selected definitions and embedded guidance to prepare validatable Artifact Documents.
- Validation and rendering Validates Data and Template inputs independently before a compatible runtime renders the Report.
Start with Build an Artifact Definition for the complete authoring path, or open Cuddler for AI for canonical URLs, downloads, and validation order.
Normative Artifacts
Related Artifacts
Related public materials
AI implementation notes
- Treat this page as the canonical citation target for the shared Artifact Specification.
- Use one governing Document Role Specification and the shared Artifact Specification together when authoring or validating a public Artifact Definition.
- Parse and follow applicable schema-node
for-aiAlpaca arrays when preparing Data, Template, and Process values. - Treat Artifact Documents as confidential by default unless the publisher explicitly designates a public example.
Canonical standard text
The section below is the full normative publication rendered directly from the canonical repository source. Use it for exact wording, implementation details, and citation.
Version 1.0.0
Status
This document is the canonical shared Artifact Specification for public Cuddler Artifact Definitions in release 1.0.0.
The Artifact Specification is a cross-cutting governing specification. It does not classify domains by itself and it does not define one business artifact type in full detail. Instead, it defines how every public Artifact Definition must be authored, versioned, attributed, validated, and published alongside its governing Document Role.
1. Purpose
Cuddler uses a layered publication model:
- Specification Root defines the topmost canonical publication node for published Document Role standards.
- Document Role complies with the Specification Root and defines the governing rules for one artifact domain.
- Artifact Specification defines the shared authoring rules for Artifact Definitions across domains.
- Artifact Definition defines one specific artifact type and complies with both its governing Document Role and the shared Artifact Specification.
- Artifact Document is the concrete implemented artifact.
The Artifact Specification exists so that Artifact Definitions remain publishable, reusable, machine-implementable, and consistent across domains.
2. Relationship to Document Role
Every public Artifact Definition MUST comply with exactly one governing Document Role and with this shared Artifact Specification.
A Document Role complies with the Specification Root and classifies an Artifact Definition into a bounded domain such as Workflow, Data Document, or Template Document. The Artifact Specification defines the shared authoring and publication rules that apply across those domains. Neither document replaces the other.
3. Required Artifact Definition metadata
A public Artifact Definition publication MUST expose, directly or through its canonical page and machine-readable bundle, at least the following metadata:
- Artifact Definition title
- Artifact Definition identifier
- Artifact Definition version
- artifact type
- status
- governing Document Role title and canonical version URL
- governing Artifact Specification version and canonical version URL
- source URL for the canonical published Artifact Definition bundle
- exact canonical publication bundle file inventory
- publisher or author
- copyright and attribution notice
The machine-readable bundle SHOULD also preserve a stable implementation identifier and output metadata when the domain requires them.
When an Artifact Definition bundle contains multiple schemas, manifests, or examples, it MUST identify each canonical published file and state what that file validates or governs.
4. Authoring and conformance rules
A public Artifact Definition is valid only when all of the following are true:
- it complies with exactly one governing Document Role,
- it complies with this shared Artifact Specification,
- its machine-readable schema files and page metadata agree about identity, version, and governing documents,
- its example artifacts bind to the exact canonical schema identifiers they claim to implement,
- it does not widen optionality, counts, enumerations, or publication bundle shape merely because examples omit or conflict on a business fact,
- no Artifact Document published as an example contradicts the governing Artifact Definition, this Artifact Specification, or the governing Document Role.
Artifact Definition pages MUST state clearly that the Artifact Definition defines what Artifact Documents must implement. They MUST NOT present themselves as the shared Artifact Specification.
5. Versioning and extension rules
The Artifact Specification version is part of the Artifact Definition publication contract. Artifact Definition pages and machine-readable bundles MUST identify the Artifact Specification version they follow.
Additive clarifications may ship as patch or minor revisions when they do not invalidate already complying Artifact Definitions. Breaking changes to required metadata, conformance rules, or authoring structure require a new major Artifact Specification version.
6. Publication, openness, and confidentiality
Document Role, the Artifact Specification, and Artifact Definitions are open source and publicly shareable.
Artifact Documents are confidential by default unless the owner or publisher explicitly designates them otherwise.
Public examples MAY be published as illustrative Artifact Documents, but those examples do not change the default confidentiality rule for real operational instances.
7. Attribution and source-URL requirement
Third parties may use, implement, adapt, and modify Document Role, the Artifact Specification, and Artifact Definitions provided they preserve attribution and include the public URL of the original source document they are using.
Modified redistributions SHOULD clearly indicate that they are derived works and MUST NOT be represented as the canonical Cuddler publication.
8. Artifact Definition page requirements
Each public Artifact Definition page MUST:
- name the governing Document Role,
- name the governing Artifact Specification version,
- link to the canonical URLs for both,
- describe the Artifact Definition as the definition document for one artifact type,
- link to the canonical machine-readable bundle and examples,
- list the exact canonical publication files and what each file validates or governs,
- display the applicable attribution and reuse notice.
9. References
- Data Document Role v1.0.0
- Template Document Role v1.0.0
- Process Document Role v1.0.0
