brand.json Specification

Version 1.0 — A portable, machine-readable standard for brand identity in the age of AI.

Overview

brand.json is a structured file format that allows brands to define their visual identity, voice, and guidelines in a way that AI tools, ad platforms, and creative software can programmatically understand and apply.

File location: https://yourbrand.com/brand.json

MIME type: application/json

Schema Structure

Root Object

Field	Type	Required	Description
$schema	string	Yes	Schema version URL
version	string	Yes	Your brand file version (semver)
brand	object	Yes	Core brand metadata
colors	object	Yes	Color palette definitions
typography	object	Yes	Font and type scale
logos	object	Yes	Logo asset references
voice	object	Yes	Tone, personality, and language

brand (required)

Example

{
  "brand": {
    "name": "Acme Corporation",
    "tagline": "Building tomorrow, today.",
    "description": "Acme Corporation is a sustainable construction company focused on modular, eco-friendly building solutions.",
    "industry": "Construction / Sustainability",
    "founded": "2019",
    "website": "https://acmecorp.com"
  }
}

Field	Type	Required	Description
name	string	Yes	Legal or public brand name
tagline	string	No	Primary tagline or slogan
description	string	Yes	1-3 sentence brand description
industry	string	No	Primary industry or category
founded	string	No	Year founded
website	string	No	Primary website URL

colors (required)

Colors use hex format. Semantic naming ensures AI understands intent, not just values.

Example

{
  "colors": {
    "primary": {
      "hex": "#2D5A27",
      "name": "Forest Green",
      "usage": "Primary brand color. Use for headlines, CTAs, and key UI elements."
    },
    "secondary": {
      "hex": "#8B4513",
      "name": "Warm Earth",
      "usage": "Secondary accent. Use for supporting elements and warmth."
    },
    "accent": {
      "hex": "#F4A460",
      "name": "Sandy Gold",
      "usage": "Highlight color. Use sparingly for emphasis."
    },
    "background": {
      "light": "#FAFAF8",
      "dark": "#1A1A1A"
    },
    "text": {
      "primary": "#1A1A1A",
      "secondary": "#4A4A4A",
      "onDark": "#FAFAF8"
    }
  }
}

Field	Type	Required	Description
primary	object	Yes	Primary brand color with hex, name, and usage
secondary	object	No	Secondary brand color
accent	object	No	Accent/highlight color
background	object	Yes	Background colors (light/dark)
text	object	Yes	Text colors for various contexts

typography (required)

Example

{
  "typography": {
    "primary": {
      "family": "Inter",
      "weights": [400, 500, 600, 700],
      "source": "google",
      "usage": "Headlines and UI elements"
    },
    "secondary": {
      "family": "Merriweather",
      "weights": [400, 700],
      "source": "google",
      "usage": "Body copy"
    },
    "fallback": "system-ui, -apple-system, sans-serif",
    "scale": {
      "base": "16px",
      "ratio": 1.25,
      "note": "Minor third scale for harmonious hierarchy"
    }
  }
}

Field	Type	Required	Description
primary	object	Yes	Primary typeface with family, weights, and source
secondary	object	No	Secondary typeface
fallback	string	Yes	System fallback stack
scale	object	No	Type scale preferences

Source values: "google", "adobe", "custom", "system"

logos (required)

Example

{
  "logos": {
    "primary": {
      "url": "https://acmecorp.com/assets/logo-primary.svg",
      "format": "svg",
      "background": "light",
      "usage": "Default logo for most applications"
    },
    "icon": {
      "url": "https://acmecorp.com/assets/icon.svg",
      "format": "svg",
      "minSize": "32px",
      "usage": "Favicon, app icon, small applications"
    },
    "darkMode": {
      "url": "https://acmecorp.com/assets/logo-dark.svg",
      "format": "svg",
      "background": "dark"
    }
  }
}

Field	Type	Required	Description
primary	object	Yes	Primary logo variant with URL, format, and background
wordmark	object	No	Text-only logo
icon	object	No	Square icon/symbol
darkMode	object	No	Logo for dark backgrounds

voice (required)

This is the most critical section for AI applications. Be specific and provide examples.

Example

{
  "voice": {
    "personality": [
      "Confident but not arrogant",
      "Expert yet accessible",
      "Optimistic and forward-looking",
      "Warm and human"
    ],
    "tone": {
      "default": "Professional and approachable",
      "formal": "When discussing technical specifications or legal matters",
      "casual": "Social media and community engagement"
    },
    "principles": [
      "Lead with benefits, not features",
      "Use active voice",
      "Avoid jargon unless speaking to industry professionals",
      "Be concise—respect the reader's time"
    ],
    "vocabulary": {
      "preferred": ["sustainable", "innovative", "community", "future-ready"],
      "avoid": ["cheap", "disruption", "synergy", "leverage"]
    },
    "examples": {
      "headline": {
        "good": "Build smarter. Live better.",
        "bad": "Revolutionary disruption in construction!"
      },
      "cta": {
        "good": "Start your project",
        "bad": "Click here now!!!"
      }
    }
  }
}

Field	Type	Required	Description
personality	array	Yes	3-5 personality traits
tone	object	Yes	Tone guidance by context
principles	array	Yes	Writing principles
vocabulary	object	No	Preferred and avoided words
examples	object	Yes	Good/bad examples by content type

Implementation Notes

For AI Tools

When consuming a brand.json file, prioritize:

Voice examples — These are the most actionable for content generation
Color semantics — Use the usage field to understand context
Vocabulary guidance — Respect preferred/avoided word lists

For Ad Platforms

Validate against schema before ingestion
Surface missing required fields to users
Use logo background hints for placement decisions

For Brands

Host at your domain root for discoverability
Version your file when making updates
Include rich examples in the voice section — AI learns from examples

Roadmap (Future Versions)

v1.1: Imagery style guidelines (photography vs illustration, mood, subjects)
v1.2: Motion/animation principles
v1.3: Audio identity (sonic logos, music preferences)
v2.0: Multi-brand support, sub-brand inheritance

This specification is maintained by AI Meet Brand. Contributions welcome.