Skip to content

implementation-guide.md

Latest commit

 

History

History
330 lines (258 loc) · 7.82 KB

implementation-guide.md

File metadata and controls

330 lines (258 loc) · 7.82 KB

LLM-LD Implementation Guide

Add LLM-LD to your website in 15 minutes.

This guide walks you through implementing all three layers of LLM-LD. You can start with Layer 1 alone and add layers over time — each one works independently.

Quick Start (5 minutes)

Step 1: Create your discovery file

Create a file at /.well-known/llm-ld.json in your website's public directory.

{
  "@context": ["https://schema.org", "https://llmld.org/v1"],
  "@type": "llmld:AIWebsite",
  "llmld:version": "1.0",
  
  "llmld:summary": {
    "one_liner": "What your business does in one sentence.",
    "key_facts": [
      "Important fact #1",
      "Important fact #2",
      "Important fact #3"
    ]
  },

  "llmld:actions": {
    "primary": [
      { "name": "Your Main CTA", "url": "https://yoursite.com/action", "type": "contact" }
    ]
  },

  "llmld:contact": {
    "email": "hello@yoursite.com",
    "url": "https://yoursite.com/contact"
  }
}

Step 2: Verify it's accessible

Visit https://yoursite.com/.well-known/llm-ld.json in your browser. You should see the JSON.

Step 3: You're done

Seriously. That's the minimum viable LLM-LD implementation. AI agents can now discover your business.

Layer 1: Page-Level Schemas (10 minutes)

Add JSON-LD <script> tags to your key pages.

Homepage

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yoursite.com",
  "description": "What you do.",
  "foundingDate": "2020",
  "contactPoint": {
    "@type": "ContactPoint",
    "email": "hello@yoursite.com",
    "contactType": "customer service"
  }
}
</script>

Product/Service Page

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Your Product",
  "description": "What it does and who it's for.",
  "url": "https://yoursite.com/product",
  "provider": {
    "@type": "Organization",
    "name": "Your Company"
  },
  "offers": {
    "@type": "Offer",
    "price": "99",
    "priceCurrency": "USD"
  }
}
</script>

About Page

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "AboutPage",
  "mainEntity": {
    "@type": "Organization",
    "name": "Your Company",
    "description": "Your story.",
    "founder": [
      {
        "@type": "Person",
        "name": "Founder Name",
        "jobTitle": "CEO"
      }
    ]
  }
}
</script>

FAQ Page

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What do you do?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "We do X for Y customers."
      }
    }
  ]
}
</script>

Tips for Layer 1

  • Be specific — Use LocalBusiness not Organization if you're local. Use SoftwareApplication not Product if you're SaaS.
  • Be factual — Descriptions should be clear and concise. AI agents parse for facts, not marketing fluff.
  • Cover key pages — Homepage, top 3-5 product/service pages, about, contact, FAQ at minimum.

Layer 2: Knowledge Graph (30 minutes)

Create entity files that describe the relationships between things in your business.

Directory Structure

/entities/
  organization.json
  people.json
  products.json

organization.json

{
  "@context": ["https://schema.org", "https://llmld.org/v1"],
  "@graph": [
    {
      "@id": "urn:entity:org:your-company",
      "@type": "Organization",
      "name": "Your Company",
      "description": "What you do.",
      "url": "https://yoursite.com",
      "foundingDate": "2020",
      "founder": [
        { "@id": "urn:entity:person:jane-doe" }
      ],
      "offers": [
        { "@id": "urn:entity:product:product-a" },
        { "@id": "urn:entity:product:product-b" }
      ]
    }
  ]
}

people.json

{
  "@context": ["https://schema.org", "https://llmld.org/v1"],
  "@graph": [
    {
      "@id": "urn:entity:person:jane-doe",
      "@type": "Person",
      "name": "Jane Doe",
      "jobTitle": "CEO & Founder",
      "worksFor": { "@id": "urn:entity:org:your-company" },
      "knowsAbout": ["AI", "Data Science", "Enterprise SaaS"]
    }
  ]
}

Why Layer 2 Matters

Layer 1 describes individual pages. Layer 2 describes relationships. An AI agent reading Layer 2 understands that Jane founded the company, the company offers Product A, and Product A serves the healthcare industry — all connected via @id references.

Layer 3: Full Site Index (15 minutes)

Expand your discovery file into a comprehensive site index. See the specification for the full schema, or use the examples as templates.

Key additions beyond the Quick Start:

{
  "llmld:products": [
    {
      "name": "Product Name",
      "description": "What it does.",
      "url": "https://yoursite.com/product",
      "category": "Category",
      "pricing": "$99/month"
    }
  ],

  "llmld:pages": [
    { "url": "https://yoursite.com/", "type": "homepage", "title": "Page Title" },
    { "url": "https://yoursite.com/pricing", "type": "pricing", "title": "Pricing" }
  ]
}

Framework-Specific Guides

Next.js / React

Place your discovery file at public/.well-known/llm-ld.json. For JSON-LD schemas, use a component:

export function JsonLd({ data }: { data: Record<string, unknown> }) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}

// Usage in page
<JsonLd data={{
  "@context": "https://schema.org",
  "@type": "Product",
  name: "Your Product",
  description: "...",
}} />

WordPress

Use the Schema Pro plugin for Layer 1, and upload llm-ld.json to your .well-known directory via FTP or file manager.

Static Sites (Hugo, Jekyll, 11ty)

Place llm-ld.json in your static assets directory. Most static site generators serve /.well-known/ paths automatically.

Shopify

Add JSON-LD to your theme.liquid or use a schema app. For the discovery file, use a custom page or proxy route.

AI Subdomain Pattern

For sites where modifying production code is impractical, host a machine-optimized mirror:

ai.yoursite.com/
  index.html          # Simplified, schema-rich homepage
  products/
    product-a.html    # Schema-rich product page
  .well-known/
    llm-ld.json       # Discovery file

Add to your main site's robots.txt:

# LLM-LD AI Subdomain
LLM-LD: https://ai.yoursite.com/.well-known/llm-ld.json

This is how the first 100+ sites on the LLM Disco Network implemented LLM-LD.

Validation Checklist

  • /.well-known/llm-ld.json is accessible (no auth, returns JSON)
  • one_liner clearly describes the business
  • At least one primary action with a working URL
  • Contact information present
  • Key product/service pages have JSON-LD schemas
  • All URLs use HTTPS
  • File is under 50KB

Common Mistakes

  1. Marketing copy in descriptions — AI agents want facts, not "world-class" and "best-in-class"
  2. Missing actions — If an agent can't tell a user what to DO, the data is incomplete
  3. Stale data — Update your discovery file when products, hours, or contact info change
  4. Over-engineering — Start with Layer 1 + a simple discovery file. Add complexity later.

Need Help?

LLM-LD is an open standard by Capxel. Licensed under CC BY 4.0.