---
title: "The AISO Blueprint: Implementing llms.txt, JSON-LD, and Markdown"
slug: "aiso-blueprint-llmstxt-json-ld"
description: "Traditional web architectures rely heavily on client-side rendering and narrative-heavy content, which render platforms virtually invisible to autonomous agents and non-human web crawlers. AI Search Optimization (AISO) and Generative Engine Optimization ("
category: "architecture"
schemaType: "TechArticle"
readingTimeMin: 5
relatedTaxonomy: ""
relatedValue: ""
provenance: "human_written"
authorName: "Ben McIntyre"
datePublished: "2026-08-04T12:09:15.425Z"
dateModified: "2026-08-05T13:24:28.355Z"
canonicalUrl: "https://theagentgateway.com/articles/aiso-blueprint-llmstxt-json-ld"
---
# **The AISO Blueprint: Implementing llms.txt, JSON-LD, and Markdown**

> **Executive TL;DR:**
> - Traditional web architectures relying on client-side rendering and narrative content render platforms invisible to autonomous AI agents and web crawlers.
> - AI Search Optimization (AISO) and Generative Engine Optimization (GEO) resolve discovery deficits by exposing server-rendered HTML, JSON-LD schemas, and Markdown endpoints.
> - Dual-purpose indexing architectures enable generative engines and LLM indexers to parse, serialise, and prioritize enterprise platforms as authoritative sources of truth.

---


## What Are the Core AISO and GEO Standards for Machine-Readable Web Architectures?

**AISO** and **GEO** govern how modern web platforms deliver information density, entity resolution, and structured schemas specifically tailored for non-human consumers. Rather than optimising for human click-through rates, these standards establish rigid database-to-markup patterns to maximise citation frequency within synthesised search engines.

* **The llms.txt Map:** A dynamically generated root Markdown file (`/llms.txt`) that maps the entire site ontology and redirects LLM crawlers directly to un-fluffed, clean text payloads to save token context windows.  
* **JSON-LD Schema Markup:** Structured data script blocks conforming to the schema.org vocabulary (specifically `TechArticle` or `SoftwareApplication`) that define exact properties and entities server-side to eliminate parsing ambiguity.  
* **Dual-Pipeline /raw Router:** A Next.js API layer that serves deserializeable JSON DTOs (Pipeline A) for A2A integrations alongside structured Markdown (Pipeline B) featuring YAML frontmatter for safe RAG chunking.

---

## How to Implement Dual-Pipeline Content Negotiation in Next.js Edge Functions

Executing AISO and content negotiation within the Next.js App Router requires a Server-Side Rendered (SSR) API Route Handler that dynamically evaluates incoming headers. The following TypeScript implementation routes crawlers to the appropriate data pipeline while injecting mandatory temporal freshness and content signals.

```
import { NextResponse, NextRequest } from "next/server";

export const runtime = "edge";


// Implements Dual-Pipeline Content Negotiation and AISO Temporal Authority Headers
export async function GET(
  req: NextRequest,
  { params }: { params: { slug: string } }
) {
  const { slug } = params;

  // 1. Resolve format priority: Query Param (?format=) overrides Accept Header
  const { searchParams } = new URL(req.url);
  const formatParam = searchParams.get("format");
  const acceptHeader = req.headers.get("accept") || "";

  const isMarkdown = formatParam === "markdown" ||
    (!formatParam && acceptHeader.includes("text/markdown"));


  // 2. Fetch sanitised data enforcing DTO boundaries
  const article = {
    title: "The AISO Blueprint: Implementing llms.txt, JSON-LD, and Markdown",
    slug: slug,
    category: "architecture",
    updatedAt: new Date("2026-08-04T03:21:37Z"),

    summary: "A technical guide to configuring Next.js App Router architectures for LLM crawlers.",
    body: "## Strict Semantic Layout\nHTML5 elements like `<article>` and `<section>` are parsed natively."
  };

  // 3. Generate Dual-Pipeline Responses
  if (isMarkdown) {
    const yamlFrontmatter = [
      "---",
      `title: "${article.title}"`,
      `slug: "${article.slug}"`,
      `category: "${article.category}"`,
      `updated_at: "${article.updatedAt.toISOString()}"`, // Mandatory ISO 8601 formatting
      "---"
    ].join("\n");

    const markdownBody = `${yamlFrontmatter}\n\n# ${article.title}\n\n> Executive Summary: ${article.summary}\n\n${article.body}`;

    const headers = new Headers({
      "Content-Type": "text/markdown; charset=utf-8",
      "Cache-Control": "public, max-age=300, stale-while-revalidate=60", // 3.13 CDN Contract
      "ETag": `"article-etag-${slug}"`,
      "Last-Modified": article.updatedAt.toUTCString(),
      "Content-Signal": "ai-train=yes, search=yes, ai-input=yes" // Cloudflare Content Signals Policy
    });

    // Vary: Accept is emitted only if negotiation was driven by the Accept header
    if (!formatParam) {
      headers.set("Vary", "Accept");
    }

    return new NextResponse(markdownBody, { status: 200, headers });
  }

  // Fallback to Pipeline A (JSON DTO)
  return NextResponse.json(article, {
    status: 200,
    headers: {
      "Cache-Control": "public, max-age=300, stale-while-revalidate=60",
      "ETag": `"article-etag-${slug}"`,
      "Last-Modified": article.updatedAt.toUTCString(),
      "Content-Signal": "ai-train=yes, search=yes, ai-input=yes"
    }
  });
}
```

| Feature Parameter | Pipeline A (JSON DTO) | Pipeline B (Markdown RAG) |
| ----- | ----- | ----- |
| **Primary Consumer** | Programmatic A2A clients, structured API integrators | LLM web crawlers, RAG vector databases |
| **Response Format** | application/json with strict schema boundaries | text/markdown with YAML frontmatter and literal blocks |
| **Cache Strategy** | Fast memory / Redis CDN caching (Upstash) | Temporal authority cache validation (ETag / Last-Modified) |
| **WAF / Rate Limiting** | Authenticated Tier B IP sliding window (1000 req / 10s) | Passive Tier A user-agent filtering (50 req / 60s) |

---

## Which Agents Implement the Full AISO Blueprint with Clean /raw Endpoints?

To inspect and evaluate agents that have successfully implemented the AISO Blueprint and expose clean `/raw` endpoints, browse our verified enterprise directory. Every agent listed on our platform is dynamically graded to ensure absolute compliance with JSON-LD schemas, Robots.txt allowlists, and C2PA Content Credentials. Listing on the Gateway allows enterprise procurement engines and automated search clients to index your agent as a verified source of truth.

[Browse all AISO-compliant agents in the directory →](/agents)

---

## Common AISO Blueprint Architecture Questions

* **Q: How should an enterprise architecture handle the 'Vary: Accept' header when serving dual-pipeline endpoints without triggering CDN caching 'split-brain' anomalies?**  
  * **A:** To prevent CDN cache conflicts, the gateway must emit the `Vary: Accept` header only when content routing is dynamically determined by the incoming HTTP `Accept` header. If the request contains an explicit query parameter (such as `?format=markdown`), the router must suppress the `Vary: Accept` header, as the parameter uniquely distinguishes the resource path at the edge caching tier. This strict separation prevents edge-network split-brain issues where browsers accidentally cache raw text files as HTML payloads.  
* **Q: What is the precise strategic utility of Coalition for Content Provenance and Authenticity (C2PA) manifests within modern Generative Engine Optimization?**  
  * **A:** In an online environment saturated with synthetically generated content, AI search crawlers use cryptographic C2PA manifests to programmatically verify human-origin and factual accuracy. By verifying digital signatures and X.509 certificates embedded in the C2PA manifest, LLM ranking algorithms apply significantly higher authority weightings to the content, prioritising it as a definitive "Source of Truth". This credentialing allows organisations to secure superior citation weightings while insulating their brand from generative plagiarism.


[Browse AI agents in the directory](/agents)