Brand Schema
An open, interoperable approach to publishing organizational identity in a machine-readable format. Brand Schema provides a common foundation that allows brand systems, design systems, and AI systems to interoperate.
Brand Schema is the standard; a brand publishes a Brand Card at /.well-known/brand-card.json. Version 1.0.0 is open for comment through 22 October 2026 — it is not frozen. File comments as GitHub issues on the repository.
Brand Schema is licensed under the Apache License 2.0. Anyone may implement, fetch, and serve Brand Cards in a commercial product with no additional SchemaFirst license. SchemaFirst and Brand Card are trademarks.
Purpose
Organizations increasingly rely on software platforms, automated systems, artificial intelligence, agencies, contractors, and distributed teams to create content, experiences, communications, and customer interactions.
The information that defines organizational identity is often distributed across many systems and documents, making it difficult to discover, share, maintain, and apply consistently.
Brand Schema exists to explore an open, interoperable approach to publishing organizational identity in a machine-readable format.
The goal is not to replace existing brand systems, design systems, governance programs, content standards, or asset management platforms.
The goal is to provide a common foundation that allows those systems to interoperate.
Problem Space
Organizational identity is typically represented through a combination of:
These resources are frequently fragmented across platforms, teams, vendors, and technologies. As automation and AI become more prevalent, organizations increasingly need a portable and machine-readable representation of this information.
Without a common approach:
- ×Organizational context must be recreated repeatedly.
- ×Brand consistency becomes difficult to maintain.
- ×Validation becomes difficult to automate.
- ×Identity information becomes trapped within individual platforms.
- ×Interoperability suffers.
Core Decisions
Standard Name
Brand Schema
Brand Schema is the name of the standard and associated specifications.
Published Artifact
Brand Card
Organizations publish a Brand Card. Consumers retrieve and process Brand Cards. A Brand Card contains only values explicitly declared by the publishing organization.
Discovery Endpoint
Organizations may publish their Brand Card at this location. Marketing systems, design systems, software applications, validation systems, and AI systems should use this location as the canonical discovery endpoint.
https://example.com/.well-known/brand-card.jsonReciprocal References
The Brand Card is one file in a small family of discovery documents. When a brand publishes a /.well-known/brand.json or /.well-known/agent-card.json, those files point in to the card, and the card may point back out. The card never pastes in parent or sub-brand trees.
brand.json / agent-card.json point in:
{
"brand-card": "https://example.com/.well-known/brand-card.json"
}brand-card.json points out:
{
"identity": {
"brand-json": "https://example.com/.well-known/brand.json"
},
"metadata": {
"agent-card": {
"url": "https://example.com/.well-known/agent-card.json"
}
}
}Serialization Format
Brand Cards are published as JSON. Design-token value formats (for example DTCG token values) are not the Brand Card format in this version.
JSONGuiding Principles
Any future specifications developed under Brand Schema should strive to be:
Open
Freely implementable and publicly documented.
Interoperable
Usable across organizations, tools, and platforms.
Discoverable
Easy for consumers to locate and retrieve.
Extensible
Capable of supporting future requirements without fragmentation.
Practical
Focused on solving real-world problems.
Durable
Designed to remain useful despite changes in vendors, technologies, or implementation approaches.
Requirement Levels
Brand Schema classifies fields using requirement levels so publishers, consumers, validators, and AI systems understand the relative importance of information.
The value must be supplied by the publisher.
The value should be supplied by the publisher when available.
The value may be supplied by the publisher.
Validation is advisory.A validator reports which recommended or optional fields are missing, but it must not block a brand from publishing its card. There is no “prohibited” level and no failure that blocks a pass.
Brand Card Example
A Brand Card carries only the values the brand explicitly declared. Field names are canonical and kebab-case. Nested paths follow the order application › mode › element › state › attribute; the default presentation omits the mode segment.
{
"metadata": {
"card-version": "1.0.0",
"conforms-to": "https://www.schemafirst.org/spec/1.0",
"updated-at": "2026-07-20T14:30:00Z",
"publisher": "Example Company"
},
"identity": {
"name": "Example Company",
"description": "Open standards for publishing organizational identity.",
"audience": ["Product teams", "Brand agencies"],
"brand-json": "https://example.com/.well-known/brand.json"
},
"logo": {
"primary": { "url": "https://example.com/assets/logo.svg" }
},
"color": {
"primary": "#0066ff",
"background": "#0b0b12",
"font": "#f5f5f7"
},
"typography": {
"heading": { "font-family": ["Inter", "sans-serif"] },
"body": { "font-family": ["Inter", "sans-serif"] }
},
"voice": {
"tone": {
"required": ["clear", "professional"],
"recommended": ["approachable"]
},
"key-message": "Publish brand decisions once; every system starts from the same source."
},
"email": {
"dark-mode": {
"hyperlink": {
"unvisited": {
"font-color": "#8ab4ff"
}
}
}
}
}Severity-classified values
Some fields classify their values — not the field — using the shared severity vocabulary. voice.tone groups words the brand must use, should use, may use, or must avoid.
- required
- recommended
- optional
- prohibited
Path Organization
Paths read left to right as application › mode › element › state › attribute.
email.dark-mode.hyperlink.unvisited.font-colorAn application object (like email) exists only when the brand supplied a value for that medium. Never copy general color or type into it to look complete.
Publish a Brand Card: the digital minimum
To conform for digital use, a Brand Card supplies the eleven required identity, logo, color, typography, and voice fields, plus the four card-metadata fields. A raster logo.primary is enough for a digital-only card. The exact leaf names are defined by the required field set in the repository.
Card metadata
Four fields, always required.
metadata.card-versionmetadata.conforms-tometadata.updated-atmetadata.publisher
Required field set
Eleven fields across five categories.
- Identity — e.g.
identity.name - Logo — e.g.
logo.primary - Color — e.g.
color.primary - Typography — e.g.
typography.heading.font-family,typography.body.font-family - Voice — e.g.
voice.tone
Print & environment: a CMYK color and a vector logo (SVG, PDF, or EPS) are required whenever a print or environment section exists on the card. Digital-only cards do not need them.
Declared, not resolved
A path on the card is a declared decision. A path that is not on the card is undeclared. There is no resolution walk and no fallback pointer — the standard never tells a consumer to substitute a broader path for a missing narrower one.
Distinct paths, distinct decisions
color.hyperlink and email.hyperlink.unvisited.font-color are two separate fields. Neither one implies or backfills the other; a product chooses which declared fields it applies.
No defaults, no walk-up
Brand Schema ships no default values and defines no compilation or resolved-value step. If a path is absent it is simply undeclared — consumers do not walk up to a broader path such as color.primary.
Publication
A public Brand Card is published at a well-known path following RFC 8615. RFC 2119 keywords below apply only to the Brand Card document and how it is published and fetched.
- Hosts MUST omit nulls, empty strings, empty arrays, empty objects, and placeholders.
- Hosts SHOULD send Cache-Control and ETag (from metadata.card-version or a content hash); clients SHOULD use If-None-Match.
- Consumers MUST ignore keys they do not understand.
- The public well-known file MUST NOT contain secrets.
- When a private card exists, list its authenticated URL as metadata.private-card.url; clients SHOULD NOT then treat the public card as the complete set of decisions.
Discovery
Well-known URI
GET https://{domain}/.well-known/brand-card.json — the canonical discovery path.
Product registries
A directory or marketplace is a product, not part of this standard. Brand Schema does not specify a registry API.
Direct URL
An agency or brand hands a consumer a Brand Card URL, or supplies it through configuration.
Versions
metadata.card-version
The version of this Brand Card file— the brand's own revision of its published decisions.
metadata.conforms-to
The Brand Schema Major.Minor URL the card conforms to. For 1.0.x use https://www.schemafirst.org/spec/1.0. A spec patch does not require card changes.
Areas for Community Exploration
The following topics remain intentionally open for discussion:
The purpose of this effort is to encourage discussion and experimentation before converging on technical implementations.
Success Criteria
The protocol succeeds when organizational identity becomes portable, discoverable, and interoperable.
- Organizations can publish identity information once and make it available to many different systems.
- Consumers can retrieve, understand, validate, and apply that information consistently.
- Publishers don't need to recreate organizational context for every platform.
Long-Term Vision
Make organizational identity portable, discoverable, and interoperable. Organizations publish identity information once, and many different systems can understand and apply it:
The Brand Card serves as the foundational artifact supporting that vision.
Join the Discussion
Brand Schema is developed through the SchemaFirst standards process. Technical details evolve through community review, discussion, and consensus.