brand.json file provides a standardized way for brands to claim their identity and establish discoverable brand information. It supports four mutually exclusive variants to accommodate different use cases.
brand.json is the canonical source of brand identity data. The brand object defined here (logos, colors, tone, tagline) is the single brand definition used across AdCP. Tasks reference brands by domain and brand_id — the system resolves full identity from brand.json or the registry.File location
Brands host thebrand.json file at:
Variants
The brand.json file supports four mutually exclusive variants:1. Authoritative Location Redirect
Points to a hosted brand.json at another URL:- Brand.json is hosted centrally (e.g., by a service provider)
- CDN distribution is needed
- Managed brand services
2. House Redirect
Points to the house domain that contains the full brand portfolio:region: ISO 3166-1 alpha-2 country code (e.g., “CN”)note: Explanation text
- Brand domain is owned by a larger house
- Regional/localized domains point to main house
- Legacy domains redirect to canonical
3. Brand Agent
Designates an MCP agent that provides brand information:contact: Contact information
4. House Portfolio
Contains the full brand hierarchy with all brands and properties:House definition
The house object represents the corporate entity:Brand definition
Each brand in thebrands array:
Names Array
Names are localized with language codes:Keller Types
Brand architecture classifications from marketing theory:Extended color roles
Thecolors object has five standard roles (primary, secondary, accent, background, text), but brands can and should provide additional roles for finer granularity. The schema accepts any additional color role via additionalProperties.
These extended roles help creative agents distinguish between text hierarchies and surface levels without guessing.
Visual guidelines
Thevisual_guidelines object provides structured rules that generative creative systems can use to produce on-brand assets consistently. These are brand constants — they don’t change campaign to campaign.
Visual guidelines complement the basic identity fields (
colors, fonts, logos). Colors define what the brand palette is; visual guidelines define how to use it. Fonts define font families; visual guidelines define the type scale.Photography
Controls how brand photography should look when selected or generated:Graphic style
Defines the visual language for brand graphics and illustrations:flat_illustration, geometric, gradient_mesh, editorial_collage, hand_drawn, minimal_line_art, 3d_render, isometric, photographic_composite.
Shapes
Brand shapes used as part of visual identity:Iconography
Icon style system and usage rules:Composition
Layout rules for overlays, textures, and backgrounds:none, subtle_grain, noise, paper, fabric, concrete. Intensity: low, medium, high.
Background types: solid_color, gradient, blurred_photo, image, video, pattern, transparent.
Border radius
Named border radius presets for UI components and layout elements. Border radius is one of the most visible brand differentiators — generous radii feel warm and approachable, while small or zero radii feel precise and editorial.
Additional named presets can be added beyond the five standard levels.
graphic_style.corner_radius defines a default radius for graphic/illustration elements. border_radius defines a named scale for UI components and layout — buttons, cards, inputs, modals.Elevation
Named shadow levels that define how elements appear to lift off the surface. Brands use elevation as identity — some prefer dramatic multi-layer shadows, others use a single diffuse shadow.box-shadow syntax. Generative systems can apply these directly.
Additional named levels (e.g.,
dropdown, tooltip) can be added.
Spacing
Spacing system for consistent layout rhythm. A base unit plus a named scale enables creative agents to produce correctly-spaced layouts without guessing.
The
scale object supports standard sizes (xs, sm, md, lg, xl, 2xl) and can include additional named values (e.g., 3xl, section).
Graphic elements
Reusable decorative or structural visual elements that are part of the brand identity — torn paper edges, watermarks, dividers, background patterns:Motion
Motion and animation rules for video, animated display, and interactive formats:Logo placement
Logo placement and clear space rules for automated creative production:Colorways
Named color pairings that define how colors work together. Allows a creative brief to reference “use my primary colorway” without specifying every color:Type scale
Typography scale defining sizes and weights for different text roles:font field references font roles defined in the brand’s fonts object ("primary", "secondary"), or can specify a font family name directly.
When sizes are in pixels, use base_width to indicate the reference canvas these sizes were designed for. Generative systems should scale proportionally for other canvas sizes — a 48px heading designed for 1080px width would scale to 14px on a 320px mobile leaderboard.
Asset libraries
References to managed asset libraries (icon sets, illustration systems, image collections). URLs are for human access — a brand portal, press kit, or DAM landing page that a person can open in a browser.
The
color_guide provides generative systems with the color palettes used in the library — useful for producing on-brand illustrations or icons without accessing the library itself.
Restrictions
Visual prohibitions and guardrails — the visual equivalent oftone.donts. These tell generative systems what to avoid:
Property definition
Properties are digital touchpoints associated with brands:Property types
Matches AdCP property-type enum:websitemobile_appctv_appdesktop_appdoohpodcastradiostreaming_audio
Property relationships
Properties default toowned — the brand operates the property directly. For networks and SSPs that sell inventory they don’t own, the relationship field declares the commercial arrangement:
This is the AdCP equivalent of
sellers.json — the operator’s public declaration of which publishers they work with. The publisher confirms by setting the matching delegation_type on the agent’s authorization in their adagents.json. See ad networks for the bilateral verification pattern.
Resolution algorithm
To resolve a domain to a canonical brand:- Fetch
https://{domain}/.well-known/brand.json - Check variant:
- authoritative_location: Fetch from that URL, continue from step 2
- house (string): Fetch from house domain, continue from step 2
- brand_agent: Return agent URL (agent provides brand info)
- house (object) + brands: Search for domain in properties
- For house portfolio, find the brand whose properties contain the query domain
- Return canonical brand information
Complete examples
Small Business
Enterprise with Agent
Multi-Brand Portfolio
Talent Agency with Rights
A talent agency managing athlete brands with licensable rights:rights_agent field tells crawlers what’s licensable without any MCP calls — available uses, rights type, and countries. Buyer agents can search the registry for “Dutch athletes available for voice licensing” and find matches from the indexed brand.json data.
Regional Domain Redirect
Onnike.cn/.well-known/brand.json:
Caching
Recommended cache TTLs:- Canonical files: 24 hours
- Redirect files: 24 hours
- Failed lookups: 1 hour
Best practices
- Start simple: Begin with minimal brand.json and add complexity as needed
- Use redirects for subsidiaries: Point brand domains to house domain
- List all properties: Include regional domains, apps, and legacy domains
- Keep names current: Include localized names and common aliases
- Visual guidelines are optional: Add them when you need generative systems to produce on-brand assets consistently. Start with colorways and restrictions — they have the highest immediate impact.
- Keep portfolios lean: For house portfolios with many brands, include visual guidelines only on brands that need them. Full visual guidelines on every brand in a large portfolio increases file size significantly.