Community ExplorationSchemaFirst Standards Repository

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.

View on GitHub Discovery Endpoint

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:

Visual identity systems

Brand guidelines

Content standards

Accessibility requirements

Legal requirements

Asset repositories

Design systems

Institutional knowledge

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

GET /.well-known/brand-card.json

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.

Example: https://example.com/.well-known/brand-card.json

Agent Discovery Integration

Organizations that publish an agent discovery file may reference their Brand Card as an extension:

{
  "name": "Example Agent",
  "description": "Agent metadata for Example Company.",
  "extensions": {
    "brand-card": {
      "url": "https://example.com/.well-known/brand-card.json",
      "version": "1.0",
      "required": false
    }
  }
}

Serialization Formats

JSON (preferred)YAML (supported)

Guiding 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

Future Brand Schema specifications are expected to classify categories and values using requirement levels. These help publishers, consumers, validators, and AI systems understand the relative importance of information.

Required

The value must be supplied by the publisher.

Recommended

The value should be supplied by the publisher when available.

Optional

The value may be supplied by the publisher.

Prohibited

The value or behavior should not be present.

Schema Definition

The Brand Schema defines severity levels and category specifications for Brand Cards.

{
  "standard": "Brand Schema",
  "version": "0.1",

  "severity_levels": {
    "required": {
      "description": "Failure must block a pass.",
      "blocks_pass": true
    },
    "recommended": {
      "description": "Advisory. Failure is noted but does not block a pass.",
      "blocks_pass": false
    },
    "optional": {
      "description": "Lowest priority. Downstream may allow pass-with-optional-fails.",
      "blocks_pass": false
    },
    "prohibited": {
      "description": "Presence or failure blocks a pass.",
      "blocks_pass": true,
      "failure_reason": "blockedByProhibited"
    }
  },

  "categories": [
    {
      "category": "brand.name",
      "type": "string",
      "severity": "required",
      "standard_default": null,
      "description": "Public-facing brand name."
    },
    {
      "category": "brand.website",
      "type": "uri",
      "severity": "recommended",
      "standard_default": null,
      "description": "Primary website for the organization."
    },
    {
      "category": "logos.primary",
      "type": "uri",
      "severity": "required",
      "standard_default": null,
      "description": "Primary logo asset."
    },
    {
      "category": "typography.body_font",
      "type": "array[string]",
      "severity": "recommended",
      "standard_default": ["Arial", "Helvetica", "sans-serif"],
      "description": "Preferred body font stack."
    },
    {
      "category": "voice.tone",
      "type": "array[string]",
      "severity": "recommended",
      "standard_default": ["professional", "clear"],
      "description": "Short descriptors representing the brand voice."
    }
  ]
}

Severity Levels

required- blocks pass on failure
recommended- advisory only
optional- lowest priority
prohibited- blocks pass if present

Category Properties

category - dot-notation path
type - string, uri, array[string], etc.
severity - requirement level
standard_default - fallback value
description - human-readable purpose

Standard Defaults

Future Brand Schema specifications may define Standard Defaults for categories included in the standard. Standard Defaults are community-maintained recommendations that may be used by consuming systems when a publisher does not provide a value.

Examples may include:

Common web-safe font stacks
Accessibility targets
Reading levels
Image aspect ratios
Other broadly accepted defaults

Standard Defaults are part of the Brand Schema specification and are not stored within Brand Cards. Whether a consuming system uses Standard Defaults remains an implementation decision.

Areas for Community Exploration

The following topics remain intentionally open for discussion:

Information models

Schema design

Category definitions

Required fields

Recommended fields

Optional fields

Prohibited values

Standard Defaults

Validation models

Extension mechanisms

Branching strategies

Compatibility profiles

Security considerations

Discovery enhancements

Certification models

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:

Design systemscan consume it

Marketing systemscan consume it

AI systemscan consume it

Validation systemscan consume 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.

Contribute on GitHub Join a Working Group