{
  "meta": {
    "artifactSpecificationId": "artifact-specification",
    "version": "1.0.0",
    "title": "Cuddler Artifact Specification",
    "status": "Public normative publication",
    "publishedAt": "2026-03-22T00:00:00Z",
    "updatedAt": "2026-03-22T00:00:00Z",
    "canonicalVersionUrl": "https://www.cuddler.dev/standards/artifact-specification/",
    "canonicalArtifactSpecificationUrl": "https://www.cuddler.dev/standards/artifact-specification/v1.0.0/artifact-specification.json",
    "summary": "Official Cuddler Artifact Specification v1.0.0 defining the shared authoring, metadata, publication, attribution, confidentiality, and validation summary that every public Cuddler Artifact Definition must satisfy.",
    "authors": [
      {
        "name": "Matt Edwards",
        "url": "https://www.cuddler.dev/standards/authors/matt-edwards/"
      }
    ],
    "license": "© 2026 TrackThat. This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). See https://www.cuddler.dev/license/ for the site license summary. You are free to share, use, adapt, and modify this material, including for commercial purposes, provided you give appropriate attribution and include a link to the original source URL and the CC BY 4.0 license at https://creativecommons.org/licenses/by/4.0/.",
    "copyright": "© 2026 TrackThat."
  },
  "content": {
    "abstract": "This Artifact Specification defines the shared authoring and conformance rules for every public Cuddler Artifact Definition. It works alongside the governing Document Role that complies with the Specification Root, standardizes the metadata and publication summary every Artifact Definition must expose, and clarifies openness, attribution, and confidentiality boundaries across the publication model.",
    "documentMediaType": "text/html",
    "documentHtml": "<h2>Version 1.0.0</h2>\n<h3>Status</h3>\n<p>This document is the canonical shared Artifact Specification for public Cuddler Artifact Definitions in release <code>1.0.0</code>.</p>\n<p>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.</p>\n<hr />\n<h3>1. Purpose</h3>\n<p>Cuddler uses a layered publication model:</p>\n<ol>\n<li><strong>Specification Root</strong> defines the topmost canonical publication node for published Document Role standards.</li>\n<li><strong>Document Role</strong> complies with the Specification Root and defines the governing rules for one artifact domain.</li>\n<li><strong>Artifact Specification</strong> defines the shared authoring rules for Artifact Definitions across domains.</li>\n<li><strong>Artifact Definition</strong> defines one specific artifact type and complies with both its governing Document Role and the shared Artifact Specification.</li>\n<li><strong>Artifact Document</strong> is the concrete implemented artifact.</li>\n</ol>\n<p>The Artifact Specification exists so that Artifact Definitions remain publishable, reusable, machine-implementable, and consistent across domains.</p>\n<hr />\n<h3>2. Relationship to Document Role</h3>\n<p>Every public Artifact Definition MUST comply with exactly one governing Document Role and with this shared Artifact Specification.</p>\n<p>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.</p>\n<hr />\n<h3>3. Required Artifact Definition metadata</h3>\n<p>A public Artifact Definition publication MUST expose, directly or through its canonical page and machine-readable bundle, at least the following metadata:</p>\n<ul>\n<li>Artifact Definition title</li>\n<li>Artifact Definition identifier</li>\n<li>Artifact Definition version</li>\n<li>artifact type</li>\n<li>status</li>\n<li>governing Document Role title and canonical version URL</li>\n<li>governing Artifact Specification version and canonical version URL</li>\n<li>source URL for the canonical published Artifact Definition bundle</li>\n<li>exact canonical publication bundle file inventory</li>\n<li>publisher or author</li>\n<li>copyright and attribution notice</li>\n</ul>\n<p>The machine-readable bundle SHOULD also preserve a stable implementation identifier and output metadata when the domain requires them.</p>\n<p>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.</p>\n<hr />\n<h3>4. Authoring and conformance rules</h3>\n<p>A public Artifact Definition is valid only when all of the following are true:</p>\n<ol>\n<li>it complies with exactly one governing Document Role,</li>\n<li>it complies with this shared Artifact Specification,</li>\n<li>its machine-readable schema files and page metadata agree about identity, version, and governing documents,</li>\n<li>its example artifacts bind to the exact canonical schema identifiers they claim to implement,</li>\n<li>it does not widen optionality, counts, enumerations, or publication bundle shape merely because examples omit or conflict on a business fact,</li>\n<li>no Artifact Document published as an example contradicts the governing Artifact Definition, this Artifact Specification, or the governing Document Role.</li>\n</ol>\n<p>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.</p>\n<hr />\n<h3>5. Versioning and extension rules</h3>\n<p>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.</p>\n<p>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.</p>\n<hr />\n<h3>6. Publication, openness, and confidentiality</h3>\n<p>Document Role, the Artifact Specification, and Artifact Definitions are open source and publicly shareable.</p>\n<p>Artifact Documents are confidential by default unless the owner or publisher explicitly designates them otherwise.</p>\n<p>Public examples MAY be published as illustrative Artifact Documents, but those examples do not change the default confidentiality rule for real operational instances.</p>\n<hr />\n<h3>7. Attribution and source-URL requirement</h3>\n<p>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.</p>\n<p>Modified redistributions SHOULD clearly indicate that they are derived works and MUST NOT be represented as the canonical Cuddler publication.</p>\n<hr />\n<h3>8. Artifact Definition page requirements</h3>\n<p>Each public Artifact Definition page MUST:</p>\n<ul>\n<li>name the governing Document Role,</li>\n<li>name the governing Artifact Specification version,</li>\n<li>link to the canonical URLs for both,</li>\n<li>describe the Artifact Definition as the definition document for one artifact type,</li>\n<li>link to the canonical machine-readable bundle and examples,</li>\n<li>list the exact canonical publication files and what each file validates or governs,</li>\n<li>display the applicable attribution and reuse notice.</li>\n</ul>\n<hr />\n<h3>9. References</h3>\n<ul>\n<li>Data Document Role v1.0.0</li>\n<li>Template Document Role v1.0.0</li>\n<li>Process Document Role v1.0.0</li>\n</ul>",
    "execution": {
      "implementerRequirements": [
        "Treat the Artifact Specification as the shared authoring and publication contract for all public Cuddler Artifact Definitions, and use its summary, abstract, section summaries, execution guidance, publication notes, and artifact groups as the shared drafting brief.",
        "Require Artifact Definitions to publish well-informed schema-node <code>for-ai</code> arrays in Alpaca format. Consumers should parse and follow those entries when preparing Data, Template, and Process values, and authors should not use JSON Schema <code>description</code> as the primary AI-instruction surface.",
        "When a value can be fixed by the standard or artifact intent, the final schema should fix it with definitive constraints such as const, enum, pattern, format, required, minItems, maxItems, conditional gates, and closed-object rules instead of leaving it ambiguous.",
        "Do not widen optionality, enumerations, counts, or publication bundle shape just because a user example omits a value or conflicts with another example; unresolved business gaps belong in a brief assumptions note rather than in a looser schema.",
        "Ensure every public Artifact Definition identifies exactly one governing Document Role that complies with the Specification Root and the governing Artifact Specification version it follows.",
        "Use user-provided example documents only to derive business-domain facts and content expectations that cannot already be fixed by the governing standards, require an exact schema-file inventory when the bundle contains multiple machine-readable files, and preserve attribution and the original public source URL whenever public Cuddler standards or schemas are reused or adapted."
      ],
      "validationWorkflow": [
        "Validate Artifact Definition bundle identity and version metadata, then confirm governing Document Role and Artifact Specification links, then validate any published examples against the exact canonical schema identifiers they claim to implement.",
        "Fail authoring-profile validation when a required schema-node <code>for-ai</code> array is missing, malformed, or empty where the governing standards require one.",
        "Fail publication when Artifact Definition page metadata, machine-readable bundle metadata, canonical public URLs, or the published schema-file inventory drift from one another.",
        "Treat Artifact Documents as confidential by default unless the publication explicitly designates a public example."
      ],
      "publicationNotes": [
        "Publish the Artifact Specification as one canonical page and one canonical machine-readable source document.",
        "Publish AI-facing schema-node guidance in <code>for-ai</code> Alpaca arrays instead of relying on JSON Schema <code>description</code> as the instruction channel.",
        "Keep Artifact Definition pages, discovery surfaces, and contributor instructions aligned to the same Artifact Specification version.",
        "Use the Artifact Specification to define the shared metadata, attribution, confidentiality, and conformance summary instead of duplicating those rules inconsistently in Document Role or launcher prompts.",
        "Publish an exact canonical file inventory whenever an Artifact Definition bundle contains multiple schemas, manifests, or examples, and state what each file validates or governs.",
        "Author Artifact Definitions so definitive properties such as language, meta.status, date or date-time handling, exact counts, conditional section gates, fixed enumerations, and canonical publication files are expressed in schema logic or exact bundle metadata whenever they are knowable at publication time."
      ]
    },
    "artifactGroups": [
      {
        "key": "normative-artifacts",
        "title": "Normative Artifacts",
        "items": [
          {
            "id": "artifact-specification-document",
            "title": "Artifact Specification document",
            "role": "artifact-specification",
            "publicationClass": "normative",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/artifact-specification/v1.0.0/artifact-specification.json"
          }
        ]
      },
      {
        "key": "related-artifacts",
        "title": "Related Artifacts",
        "items": [
          {
            "id": "document-role-specifications-index",
            "title": "Document Role index",
            "role": "related-index",
            "publicationClass": "supporting",
            "mediaType": "text/html",
            "url": "https://www.cuddler.dev/standards/document-role/"
          },
          {
            "id": "artifact-definitions-index",
            "title": "Artifact Definitions index",
            "role": "related-index",
            "publicationClass": "supporting",
            "mediaType": "text/html",
            "url": "https://www.cuddler.dev/standards/artifact-definitions/"
          }
        ]
      }
    ],
    "sectionSummaries": [
      {
        "key": "overview",
        "title": "Overview",
        "summary": "Defines the shared Artifact Definition authoring brief and makes the Document Role, not this specification, responsible for domain meaning."
      },
      {
        "key": "scope",
        "title": "Scope",
        "summary": "Separates domain classification from the shared metadata, publication, attribution, and confidentiality rules every drafted Artifact Definition must inherit."
      },
      {
        "key": "implementation",
        "title": "Implementation",
        "summary": "Identifies the governing-document metadata, source URL, exact schema-file inventory, and definitive schema language that must appear in every drafted Artifact Definition, including fixed metadata values and exact cardinality rules when knowable."
      },
      {
        "key": "validation",
        "title": "Validation",
        "summary": "Requires page metadata, machine-readable bundle metadata, published schema-file inventories, and any published examples to stay aligned to one governing Document Role and this shared Artifact Specification while keeping knowable constraints fixed in schema logic."
      },
      {
        "key": "artifacts",
        "title": "Artifacts",
        "summary": "Points to the canonical Artifact Specification JSON source that assistants and implementers should cite while drafting."
      },
      {
        "key": "security",
        "title": "Security",
        "summary": "Preserves the confidentiality default for real Artifact Documents even when public standards or user-provided examples are involved in drafting."
      },
      {
        "key": "change-management",
        "title": "Change Management",
        "summary": "Explains how shared authoring rules evolve across versions without changing which document owns domain-specific meaning."
      },
      {
        "key": "references",
        "title": "References",
        "summary": "Points drafters to the published Document Roles that supply the domain-specific rules missing from this shared specification."
      }
    ],
    "references": {
      "normative": [
        {
          "title": "Workflow Document Role concept",
          "locator": "https://www.cuddler.dev/standards/document-role/process/"
        },
        {
          "title": "Data Document Document Role concept",
          "locator": "https://www.cuddler.dev/standards/document-role/data/"
        },
        {
          "title": "Template Document Role concept",
          "locator": "https://www.cuddler.dev/standards/document-role/template/"
        }
      ],
      "informative": [
        {
          "title": "Artifact Definitions index",
          "locator": "https://www.cuddler.dev/standards/artifact-definitions/"
        }
      ]
    }
  }
}