# AI-Friendly HTML Guide

**Version**: 2.0
**Purpose**: Prescriptive guide for developers building web interfaces for both humans and AI agents
**Format**: Copy-paste this entire file into your AI assistant for implementation guidance
**Cross-references**:
- Appendix A (Implementation Cookbook) - Quick copy-paste recipes
- Chapter 12 (Technical Advice) - Full narrative with business context
- **Appendix L (Proposed AI Metadata Patterns)** - Complete MX namespace architecture, metadata specifications, integration guidelines, and relationship to web standards. See Appendix L for comprehensive MX Framework patterns including mx: meta tags, data attributes by namespace (mx.ai, mx.co, mx.ho), JSON-LD integration, and standards compliance.

---

A prescriptive guide for developers creating web interfaces that work for both humans and AI agents.

## Core Principle

Build web pages where state is explicit, information is complete, and structure is semantic. This isn't about accommodating AI as an afterthought — it's about building clearer interfaces that serve everyone better.

The patterns in this guide progress from quick fixes you can apply in minutes to architectural decisions that require more planning. Start wherever makes sense for your situation.

## Standards vs Proposed Patterns

This guide presents both established standards and proposed patterns:

**Established Standards** (use with confidence):

- Schema.org JSON-LD structured data
- HTML semantic elements (`<nav>`, `<main>`, `<dialog>`)
- ARIA attributes for accessibility
- HTTP status codes
- robots.txt

**Emerging Conventions** (early adoption):

- llms.txt for AI agent guidance

**Proposed Patterns** (experimental, forward-compatible):

- mx: meta tag namespace (MX Framework)
- data-agent-visible attribute pattern
- Common data attributes for state management

**For complete proposal specifications, namespace architecture, integration guidelines, and adoption guidelines, see [Appendix L: Proposed AI Metadata Patterns](<https://mx.allabout.network/books/appendices/appendix-l.html>).**

**Note:** Appendix L covers the comprehensive MX namespace architecture (mx:, mx.ai:, mx.co:, mx.ho:), metadata patterns organised by namespace, integration guidelines with existing standards (Schema.org, Open Graph, robots.txt, llms.txt), implementation checklists, and relationship to web standards. All MX patterns are documented there with complete rationale.

All patterns shown are designed to be forward-compatible — they won't break anything if agents don't recognise them. Think of them as progressive enhancement for AI.

---

## Part 1 — Quick Reference Tables

These reference tables give you immediate answers to common questions.

### HTTP Status Codes That Matter

Use the correct status code. Agents rely on these to understand what happened.

| Code | Meaning | When to Use |
| ---- | ------- | ----------- |
| 200 | Success | GET requests returning content |
| 201 | Created | Successful POST creating a resource |
| 303 | See Other | After form submission (POST → redirect) |
| 400 | Bad Request | Validation failures, malformed input |
| 401 | Unauthorised | Login required |
| 403 | Forbidden | Authenticated but not permitted |
| 404 | Not Found | Resource doesn't exist |
| 422 | Unprocessable Entity | Valid syntax, invalid semantics |
| 429 | Too Many Requests | Rate limit exceeded (include Retry-After header) |
| 503 | Service Unavailable | Temporary downtime (include Retry-After header) |

### Standard Form Field Names

Use names that agents recognise. Pick one convention (camelCase or snake_case) and use it consistently.

| Data | Preferred Name | Avoid |
| ---- | -------------- | ----- |
| Email | email | e-mail, emailAddress, user_email |
| First name | firstName or first_name | fname, givenName |
| Last name | lastName or last_name | lname, surname, familyName |
| Full name | fullName or full_name | name, customerName |
| Phone | phone or telephone | tel, phoneNumber, mobile |
| Postcode | postcode or postal_code | zip, zipCode (UK sites) |
| Address line 1 | address1 or street_address | addr1, addressLine1 |
| Address line 2 | address2 | addr2, addressLine2 |
| City | city | town, locality |
| County/State | county or state | region, province |
| Country | country or country_code | nation, countryName |
| Card number | cardNumber or card_number | cc_number, pan, ccnum |
| Expiry date | expiryDate or expiry | exp, cardExpiry |
| CVV/CVC | cvv or cvc | securityCode, cv2 |
| Password | password | pass, pwd, passwd |
| Username | username | user, userName, login |
| Date of birth | dateOfBirth or date_of_birth | dob, birthday, birthDate |
| Company | company or company_name | organisation, businessName |
| Quantity | quantity | qty, amount, count |

### Date and Time Formats

Always use ISO 8601 in data attributes, even when displaying locally formatted dates:

```html
<time datetime="2025-03-15T14:30:00Z"
      data-timezone="Europe/London">
  3:30 PM GMT
</time>

<div class="date-picker">
  <label for="departure-date">Departure date</label>
  <input type="date"
         id="departure-date"
         name="departureDate"
         min="2025-01-01"
         max="2025-12-31"
         value="2025-03-15"
         data-format="YYYY-MM-DD"
         required>
  <p class="help-text">Format: YYYY-MM-DD (e.g., 2025-03-15)</p>
</div>

<header style="background: linear-gradient(135deg, #1e40af 0%, #3b82f6 100%);">
  <h1 style="color: white;">MX: The Protocols</h1>
  <p style="color: white; opacity: 0.7;">Designing the Web for AI Agents</p>
</header>

<header style="background: linear-gradient(135deg, #1e40af 0%, #3b82f6 100%);">
  <h1 style="color: white;">MX: The Protocols</h1>
  <p style="color: #e0e7ff;">Designing the Web for AI Agents</p>
</header>

<!-- When logged in -->
<div id="auth-status"
     data-authenticated="true"
     data-user-id="user-456"
     data-session-expires="2025-01-15T14:30:00Z">
  <p>Signed in as tom@example.com</p>
  <a href="/account">Account</a>
  <form action="/logout" method="POST">
    <button type="submit">Sign out</button>
  </form>
</div>

<!-- When logged out -->
<div id="auth-status" data-authenticated="false">
  <a href="/login">Sign in</a>
  <a href="/register">Create account</a>
</div>

<div class="spinner"></div>

<div class="loading-indicator"
     data-state="loading"
     data-started="2025-12-21T10:30:00Z"
     data-expected-duration="2000"
     role="status"
     aria-live="polite">
  Loading product information (estimated 2 seconds)
</div>

<div class="product-data"
     data-state="loaded"
     data-loaded-at="2025-12-21T10:30:02Z">
  <!-- Product information -->
</div>

<div class="toast toast-error" style="animation: fadeOut 3s forwards;">
  Email address is invalid
</div>

<form id="booking-form">
  <div class="error-summary" role="alert" aria-live="assertive">
    <h2>Please fix the following errors</h2>
    <ul id="error-list">
      <li><a href="#email">Email address format is invalid</a></li>
      <li><a href="#postcode">Postcode is required</a></li>
    </ul>
  </div>

  <div class="field">
    <label for="email">Email address</label>
    <input type="email"
           id="email"
           name="email"
           aria-invalid="true"
           aria-describedby="email-error">
    <div class="field-error"
         id="email-error"
         role="alert">
      Enter a valid email address (example: name@company.com)
    </div>
  </div>

  <button type="submit">Book appointment</button>
</form>

<table>
  <caption>Price comparison — Wireless headphones</caption>
  <thead>
    <tr>
      <th scope="col">Model</th>
      <th scope="col">Price</th>
      <th scope="col">Rating</th>
      <th scope="col">Stock</th>
    </tr>
  </thead>
  <tbody>
    <tr data-product-id="WH-1000">
      <td>AudioTech Pro</td>
      <td data-price="149.99" data-currency="GBP">£149.99</td>
      <td data-rating="4.3" data-review-count="127">4.3 (127 reviews)</td>
      <td data-in-stock="true" data-quantity="23">In stock</td>
    </tr>
  </tbody>
</table>

<div class="sourceCode" id="cb1">
  <pre class="sourceCode html">
    <code class="sourceCode html">
      <!-- actual code content -->
    </code>
  </pre>
</div>

<div class="sourceCode" id="cb1" data-role="code-container">
  <pre class="sourceCode html"
       data-role="code-block"
       data-language="html">
    <code class="sourceCode html"
          data-role="code-content">
      <!-- actual code content -->
    </code>
  </pre>
</div>

<button disabled>Submit</button>

<button disabled
        aria-disabled="true"
        aria-describedby="submit-status"
        data-disabled-reason="3 fields incomplete">
  Submit (3 errors remaining)
</button>

<div id="submit-status" class="form-status" role="status">
  Form completion: 60%
  Required fields remaining: 3
  <ul>
    <li>Email address required</li>
    <li>Postcode format incorrect</li>
    <li>Payment method not selected</li>
  </ul>
</div>

<form id="checkout-form"
      action="/checkout"
      method="POST"
      data-state="incomplete"
      data-errors="2"
      novalidate>

  <div class="error-summary"
       role="alert"
       aria-live="polite"
       data-visible="true">
    <h2>2 errors need fixing</h2>
    <ul>
      <li><a href="#email">Email: Enter a valid email address</a></li>
      <li><a href="#postcode">Postcode: Must be a valid UK postcode</a></li>
    </ul>
  </div>

  <div class="field" data-field-state="error">
    <label for="email">Email address</label>
    <input type="email"
           id="email"
           name="email"
           value="invalid-email"
           aria-invalid="true"
           aria-describedby="email-error"
           data-validation-state="invalid"
           data-error-type="format">
    <div id="email-error" class="field-error" role="alert">
      Enter a valid email address (example: name@company.com)
    </div>
  </div>

  <div class="field" data-field-state="valid">
    <label for="name">Full name</label>
    <input type="text"
           id="name"
           name="name"
           value="Jane Smith"
           aria-invalid="false"
           data-validation-state="valid">
  </div>

  <button type="submit"
          disabled
          aria-disabled="true"
          data-submit-blocked="true"
          data-block-reason="2 validation errors">
    Complete order (fix 2 errors first)
  </button>
</form>

<form action="/booking" method="POST"
      data-step="2"
      data-total-steps="4"
      data-can-proceed="true">

  <nav aria-label="Booking progress">
    <ol class="steps">
      <li data-step="1" data-status="complete">
        <a href="?step=1">Event type</a>
      </li>
      <li data-step="2" data-status="current" aria-current="step">
        Select date
      </li>
      <li data-step="3" data-status="pending">Your details</li>
      <li data-step="4" data-status="pending">Confirm</li>
    </ol>
  </nav>

  <div class="step-content">
    <!-- Current step content -->
  </div>

  <div class="step-navigation">
    <button type="button" formaction="?step=1">Back</button>
    <button type="submit" formaction="?step=3">Continue</button>
  </div>
</form>

<dialog id="confirm-delete"
        open
        aria-labelledby="dialog-title"
        data-action="confirm-deletion"
        data-target-id="item-123">

  <h2 id="dialog-title">Delete this item?</h2>
  <p>This action cannot be undone.</p>

  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="confirm" formaction="/items/123/delete" formmethod="POST">
      Delete
    </button>
  </form>
</dialog>

<nav aria-label="Breadcrumb">
  <ol itemscope itemtype="https://schema.org/BreadcrumbList">
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="/">
        <span itemprop="name">Home</span>
      </a>
      <meta itemprop="position" content="1">
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="/electronics">
        <span itemprop="name">Electronics</span>
      </a>
      <meta itemprop="position" content="2">
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="/electronics/headphones">
        <span itemprop="name">Headphones</span>
      </a>
      <meta itemprop="position" content="3">
    </li>
    <li aria-current="page">
      <span itemprop="name">Wireless Headphones WH-1000</span>
      <meta itemprop="position" content="4">
    </li>
  </ol>
</nav>

<nav aria-label="Main navigation" data-nav-type="primary">
  <ul>
    <li data-section="products">
      <a href="/products">Products</a>
      <ul data-submenu="true">
        <li><a href="/products/headphones">Headphones</a></li>
        <li><a href="/products/speakers">Speakers</a></li>
      </ul>
    </li>
    <li data-section="support">
      <a href="/support">Support</a>
    </li>
    <li data-section="account">
      <a href="/account">Account</a>
    </li>
  </ul>
</nav>

<div class="search-results"
     data-query="wireless headphones"
     data-total-results="47"
     data-page="1"
     data-per-page="20"
     data-sort="relevance">

  <p class="results-summary">
    Showing 1-20 of 47 results for "wireless headphones"
  </p>

  <ol class="results-list">
    <li data-result-position="1" data-product-id="WH-1000">
      <a href="/products/wh-1000">Wireless Headphones WH-1000</a>
      <span data-price="149.99" data-currency="GBP">£149.99</span>
    </li>
    <!-- More results -->
  </ol>

  <nav aria-label="Search results pagination">
    <a href="?q=wireless+headphones&page=2" data-page="2">Next</a>
  </nav>
</div>

<form class="filters"
      action="/products"
      method="GET"
      data-active-filters="3">

  <div class="active-filters" aria-live="polite">
    <p>Active filters:</p>
    <ul>
      <li>
        <span data-filter="category" data-value="headphones">Category: Headphones</span>
        <a href="?brand=sony&price_max=200" aria-label="Remove category filter">×</a>
      </li>
      <li>
        <span data-filter="brand" data-value="sony">Brand: Sony</span>
        <a href="?category=headphones&price_max=200" aria-label="Remove brand filter">×</a>
      </li>
      <li>
        <span data-filter="price_max" data-value="200">Max price: £200</span>
        <a href="?category=headphones&brand=sony" aria-label="Remove price filter">×</a>
      </li>
    </ul>
    <a href="/products" class="clear-all">Clear all filters</a>
  </div>

  <fieldset>
    <legend>Price range</legend>
    <label>
      <input type="radio" name="price" value="0-100"
             data-result-count="12">
      Under £100 (12)
    </label>
    <label>
      <input type="radio" name="price" value="100-200"
             checked
             data-result-count="23">
      £100-£200 (23)
    </label>
  </fieldset>

  <button type="submit">Apply filters</button>
</form>

<nav aria-label="Pagination" class="pagination"
     data-current-page="3"
     data-total-pages="24"
     data-total-items="472"
     data-per-page="20">

  <a href="?page=1" data-page="1">First</a>
  <a href="?page=2" data-page="2" rel="prev">Previous</a>

  <span aria-current="page" data-page="3">Page 3 of 24</span>

  <a href="?page=4" data-page="4" rel="next">Next</a>
  <a href="?page=24" data-page="24">Last</a>

  <!-- Machine-readable summary -->
  <p class="pagination-summary">
    Showing items 41-60 of 472
  </p>
</nav>

<!-- Also add link elements in head -->
<head>
  <link rel="prev" href="?page=2">
  <link rel="next" href="?page=4">
  <link rel="first" href="?page=1">
  <link rel="last" href="?page=24">
</head>

<div id="shopping-cart"
     data-cart-id="cart-abc123"
     data-item-count="3"
     data-subtotal="279.97"
     data-currency="GBP"
     data-last-updated="2025-01-15T10:30:00Z">

  <h2>Your basket (3 items)</h2>

  <ul class="cart-items">
    <li data-product-id="WH-1000"
        data-quantity="1"
        data-unit-price="149.99"
        data-line-total="149.99">
      <span class="product-name">Wireless Headphones WH-1000</span>
      <span class="quantity">Qty: 1</span>
      <span class="price">£149.99</span>
      <form action="/cart/update" method="POST">
        <input type="hidden" name="product_id" value="WH-1000">
        <input type="number" name="quantity" value="1" min="0" max="10">
        <button type="submit">Update</button>
      </form>
      <form action="/cart/remove" method="POST">
        <input type="hidden" name="product_id" value="WH-1000">
        <button type="submit">Remove</button>
      </form>
    </li>
    <!-- More items -->
  </ul>

  <div class="cart-summary">
    <dl>
      <dt>Subtotal</dt>
      <dd data-subtotal="279.97">£279.97</dd>
      <dt>Shipping</dt>
      <dd data-shipping="0.00">Free</dd>
      <dt>VAT (included)</dt>
      <dd data-vat="46.66">£46.66</dd>
      <dt>Total</dt>
      <dd data-total="279.97">£279.97</dd>
    </dl>
  </div>

  <a href="/checkout" class="checkout-button"
     data-checkout-ready="true">
    Proceed to checkout
  </a>
</div>

<div class="order-confirmation"
     role="status"
     data-order-status="confirmed"
     data-order-id="ORD-2025-0115-7890">

  <h1>Order confirmed</h1>

  <div class="confirmation-details">
    <dl>
      <dt>Order number</dt>
      <dd data-order-id="ORD-2025-0115-7890">ORD-2025-0115-7890</dd>

      <dt>Order date</dt>
      <dd><time datetime="2025-01-15T10:35:00Z">15 January 2025, 10:35 AM</time></dd>

      <dt>Total paid</dt>
      <dd data-total="279.97" data-currency="GBP">£279.97</dd>

      <dt>Payment method</dt>
      <dd data-payment-method="card" data-card-last4="4242">Card ending 4242</dd>

      <dt>Estimated delivery</dt>
      <dd data-delivery-date="2025-01-17">17-18 January 2025</dd>
    </dl>
  </div>

  <div class="delivery-address">
    <h2>Delivering to</h2>
    <address>
      Jane Smith<br>
      123 Main Street<br>
      Manchester M1 1AA
    </address>
  </div>

  <div class="order-items">
    <h2>Items ordered</h2>
    <ul>
      <li data-product-id="WH-1000" data-quantity="1">
        Wireless Headphones WH-1000 × 1
      </li>
    </ul>
  </div>

  <div class="next-actions">
    <a href="/orders/ORD-2025-0115-7890">Track this order</a>
    <a href="/orders">View all orders</a>
    <a href="/">Continue shopping</a>
  </div>
</div>

<html lang="en-GB" data-locale="en-GB" data-currency="GBP">
<head>
  <meta name="currency" content="GBP">
  <meta name="locale" content="en-GB">
  <link rel="alternate" hreflang="en-US" href="https://us.example.com/product">
  <link rel="alternate" hreflang="de-DE" href="https://de.example.com/produkt">
  <link rel="alternate" hreflang="x-default" href="https://example.com/product">
</head>
<body>
  <!-- Currency selector -->
  <form action="/set-currency" method="POST" class="currency-selector">
    <label for="currency">Currency</label>
    <select id="currency" name="currency" data-current="GBP">
      <option value="GBP" selected>£ GBP</option>
      <option value="USD">$ USD</option>
      <option value="EUR">€ EUR</option>
    </select>
    <button type="submit">Update</button>
  </form>

  <!-- Prices with explicit currency -->
  <span class="price"
        data-amount="149.99"
        data-currency="GBP"
        data-currency-symbol="£">
    £149.99
  </span>
</body>
</html>

<fieldset class="shipping-options"
          data-destination-country="GB"
          data-destination-postcode="M1 1AA">
  <legend>Choose delivery option</legend>

  <label class="shipping-option" data-shipping-id="standard">
    <input type="radio"
           name="shipping"
           value="standard"
           data-price="0.00"
           data-delivery-days-min="3"
           data-delivery-days-max="5"
           checked>
    <span class="option-name">Standard delivery</span>
    <span class="option-price" data-price="0.00">Free</span>
    <span class="option-time">3-5 working days</span>
    <span class="option-estimate">
      Estimated arrival:
      <time datetime="2025-01-20">20 Jan</time> -
      <time datetime="2025-01-22">22 Jan</time>
    </span>
  </label>

  <label class="shipping-option" data-shipping-id="express">
    <input type="radio"
           name="shipping"
           value="express"
           data-price="5.99"
           data-delivery-days-min="1"
           data-delivery-days-max="2">
    <span class="option-name">Express delivery</span>
    <span class="option-price" data-price="5.99">£5.99</span>
    <span class="option-time">1-2 working days</span>
    <span class="option-estimate">
      Estimated arrival:
      <time datetime="2025-01-16">16 Jan</time> -
      <time datetime="2025-01-17">17 Jan</time>
    </span>
  </label>

  <label class="shipping-option" data-shipping-id="next-day">
    <input type="radio"
           name="shipping"
           value="next-day"
           data-price="9.99"
           data-delivery-days-min="1"
           data-delivery-days-max="1"
           data-cutoff-time="14:00">
    <span class="option-name">Next day delivery</span>
    <span class="option-price" data-price="9.99">£9.99</span>
    <span class="option-time">Next working day</span>
    <span class="option-note">Order before 2pm</span>
    <span class="option-estimate">
      Estimated arrival:
      <time datetime="2025-01-16">16 Jan</time>
    </span>
  </label>
</fieldset>

<article class="tour-itinerary">
  <h1>14-Day Southeast Asia Adventure</h1>

  <nav class="day-navigation" aria-label="Jump to day">
    <a href="#day-1">Day 1: Bangkok</a>
    <a href="#day-2">Day 2: Ayutthaya</a>
    <!-- Through day 14 -->
  </nav>

  <section id="day-1" class="day-detail">
    <h2>Day 1 — Bangkok</h2>
    <p>Arrive in Bangkok...</p>
    <dl>
      <dt>Accommodation</dt>
      <dd>Grande Centre Point Hotel</dd>
      <dt>Meals</dt>
      <dd>Dinner included</dd>
    </dl>
  </section>

  <!-- Days 2-14 follow -->
</article>

<p class="price">From £99</p>

<div class="product-price">
  <span class="currency">£</span>
  <span class="amount">149.99</span>
  <span class="vat-status">inc. VAT</span>
</div>

&lt;details class="price-breakdown"&gt;
  &lt;summary&gt;Price breakdown&lt;/summary&gt;
  <dl>
    <dt>Product price</dt>
    <dd>£139.99</dd>
    <dt>Shipping</dt>
    <dd>£10.00</dd>
    <dt>VAT (included)</dt>
    <dd>£25.00</dd>
    <dt>Total</dt>
    <dd>£149.99</dd>
  </dl>
&lt;/details&gt;

<div class="transaction-error" role="alert" data-error-code="PAYMENT_DECLINED">
  <h2>Payment was declined</h2>
  <p>Your card ending 4242 was declined by your bank.</p>

  <div class="recovery-options">
    <h3>What you can do</h3>
    <ul>
      <li><a href="/checkout/payment">Try a different card</a></li>
      <li><a href="/checkout/payment?method=paypal">Pay with PayPal</a></li>
      <li><a href="/cart">Return to basket</a> (your items are saved)</li>
    </ul>
  </div>

  &lt;details&gt;
    &lt;summary&gt;Technical details&lt;/summary&gt;
    <dl>
      <dt>Error code</dt>
      <dd>PAYMENT_DECLINED</dd>
      <dt>Transaction reference</dt>
      <dd>TXN-2025-0115-ABC123</dd>
      <dt>Time</dt>
      <dd><time datetime="2025-01-15T10:30:00Z">10:30 AM</time></dd>
    </dl>
  </details>
</div>

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "description": "Over-ear wireless headphones with noise cancellation",
  "sku": "WH-1000",
  "brand": {
    "@type": "Brand",
    "name": "AudioTech"
  },
  "offers": {
    "@type": "Offer",
    "price": "149.99",
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock",
    "inventoryLevel": 23,
    "priceValidUntil": "2025-12-31"
  }
}

{
  "@context": "https://schema.org",
  "@type": "Restaurant",
  "name": "Luigi's Pizza",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "Manchester",
    "postalCode": "M1 1AA",
    "addressCountry": "GB"
  },
  "telephone": "0161-123-4567",
  "openingHours": "Mo-Su 11:00-22:00",
  "priceRange": "££",
  "servesCuisine": "Italian"
}

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Tech Conference 2025",
  "startDate": "2025-06-15T09:00",
  "endDate": "2025-06-15T17:00",
  "location": {
    "@type": "Place",
    "name": "Conference Centre",
    "address": {
      "@type": "PostalAddress",
      "addressLocality": "London",
      "addressCountry": "GB"
    }
  },
  "offers": {
    "@type": "Offer",
    "price": "299",
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock"
  }
}

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Build Agent-Friendly Websites",
  "author": {
    "@type": "Person",
    "name": "Jane Developer"
  },
  "datePublished": "2025-01-15",
  "dateModified": "2025-01-20",
  "publisher": {
    "@type": "Organization",
    "name": "Tech Blog"
  }
}

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "name": "Web Design Questions",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is semantic HTML?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Semantic HTML uses elements that clearly describe their meaning to both browsers and developers. Elements like <main>, <nav>, <article>, and <section> convey structure and purpose, whilst <div> and <span> are generic containers with no inherent meaning."
      }
    },
    {
      "@type": "Question",
      "name": "How do I implement form validation?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use native HTML5 validation attributes (required, pattern, min, max) combined with clear error messages via aria-invalid and role=alert. Validate on blur, not just on submit, and show persistent error feedback that doesn't disappear."
      }
    },
    {
      "@type": "Question",
      "name": "What structured data should I add first?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Start with Schema.org structured data relevant to your content type: Product for e-commerce, LocalBusiness for shops, Article for blogs, and FAQPage for Q&A content. Use JSON-LD format in the page head for simplest implementation."
      }
    }
  ]
}

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://example.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Products",
      "item": "https://example.com/products"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Wireless Headphones",
      "item": "https://example.com/products/wireless-headphones"
    }
  ]
}

{
  "@context": "https://schema.org",
  "@type": ["Product", "Book"],
  "name": "MX: The Protocols",
  "author": {
    "@type": "Person",
    "name": "Tom Cranstoun"
  },
  "isbn": "978-1-234567-89-0",
  "bookFormat": "https://schema.org/EBook",
  "numberOfPages": 320,
  "inLanguage": "en-GB",
  "datePublished": "2026-01-01",
  "publisher": {
    "@type": "Organization",
    "name": "Tech Publishers"
  },
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "Organization",
      "name": "Publisher Store"
    }
  }
}

<div class="agent-metadata visually-hidden" data-agent-visible="true">
  <h2>Purchase Information</h2>
  <dl>
    <dt>Action</dt>
    <dd>POST to /cart/add</dd>

    <dt>Required parameters</dt>
    <dd>product_id=WH-1000, quantity (1-23)</dd>

    <dt>Prerequisites</dt>
    <dd>
      <ul>
        <li>Authentication: Required (status: <span id="auth-status">authenticated</span>)</li>
        <li>Payment method: Required (status: <span id="payment-status">configured</span>)</li>
        <li>Shipping address: Required (status: <span id="shipping-status">set</span>)</li>
      </ul>
    </dd>

    <dt>Expected response</dt>
    <dd>Success: 303 redirect to /cart/added | Error: 400 with JSON details</dd>
  </dl>
</div>

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/products/wh-1000</loc>
    <lastmod>2025-01-15</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://example.com/products/wh-2000</loc>
    <lastmod>2025-01-14</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

<head>
  <meta name="mx:content-policy" content="full-extraction-allowed">
  <meta name="mx:attribution" content="required">
</head>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "offers": {
    "@type": "Offer",
    "price": "149.99",
    "priceCurrency": "GBP"
  }
}
</script>

<div id="root"></div>
<script src="app.js"></script>

<html>
<body>
  <div id="app"></div>
  <script src="bundle.js"></script>
</body>
</html>

<html>
<body>
  <div id="app">
    <h1>Product Name</h1>
    <p class="price">£149.99</p>
    <p class="description">Product description here...</p>
    <!-- Full content rendered -->
  </div>
  <script src="bundle.js"></script>
</body>
</html>

// Regular API (optimised for frontend)
GET /api/products/12345
{
  "id": 12345,
  "name": "Wireless Headphones",
  "price": 14999,  // Cents, frontend formats
  "images": ["img1.jpg", "img2.jpg"]
}

// AI-optimised API (includes context)
GET /api/ai/products/12345
{
  "id": 12345,
  "name": "Wireless Headphones",
  "description": "Over-ear wireless headphones with noise cancellation",
  "price": {
    "amount": 149.99,
    "currency": "GBP",
    "formatted": "£149.99",
    "includes_vat": true
  },
  "availability": {
    "status": "in_stock",
    "quantity": 23,
    "ships_within": "1-2 days"
  },
  "purchase_instructions": {
    "endpoint": "POST /api/cart/add",
    "required_fields": ["product_id", "quantity"],
    "authentication": "required_for_checkout"
  },
  "related_products": [12346, 12347],
  "category_path": ["Electronics", "Audio", "Headphones"]
}

function detectAgent(req, res, next) {
  const ua = req.headers['user-agent'] || '';

  const agentPatterns = {
    'gptbot': 'openai',
    'chatgpt': 'openai',
    'claudebot': 'anthropic',
    'claude-web': 'anthropic',
    'google-extended': 'google',
    'bingbot': 'microsoft',
    'perplexitybot': 'perplexity'
  };

  const lowerUA = ua.toLowerCase();

  for (const [pattern, provider] of Object.entries(agentPatterns)) {
    if (lowerUA.includes(pattern)) {
      req.isAIAgent = true;
      req.agentProvider = provider;
      req.agentUA = ua;
      break;
    }
  }

  req.isAIAgent = req.isAIAgent || false;
  next();
}

app.use(detectAgent);

// Use in routes
app.get('/products/:id', (req, res) => {
  if (req.isAIAgent) {
    // Log separately, serve JSON-LD enriched response
    logAgentAccess(req);
  }
  res.render('product', { product });
});

<html data-consent-status="pending">
<body>
  <!-- Consent banner -->
  <dialog id="cookie-consent"
          open
          aria-labelledby="consent-title"
          data-consent-required="true"
          data-consent-categories="necessary,analytics,marketing">

    <h2 id="consent-title">Cookie preferences</h2>
    <p>We use cookies to improve your experience.</p>

    <form action="/consent" method="POST">
      <fieldset>
        <label>
          <input type="checkbox" name="necessary" checked disabled>
          Necessary (required)
        </label>
        <label>
          <input type="checkbox" name="analytics" value="true">
          Analytics
        </label>
        <label>
          <input type="checkbox" name="marketing" value="true">
          Marketing
        </label>
      </fieldset>

      <button type="submit" name="action" value="accept-all">Accept all</button>
      <button type="submit" name="action" value="accept-selected">Accept selected</button>
      <button type="submit" name="action" value="reject-optional">Reject optional</button>
    </form>
  </dialog>

  <!-- Main content always accessible -->
  <main>
    <!-- Page content here -->
  </main>
</body>
</html>

app.use((req, res, next) => {
  // AI agents get necessary-only cookies automatically
  if (req.isAIAgent) {
    req.consentLevel = 'necessary';
    res.locals.showConsentBanner = false;
  } else {
    req.consentLevel = req.cookies.consent || 'pending';
    res.locals.showConsentBanner = req.consentLevel === 'pending';
  }
  next();
});

function botProtection(req, res, next) {
  // Known legitimate AI agents - allow through
  if (req.isAIAgent && isVerifiedAgent(req)) {
    return next();
  }

  // Suspicious patterns - challenge
  if (isSuspiciousRequest(req)) {
    return res.status(403).render('captcha-challenge');
  }

  next();
}

function isVerifiedAgent(req) {
  // Verify via reverse DNS for known providers
  const knownAgentIPs = {
    'openai': ['20.15.240.0/24', '20.171.206.0/24'],
    'anthropic': ['...'],
  };

  // Check if IP matches claimed provider
  const provider = req.agentProvider;
  const clientIP = req.ip;

  return verifyIPRange(clientIP, knownAgentIPs[provider]);
}

<div class="bot-protection" data-protection-type="captcha">
  <p>Please verify you're human:</p>

  <!-- Standard captcha for browsers -->
  <div class="captcha-widget" id="recaptcha"></div>

  <!-- Alternative for AI agents -->
  <div class="agent-alternative visually-hidden" data-agent-visible="true">
    <p>AI agents: Request API access instead.</p>
    <dl>
      <dt>API endpoint</dt>
      <dd>/api/v1/</dd>
      <dt>Authentication</dt>
      <dd>API key required</dd>
      <dt>Request access</dt>
      <dd>api-access@example.com</dd>
    </dl>
  </div>
</div>

const rateLimit = require('express-rate-limit');

// Separate limits for agents
const agentLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 100, // 100 requests per hour
  message: {
    error: 'rate_limit_exceeded',
    retry_after: 3600,
    llms_guidance: '/llms.txt'
  },
  skip: (req) => !req.isAIAgent
});

const humanLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 200,
  skip: (req) => req.isAIAgent
});

app.use('/products', agentLimiter, humanLimiter);

// Express.js example
app.post('/checkout', (req, res) => {
  const order = processOrder(req.body);

  if (order.success) {
    // 303 redirect after successful POST
    res.redirect(303, `/orders/${order.id}/confirmation`);
  } else {
    // Return to form with errors
    res.status(400).render('checkout', {
      errors: order.errors,
      values: req.body
    });
  }
});

<div role="alert" data-error-type="rate-limit" data-retry-after="60">
  <p>You're making requests too quickly. Please wait 60 seconds.</p>
</div>

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="llms-txt" content="/llms.txt">
  <title>404 Not Found</title>
</head>
<body>
  <h1>404</h1>
  <p>Page Not Found</p>
  <p><a href="/">Go back to Home</a></p>
</body>
</html>