{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/1.0.0/data.schema.json",
  "title": "Brand Guide Data Schema",
  "cuddler": {
    "specVersion": "1.0.0",
    "documentTypeId": "brand-guide",
    "schemaVersion": "1.0.0",
    "output": {
      "primaryContentType": "text/markdown",
      "supportedContentTypes": [
        "text/markdown",
        "application/pdf"
      ]
    },
    "profile": {
      "id": "brand-guide",
      "version": "1.0.0",
      "for-ai": [
        {
          "instruction": "Explain what this Cuddler schema profile governs so AI consumers understand when to use this schema family.",
          "input": "",
          "output": "Brand Guide data-and-template schema family for publishing stable brand guidance artifacts."
        }
      ]
    },
    "schemaLinks": [
      {
        "rel": "related",
        "targetSchema": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/1.0.0/template.schema.json",
        "targetDocumentTypeId": "brand-guide",
        "for-ai": [
          {
            "instruction": "Explain why this related schema is linked here and when an AI consumer should follow it.",
            "input": "",
            "output": "Use the paired Brand Guide template schema when validating or rendering the companion template document for the same artifact family."
          }
        ]
      }
    ],
    "artifactType": "Brand Guide",
    "status": "Public normative publication",
    "publisher": "TrackThat Inc.",
    "sourceUrl": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/",
    "attributionNotice": "\u00a9 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/.",
    "governingDomainSpecification": {
      "title": "Data Document Role",
      "url": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/"
    },
    "governingArtifactSpecification": {
      "title": "Cuddler Artifact Specification",
      "version": "1.0.0",
      "url": "https://www.cuddler.dev/standards/artifact-specification/v1.0.0/"
    }
  },
  "$ref": "#/$defs/Root",
  "$defs": {
    "Root": {
      "allOf": [
        {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/CuddlerDocument"
        },
        {
          "type": "object",
          "properties": {
            "$schema": {
              "type": "string",
              "format": "uri",
              "const": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/1.0.0/data.schema.json",
              "for-ai": [
                {
                  "instruction": "Use this guidance when preparing a valid value for this schema node.",
                  "input": "",
                  "output": "Absolute URI of this immutable Brand Guide Data Schema."
                }
              ]
            },
            "meta": {
              "allOf": [
                {
                  "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Meta"
                },
                {
                  "type": "object",
                  "properties": {
                    "schemaVersion": {
                      "const": "1.0.0",
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Schema version for the Brand Guide document family."
                        }
                      ]
                    },
                    "documentTypeId": {
                      "const": "brand-guide",
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Stable document type identifier for Brand Guide."
                        }
                      ]
                    },
                    "title": {
                      "type": "string",
                      "minLength": 1,
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Reader-facing title for the guide."
                        }
                      ]
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "final",
                        "deprecated"
                      ],
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Lifecycle status of the guide."
                        }
                      ]
                    },
                    "language": {
                      "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/LanguageTag",
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Primary simplified Cuddler language tag for the guide."
                        }
                      ]
                    },
                    "summary": {
                      "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString",
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Short summary explaining the brand promise and the intended scope of the guide."
                        }
                      ]
                    }
                  }
                }
              ]
            },
            "content": {
              "allOf": [
                {
                  "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Content"
                },
                {
                  "type": "object",
                  "required": [
                    "sections",
                    "documentModel"
                  ],
                  "properties": {
                    "sections": {
                      "type": "array",
                      "minItems": 5,
                      "items": {
                        "oneOf": [
                          {
                            "title": "Overview",
                            "allOf": [
                              {
                                "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Section"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "const": "overview",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Section key for the opening overview."
                                      }
                                    ]
                                  },
                                  "heading": {
                                    "const": "Overview",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Displayed heading for the overview section."
                                      }
                                    ]
                                  },
                                  "blocks": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                      "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/TextBlock"
                                    },
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Narrative overview content for the guide."
                                      }
                                    ]
                                  }
                                }
                              }
                            ],
                            "for-ai": [
                              {
                                "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                "input": "",
                                "output": "Introduce the brand and summarize the primary promise in one or more text blocks."
                              }
                            ]
                          },
                          {
                            "title": "Core Principles",
                            "allOf": [
                              {
                                "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Section"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "const": "core-principles",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Section key for the core principles section."
                                      }
                                    ]
                                  },
                                  "heading": {
                                    "const": "Core Principles",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Displayed heading for the core principles section."
                                      }
                                    ]
                                  },
                                  "blocks": {
                                    "type": "array",
                                    "minItems": 2,
                                    "items": {
                                      "oneOf": [
                                        {
                                          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/TextBlock"
                                        },
                                        {
                                          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/TableBlock"
                                        }
                                      ]
                                    },
                                    "allOf": [
                                      {
                                        "contains": {
                                          "type": "object",
                                          "required": [
                                            "kind"
                                          ],
                                          "properties": {
                                            "kind": {
                                              "const": "table"
                                            }
                                          }
                                        },
                                        "minContains": 1
                                      }
                                    ],
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Supporting narrative plus a table that summarises the core principles."
                                      }
                                    ]
                                  }
                                }
                              }
                            ],
                            "for-ai": [
                              {
                                "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                "input": "",
                                "output": "Explain the brand principles using supporting narrative and a structured table."
                              }
                            ]
                          },
                          {
                            "title": "Voice",
                            "allOf": [
                              {
                                "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Section"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "const": "voice",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Section key for voice and tone guidance."
                                      }
                                    ]
                                  },
                                  "heading": {
                                    "const": "Voice",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Displayed heading for the voice section."
                                      }
                                    ]
                                  },
                                  "blocks": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                      "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/BulletsBlock"
                                    },
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "One or more bullets blocks describing the voice attributes."
                                      }
                                    ]
                                  }
                                }
                              }
                            ],
                            "for-ai": [
                              {
                                "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                "input": "",
                                "output": "List the voice attributes that should shape brand writing and presentation."
                              }
                            ]
                          },
                          {
                            "title": "Applications",
                            "allOf": [
                              {
                                "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Section"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "const": "applications",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Section key for brand applications."
                                      }
                                    ]
                                  },
                                  "heading": {
                                    "const": "Applications",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Displayed heading for the applications section."
                                      }
                                    ]
                                  },
                                  "blocks": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                      "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/BulletsBlock"
                                    },
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "One or more bullets blocks describing brand applications."
                                      }
                                    ]
                                  }
                                }
                              }
                            ],
                            "for-ai": [
                              {
                                "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                "input": "",
                                "output": "List the principal applications where the brand system must remain consistent."
                              }
                            ]
                          },
                          {
                            "title": "Audiences",
                            "allOf": [
                              {
                                "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/Section"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "const": "audiences",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Section key for audience guidance."
                                      }
                                    ]
                                  },
                                  "heading": {
                                    "const": "Audiences",
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Displayed heading for the audiences section."
                                      }
                                    ]
                                  },
                                  "blocks": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                      "oneOf": [
                                        {
                                          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/TextBlock"
                                        },
                                        {
                                          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/BulletsBlock"
                                        }
                                      ]
                                    },
                                    "for-ai": [
                                      {
                                        "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                        "input": "",
                                        "output": "Narrative or bullets content describing the intended audiences."
                                      }
                                    ]
                                  }
                                }
                              }
                            ],
                            "for-ai": [
                              {
                                "instruction": "Use this guidance when preparing a valid value for this schema node.",
                                "input": "",
                                "output": "Describe the core audiences and what resonates with each one."
                              }
                            ]
                          }
                        ]
                      },
                      "allOf": [
                        {
                          "contains": {
                            "type": "object",
                            "required": [
                              "key"
                            ],
                            "properties": {
                              "key": {
                                "const": "overview"
                              }
                            }
                          },
                          "minContains": 1
                        },
                        {
                          "contains": {
                            "type": "object",
                            "required": [
                              "key"
                            ],
                            "properties": {
                              "key": {
                                "const": "core-principles"
                              }
                            }
                          },
                          "minContains": 1
                        },
                        {
                          "contains": {
                            "type": "object",
                            "required": [
                              "key"
                            ],
                            "properties": {
                              "key": {
                                "const": "voice"
                              }
                            }
                          },
                          "minContains": 1
                        },
                        {
                          "contains": {
                            "type": "object",
                            "required": [
                              "key"
                            ],
                            "properties": {
                              "key": {
                                "const": "applications"
                              }
                            }
                          },
                          "minContains": 1
                        },
                        {
                          "contains": {
                            "type": "object",
                            "required": [
                              "key"
                            ],
                            "properties": {
                              "key": {
                                "const": "audiences"
                              }
                            }
                          },
                          "minContains": 1
                        }
                      ],
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Top-level brand-guide sections in reader-facing order."
                        }
                      ]
                    },
                    "documentModel": {
                      "$ref": "#/$defs/BrandGuideModel",
                      "for-ai": [
                        {
                          "instruction": "Use this guidance when preparing a valid value for this schema node.",
                          "input": "",
                          "output": "Required structured brand-guide facts that provide stable render targets for paired templates, including overview text, principles, voice attributes, applications, audiences, and logo visibility."
                        }
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    },
    "AudienceFact": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "hook",
        "painPoints"
      ],
      "properties": {
        "name": {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Audience segment name."
            }
          ]
        },
        "hook": {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Primary message or hook that resonates with this audience."
            }
          ]
        },
        "painPoints": {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Primary pain points or constraints this audience faces."
            }
          ]
        }
      },
      "for-ai": [
        {
          "instruction": "Use this guidance when preparing a valid value for this schema node.",
          "input": "",
          "output": "Stable audience fact record used by paired templates to repeat audience cards deterministically."
        }
      ]
    },
    "BrandGuideModel": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "overviewSummary",
        "corePrinciples",
        "voiceAttributes",
        "applications",
        "audiences",
        "hasPrimaryLogo"
      ],
      "properties": {
        "overviewSummary": {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Canonical overview summary for the guide."
            }
          ]
        },
        "corePrinciples": {
          "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/TableBlock",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Canonical table block summarizing the brand's core principles."
            }
          ]
        },
        "voiceAttributes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString"
          },
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Ordered list of voice attributes for direct list rendering."
            }
          ]
        },
        "applications": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "https://www.cuddler.dev/standards/document-role/data/v1.0.0/cuddler.base.defs.schema.1.0.0.json#/$defs/NonEmptyString"
          },
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Ordered list of primary applications where the brand system should remain consistent."
            }
          ]
        },
        "audiences": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceFact"
          },
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Stable audience records that paired templates may repeat over deterministically."
            }
          ]
        },
        "hasPrimaryLogo": {
          "type": "boolean",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Whether the paired template should render the primary logo section."
            }
          ]
        }
      },
      "for-ai": [
        {
          "instruction": "Use this guidance when preparing a valid value for this schema node.",
          "input": "",
          "output": "Stable structured facts for the brand guide. Paired templates SHOULD bind to these fields instead of relying on section or block array positions."
        }
      ]
    }
  },
  "for-ai": [
    {
      "instruction": "Use this guidance when preparing a valid value for this schema node.",
      "input": "",
      "output": "Use this schema to generate concise brand guide documents that define a brand promise, voice, applications, audiences, and logo guidance in a structured format that can be validated and rendered consistently."
    }
  ]
}