LLM-LD — Machine-Readable Discovery Protocol for AI Agents

The open standard for making websites AI-agent accessible.

JSON-LD is for search engines. LLM-LD is for AI.

---

The Problem

AI crawlers visit your website every day. They find HTML designed for humans — not machines. They guess what your business does. They get it wrong. They miss your services, your locations, your differentiators.

When someone asks an AI assistant about your industry, you don't come up.

LLM-LD fixes that.

What Is LLM-LD?

LLM-LD is a 3-layer architecture that makes websites reliably machine-readable by LLM-based agents. It tells AI systems exactly what your business does, who you serve, where you operate, and what actions to recommend.

One standard. One network. One file to start.

Architecture — Defense in Depth

Three independent layers. Each works on its own. Together, they're airtight.

Layer 1 — Schema.org JSON-LD

Standard structured data on your pages (or a dedicated AI subdomain). Works today. No platform adoption required.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Acme Dental",
  "description": "Family dental practice in Springfield, IL",
  "address": { "@type": "PostalAddress", "addressLocality": "Springfield", "addressRegion": "IL" },
  "telephone": "+1-217-555-0199",
  "url": "https://acmedental.com"
}
</script>

Layer 2 — Knowledge Graph & Entities

Structured relationship files — people, products, services, locations. Rich context that gives AI systems the connections between what you offer.

/entities/
  people.json        # Team members, founders, key personnel
  products.json      # Products/services with relationships
  locations.json     # Physical or service locations
  relationships.json # Entity connections (@id references)

Layer 3 — Site Index (llm-index.json)

One file at a well-known path. Complete understanding of your business.

{
  "@context": [
    "https://schema.org",
    "https://llmld.org/v1"
  ],
  "@type": "llmld:AIWebsite",
  "llmld:summary": {
    "one_liner": "Family dental practice in Springfield, IL",
    "key_facts": [
      "Accepting new patients",
      "Open Saturdays",
      "Most insurance accepted"
    ]
  },
  "llmld:actions": {
    "primary": [
      { "name": "Book Appointment", "url": "https://acmedental.com/book" }
    ]
  }
}

Layer 1 works if nothing else does. Layer 2 adds depth if crawlers find it. Layer 3 is the future — and it's already live on 100+ sites.

Discovery

The LLM Disco Network

A standard without discovery is a document. A standard with a network is infrastructure.

The LLM Disco Network is the open, free-to-join discovery layer for LLM-LD. When an AI crawler reaches any site in the network, it follows links to the directory and discovers every other site.

• 100+ sites live
• 10+ agencies implementing
• Growing weekly

Implement the spec. Submit your site. You're in.

Who's Using LLM-LD

• 100+ sites live on the LLM Disco Network
• 10+ agencies implementing for their clients
• Growing weekly — join the network

Capxel uses LLM-LD on capxel.com — see the live implementation example.

Quick Start

Full implementation guide: docs/implementation-guide.md — Add LLM-LD to your site in 15 minutes.

1. Create your discovery file

Create /.well-known/llm-ld.json at your domain root:

{
  "@context": "https://llmld.org/context",
  "organization": {
    "name": "Your Company",
    "type": "Your Industry",
    "description": "What you do in one paragraph.",
    "website": "https://yoursite.com"
  },
  "products": [
    {
      "name": "Your Product",
      "description": "What it does.",
      "url": "https://yoursite.com/product",
      "category": "Category"
    }
  ],
  "contact": {
    "email": "hello@yoursite.com",
    "url": "https://yoursite.com/contact"
  }
}

2. Add Layer 1 schemas to your pages

Add JSON-LD <script> tags to each page with appropriate Schema.org types.

3. (Optional) Create llm-index.json

For full Layer 3 coverage, create a comprehensive site index.

4. Validate

# Using the validator (coming soon)
npx llm-ld validate https://yoursite.com

File Structure

.well-known/
  llm-ld.json          # Discovery file (Layer 3)
  llm-index.json       # Site index (Layer 3, alternative path)

# Page-level (Layer 1)
<script type="application/ld+json">...</script>

# Entity files (Layer 2)
/entities/
  *.json

Discovery Patterns

Common paths AI agents check:

Path	Purpose
/.well-known/llm-ld.json	Primary discovery file
/llm-index.json	Site index
/.well-known/llm-index.json	Alternative index path
/ai-discovery	Human-friendly discovery page
ai.yourdomain.com/	AI subdomain (Layer 1 hosting)

Validation Rules

• Must be valid JSON
• Must be fetchable without authentication
• URLs must be canonical (HTTPS, normalized paths)
• File size should be reasonable (keep it scannable; link out to details)
• @context should reference https://llmld.org/v1 or https://schema.org

Tools

Tool	Description	Status
Validator	Python CLI for validating LLM-LD compliance	✅ tools/validate.py
ASO Skill	OpenClaw skill for auditing + generating LLM-LD	Available
Example Library	Real-world implementations across 6 industries	✅ See /examples/
Implementation Guide	Step-by-step for developers	✅ docs/implementation-guide.md

Examples

See the /examples directory for real-world implementations:

• Local Business — Dental practice, restaurant, retail
• E-Commerce — Product catalogs, multi-location
• SaaS — Software products, API documentation
• Professional Services — Consulting, legal, financial
• Healthcare — Medical practices, wellness

Contributing

LLM-LD is an open standard licensed under CC BY 4.0. We welcome contributions:

1. Fork this repository
2. Create a feature branch
3. Submit a pull request

For spec changes, please open an issue first to discuss.

Authors

Created by Capxel

• Nick Dunev — Founder
• Dominick Luna — Co-Founder

Capxel is an AI-native consumer intelligence company. LLM-LD was born from the realization that AI agents need a structured, standardized way to understand businesses — and nothing existed.

"ASO (Agentic Search Optimization) is what you do with LLM-LD. LLM-LD is the standard. ASO is the practice."

Links

• Website: llmld.org
• Capxel: capxel.com
• ASO: capxel.com/aso
• Free ASO Test: capxel.com/aso/test

License

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).

You are free to share and adapt this standard, even commercially, as long as you give appropriate credit.