{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://brandspec.org/schema/v0.1/brandspec.json", "title": "BrandSpec", "description": "An open standard for machine-readable brand definitions. Defines tokens, assets, voice, strategy, and purpose in a single canonical JSON document.", "type": "object", "required": ["brand", "version"], "properties": { "$schema": { "type": "string", "format": "uri", "description": "URI of the BrandSpec schema used to validate this document." }, "version": { "type": "string", "description": "BrandSpec schema version this document conforms to.", "example": "0.1.0" }, "_export": { "type": "object", "description": "Export metadata generated by the tool that produced this file.", "properties": { "brandName": { "type": "string", "description": "Name of the brand at time of export." }, "brandSpecVersion": { "type": "string", "description": "BrandSpec version used at export time." }, "exportedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of export." } } }, "brand": { "type": "object", "description": "The root brand definition object.", "properties": { "metadata": { "type": "object", "description": "Administrative metadata for this brand record.", "properties": { "name": { "type": "string", "description": "Canonical brand name." }, "version": { "type": "string", "description": "Brand record version string." }, "lastUpdated": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of last update." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Arbitrary tags for filtering or categorisation." } } }, "tokens": { "type": "object", "description": "Design tokens: the visual primitives of the brand.", "properties": { "colors": { "type": "array", "description": "The brand colour palette.", "items": { "type": "object", "required": ["name", "role", "hex"], "properties": { "name": { "type": "string", "description": "Human-readable colour name, e.g. 'Blue', 'Primary', 'Accent'." }, "role": { "type": "string", "enum": ["primary", "secondary", "accent", "neutral", "background", "surface", "error", "success", "warning"], "description": "Semantic role of this colour in the brand system." }, "primarySpace": { "type": "string", "enum": ["rgb", "cmyk"], "description": "The authoritative colour space for this colour. Use 'rgb' for screen-first brands, 'cmyk' for print-first brands." }, "hex": { "type": "string", "pattern": "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$", "description": "Hex colour value including leading #." }, "rgb": { "type": "object", "description": "RGB colour channels.", "properties": { "r": { "type": "integer", "minimum": 0, "maximum": 255 }, "g": { "type": "integer", "minimum": 0, "maximum": 255 }, "b": { "type": "integer", "minimum": 0, "maximum": 255 } }, "required": ["r", "g", "b"] }, "cmyk": { "type": "object", "description": "CMYK colour channels as percentages 0–100.", "properties": { "c": { "type": "integer", "minimum": 0, "maximum": 100 }, "m": { "type": "integer", "minimum": 0, "maximum": 100 }, "y": { "type": "integer", "minimum": 0, "maximum": 100 }, "k": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": ["c", "m", "y", "k"] } } } }, "typography": { "type": "array", "description": "Typography styles for each semantic role.", "items": { "type": "object", "required": ["name", "role", "family"], "properties": { "name": { "type": "string", "description": "Human-readable name for this type style, e.g. 'Headings', 'Body'." }, "role": { "type": "string", "enum": ["heading", "body", "caption", "mono", "display", "label"], "description": "Semantic role of this type style." }, "family": { "type": "string", "description": "Font family name as it would appear in a CSS font-family declaration." }, "fallback": { "type": "string", "description": "CSS generic font family fallback, e.g. 'sans-serif', 'serif', 'monospace'." }, "weights": { "type": "array", "items": { "type": "integer", "minimum": 100, "maximum": 900, "multipleOf": 100 }, "description": "Numeric font weights used for this role." }, "fontColor": { "type": "string", "pattern": "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$", "description": "Default text colour for this role as a hex value." }, "lineHeight": { "type": "string", "description": "Unitless line height multiplier, e.g. '1.5'." }, "sizes": { "type": "object", "description": "Recommended font size in pixels.", "properties": { "recommended": { "type": "number", "description": "Base recommended size in pixels." }, "min": { "type": "number", "description": "Minimum size in pixels (for fluid scaling)." }, "max": { "type": "number", "description": "Maximum size in pixels (for fluid scaling)." } } } } } } } }, "assets": { "type": "object", "description": "Brand asset references, primarily logos.", "properties": { "logos": { "type": "array", "description": "Logo variants for different contexts.", "items": { "type": "object", "required": ["id", "name", "path", "format", "variant"], "properties": { "id": { "type": "string", "description": "Unique identifier for this logo asset." }, "name": { "type": "string", "description": "Human-readable name, e.g. 'Primary Logo', 'Logo Icon'." }, "path": { "type": "string", "format": "uri", "description": "URL to the hosted logo file." }, "format": { "type": "string", "enum": ["svg", "png", "webp", "jpg"], "description": "File format of the logo asset." }, "variant": { "type": "string", "enum": ["horizontal", "stacked", "icon", "wordmark"], "description": "Layout variant of this logo." }, "colorMode": { "type": "string", "enum": ["full-color-rgb", "full-color-cmyk", "single-color", "grayscale", "white", "black"], "description": "Colour mode of this logo variant." }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary logo for general use." }, "dimensions": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "unit": { "type": "string", "enum": ["px", "mm", "pt"] } } } } } } } }, "voice": { "type": "object", "description": "Brand voice and tone of communication.", "properties": { "tone": { "type": "array", "items": { "type": "string" }, "description": "Tone descriptors, e.g. ['confident', 'clear', 'human']. Consumed by content tools and AI to calibrate output." }, "tagline": { "type": "string", "description": "The brand's primary tagline or strapline." } } }, "strategy": { "type": "object", "description": "Brand strategy: positioning, mission, vision, values, and audience.", "properties": { "mission": { "type": "string", "description": "What the brand does and for whom. Present tense, action-oriented." }, "vision": { "type": "string", "description": "The future state the brand is working toward." }, "brandPromise": { "type": "string", "description": "The core commitment the brand makes to its audience." }, "brandEssence": { "type": "array", "items": { "type": "string" }, "description": "Two or three words that capture the essence of the brand." }, "archetype": { "type": "string", "enum": ["innocent", "sage", "explorer", "outlaw", "magician", "hero", "lover", "jester", "everyman", "caregiver", "ruler", "creator"], "description": "Brand archetype from the 12-archetype framework." }, "values": { "type": "array", "description": "Core brand values with observable behaviours.", "items": { "type": "object", "required": ["name", "description"], "properties": { "name": { "type": "string", "description": "Value name." }, "description": { "type": "string", "description": "What this value means in practice for this brand." }, "behaviors": { "type": "array", "items": { "type": "string" }, "description": "Observable behaviours that demonstrate this value." } } } }, "targetAudience": { "type": "object", "properties": { "primary": { "type": "string", "description": "Description of the primary target audience." }, "secondary": { "type": "string", "description": "Description of any secondary audience." } } }, "positioning": { "type": "object", "description": "Brand positioning statement components.", "properties": { "forTarget": { "type": "string" }, "whoNeed": { "type": "string" }, "brandIs": { "type": "string" }, "thatProvides": { "type": "string" }, "unlike": { "type": "string" }, "weBecause": { "type": "string" } } }, "differentiators": { "type": "array", "items": { "type": "string" }, "description": "What makes this brand distinctly different." }, "reasonsToBelieve": { "type": "array", "items": { "type": "string" }, "description": "Evidence that supports the brand promise." }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "positioning": { "type": "string" }, "weakness": { "type": "string" } } } } } }, "purpose": { "type": "object", "description": "The brand's reason for existing beyond commercial activity.", "properties": { "statement": { "type": "string", "description": "A clear statement of why this brand exists beyond profit." }, "sdgAlignment": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 17 }, "description": "UN Sustainable Development Goal indices (1–17) that this brand's purpose aligns with." }, "metrics": { "type": "array", "description": "How the brand measures its positive impact.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "unit": { "type": "string" }, "description": { "type": "string" }, "measurementFrequency": { "type": "string", "enum": ["daily", "weekly", "monthly", "quarterly", "annually"] }, "verificationStatus": { "type": "string", "enum": ["verified", "unverified", "pending"] } } } } } } } } } }