# Schema Overview

**Yuba Schema** is an open, community-governed standard for representing business data optimized for AI platforms.

## What is Yuba Schema?

Think of Yuba Schema as **"schema.org for AI discovery"** — a comprehensive specification that defines how business data should be structured for AI platforms to discover, understand, and reference businesses.

## Why a New Standard?

Traditional business data formats were designed for web search and human browsing:

* **Google Business Profile**: Optimized for Google Search results
* **Yelp API**: Designed for Yelp's platform
* **Schema.org**: Markup for web pages

**Yuba Schema** is purpose-built for AI-native discovery:

* Structured for LLM understanding and reasoning
* Includes AI-exclusive content fields
* Tracks upstream metrics (citations, API calls - see [analytics capabilities](https://github.com/gugga7/aeo/blob/main/docs/ANALYTICS_CAPABILITIES.md))
* Supports discovery intent tracking
* Standard-agnostic (works with any AI platform)

## Core Components

### 1. Entity Schemas

**Business Profile**

* Identity, services, pricing, availability
* Location and service area
* Contact information
* Media (photos, videos, virtual tours)
* AI-exclusive content (insider tips, local secrets)
* Trust signals (verification, ratings)

**Upstream Metrics**

* Impressions (mentions in AI responses)
* Citations (quotes and references)
* Comparisons (side-by-side appearances)
* Zero-click visibility (seen but not clicked)

**Intent Journey**

* Discovery progression
* Citation moments
* Query refinements
* Time to conversion
* Multi-touch attribution

[View complete schema specification →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/core-specification)

### 2. Discovery Interfaces

Platform-agnostic interfaces for AI platforms to discover businesses:

* `search_businesses` - Discovery with filters
* `get_business_details` - Comprehensive profiles
* `compare_businesses` - Side-by-side comparison
* `check_availability` - Real-time availability
* `submit_lead` - Lead generation
* `get_upstream_metrics` - Analytics

[View MCP tool catalog →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/mcp-tools)

### 3. Validation Libraries

Official validators ensure schema compliance:

* **TypeScript**: `@aidp/schema-validator`
* **Python**: `aidp-schema-validator`
* **CLI**: `aidp-validate`

[Learn about validation →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/validation)

### 4. Migration Tools

Convert existing data to AIDP format:

* Google Business Profile migrator
* Yelp API migrator
* Schema.org converter
* Custom migration framework

[View migration guides →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/migrations)

## Key Features

### AI-Optimized Content

**Exclusive Content Fields**:

```json
{
  "aiOptimization": {
    "exclusiveContent": {
      "insiderTips": "Ask for the Ethiopian Yirgacheffe...",
      "localSecrets": "We source beans directly from farmers",
      "behindTheScenes": "We roast every Tuesday morning",
      "sustainabilityPractices": "100% compostable packaging"
    },
    "boostSignals": ["specialty_coffee", "local_roasting"],
    "visibilityScore": 87,
    "uniquenessScore": 92
  }
}
```

### Upstream Analytics

**Track Pre-Click Visibility**:

```json
{
  "impression": {
    "inSummary": true,
    "context": "Mentioned as top-rated local roaster"
  },
  "citation": {
    "count": 3,
    "placement": "primary",
    "context": "Known for single-origin beans..."
  },
  "zeroClick": {
    "impression": true,
    "brandAwarenessValue": 15.50
  }
}
```

### Intent Journeys

**Discovery Tracking**:

```json
{
  "initialQuery": "coffee shops in Portland",
  "refinements": [
    { "query": "with outdoor seating", "turnNumber": 2 },
    { "query": "that roast their own beans", "turnNumber": 3 }
  ],
  "citationMoments": [
    { "placement": "primary", "turnNumber": 4 }
  ],
  "conversion": {
    "converted": true,
    "timeToConversion": 180,
    "conversionType": "lead"
  }
}
```

### Standard-Agnostic

Works with any AI standard or protocol:

* Model Context Protocol (MCP)
* ChatGPT Plugin API
* REST APIs
* GraphQL
* Custom protocols

### Business-Controlled

* Businesses own their data
* Portable across platforms
* No platform lock-in
* Direct relationships with AI platforms

## Design Principles

### 1. Open & Transparent

* Public specification
* Community governance
* Open source reference implementation
* No proprietary extensions

### 2. AI-Native

* Structured for LLM understanding
* Semantic boost signals
* Conversational context
* Intent-based analytics

### 3. Backward Compatible

* Semantic versioning
* Deprecation policy (12-month minimum)
* Migration paths for breaking changes
* Stable core, extensible edges

### 4. Implementation-First

* Changes proven in production
* Reference implementation validates design
* Real-world usage drives evolution
* Pragmatic over theoretical

### 5. Platform Neutral

* No single AI platform controls standard
* Works with all major AI assistants
* Community-driven governance
* Prevents vendor lock-in

## Governance

Yuba Schema is maintained through open governance:

**Steering Committee**:

* 3 seats: Yuba Platform (reference implementation)
* 2 seats: AI platform representatives
* 2 seats: Business/operator representatives
* 2 seats: Independent developer community

**Working Groups**:

* MCP Tools
* Analytics & Metrics
* Trust & Safety
* Migration & Compatibility

**Change Process**:

1. Proposal submission (anyone can propose)
2. Community discussion (2 weeks minimum)
3. Working Group review
4. Steering Committee vote
5. Implementation & release

[Read full governance model →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/governance)

## Versioning

Yuba Schema follows **Semantic Versioning 2.0.0**:

* **Major (X.0.0)**: Breaking changes
* **Minor (1.X.0)**: Backward-compatible additions
* **Patch (1.0.X)**: Non-breaking fixes

**Current Version**: 1.0.0

[View changelog →](https://amistan.gitbook.io/aidp-docs/resources/changelog)

## Adoption

### Who Can Use Yuba Schema?

Yuba Schema is an open standard available for:

* Yuba Platform (reference implementation)
* AI platforms (Claude, ChatGPT, Perplexity)
* Tourism boards (regional directories)
* Business SaaS tools (POS, CRM)
* Independent developers

**Note**: Yuba is in early access. We're actively working with early adopters to refine the standard.

### Get Yuba Compliant

Implementations can claim "Yuba Compliant" by:

1. Passing official validation suite
2. Implementing core schema correctly
3. Supporting standard MCP tools (if applicable)
4. Following privacy guidelines

[Learn about certification →](https://amistan.gitbook.io/aidp-docs/for-ai-platform-developers/certification)

## Use Cases

### Tourism & Hospitality

* Hotels, restaurants, attractions
* Tourism boards aggregating businesses
* Travel AI assistants

### Professional Services

* Lawyers, accountants, consultants
* Lead generation

### Home Services

* Plumbers, electricians, contractors
* Emergency service discovery
* Quote requests

### Healthcare & Wellness

* Doctors, dentists, therapists
* Appointment scheduling
* Insurance verification

### Retail

* Local shops, boutiques
* Inventory queries
* In-store pickup

## Getting Started

### For Businesses

[Create Yuba-compliant profile →](https://amistan.gitbook.io/aidp-docs/for-business-owners/getting-started)

### For Developers

[Integrate Yuba Schema →](https://amistan.gitbook.io/aidp-docs/for-developers/overview)

### For AI Platforms

[Add Yuba discovery →](https://amistan.gitbook.io/aidp-docs/for-ai-platform-developers/overview)

### For SaaS Platforms

[Make your platform Yuba-compatible →](https://amistan.gitbook.io/aidp-docs/for-saas-platforms/overview)

## Resources

* [Core Specification](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/core-specification)
* [MCP Tool Catalog](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/mcp-tools)
* [Validation](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/validation)
* [Migration Guides](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/migrations)
* [Governance](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/governance)
* [Contributing](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/contributing)

## Community

* **GitHub**: [github.com/aidp-platform/aidp-schema](https://github.com/aidp-platform/aidp-schema)
* **GitHub Discussions**: [github.com/aidp/platform/discussions](https://github.com/aidp/platform/discussions)
* **Discussions**: [GitHub Discussions](https://github.com/aidp-platform/discussions)
* **Email**: <schema@aidp.dev>

***

**Ready to dive deeper?** [Read the complete specification →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/core-specification)