# A2WF — Agent-to-Web Framework — Complete Reference for LLMs

## What is A2WF?

A2WF (Agent-to-Web Framework) is a community-driven draft specification that defines `siteai.json`, a machine-readable JSON file that website operators host to declare what AI agents may and may not do on their website. It is a governance and restriction layer for AI agent interactions with websites.

A2WF is NOT a replacement for robots.txt, MCP, A2A, or Schema.org. It complements all of them:
- robots.txt controls crawling (path-level allow/deny)
- MCP defines agent capabilities (what agents CAN do)
- A2A defines agent-to-agent communication
- A2WF defines agent permissions from the WEBSITE OWNER's perspective (what agents MAY do)

## File Location

The siteai.json file is hosted at the website root:
```
https://example.com/siteai.json
```

Alternative locations:
- `https://example.com/.well-known/siteai.json`
- Declared via robots.txt: `SiteAI: https://example.com/siteai.json`
- Declared via HTML: `<link rel="siteai" type="application/json" href="/siteai.json">`

## Complete JSON Schema

A siteai.json file is a single JSON object with these top-level keys:

### Required Fields
- `specVersion` (string): REQUIRED. Must be "1.0"
- `permissions` (object): REQUIRED. Contains read, action, and data permissions.

### Recommended Fields
- `@context` (string): RECOMMENDED. Should be "https://schema.org"
- `identity` (object): RECOMMENDED. Website identification and jurisdiction.
- `agentIdentification` (object): RECOMMENDED. Agent identity requirements.
- `scraping` (object): RECOMMENDED. Data extraction and training policies.

### Optional Fields
- `defaults` (object): Global default settings.
- `humanVerification` (object): Human-in-the-loop requirements.
- `legal` (object): Terms of Service and regulatory references.
- `discovery` (object): Links to related standards (MCP, A2A, OpenAPI).
- `metadata` (object): Policy file metadata (author, dates).

## Field Definitions

### identity Object
- `@type` (string): RECOMMENDED. "WebSite"
- `domain` (string): Canonical URL of the website
- `name` (string): Human-readable name
- `description` (string): Brief site description
- `inLanguage` (string): BCP 47 language tag (e.g., "en", "de-AT")
- `category` (string): Website type (e.g., "e-commerce", "healthcare", "restaurant", "news", "finance", "education")
- `jurisdiction` (string): Legal jurisdiction ("EU", "US", "US-CA", "CH")
- `applicableLaw` (array of strings): Applicable regulations (e.g., ["EU AI Act", "GDPR"])

### defaults Object
- `agentAccess` (string): "open", "restricted", or "minimal"
- `requireIdentification` (boolean): Default false
- `humanVerificationRequired` (boolean): Default false
- `maxRequestsPerMinute` (integer): Global rate limit
- `maxRequestsPerHour` (integer): Global hourly rate limit

### permissions Object
Contains three sub-objects: `read`, `action`, `data`.

Each key maps to a permission. Each permission value is an object:
- `allowed` (boolean): REQUIRED. Is this permitted?
- `rateLimit` (integer): OPTIONAL. Requests per minute for this action
- `humanVerification` (boolean): OPTIONAL. Default false. Requires human confirmation
- `note` (string): OPTIONAL. Explanation for agents and humans

#### Read Permissions (passive information access):
- `productCatalog` — Product listings, descriptions, images, categories
- `pricing` — Prices, fees, rate cards
- `availability` — Stock levels, appointment slots, table availability
- `openingHours` — Business hours, holiday schedules
- `contactInfo` — Address, phone, email
- `reviews` — Customer reviews, ratings
- `faq` — Frequently asked questions
- `companyInfo` — About page, team, history

#### Action Permissions (active operations):
- `search` — Site search functionality
- `addToCart` — Adding items to shopping cart
- `checkout` — Completing a purchase (usually humanVerification: true)
- `createAccount` — User registration (often denied)
- `submitReview` — Posting reviews (often denied to prevent fakes)
- `submitContactForm` — Contact form submission
- `bookAppointment` — Booking reservations/appointments
- `cancelOrder` — Cancelling orders
- `requestRefund` — Initiating refunds

#### Data Permissions (sensitive data protection):
- `customerRecords` — User profiles, personal data
- `orderHistory` — Past orders, transactions
- `paymentInfo` — Credit cards, bank details
- `internalAnalytics` — Traffic data, business metrics
- `employeeData` — Staff information

### scraping Object
- `bulkDataExtraction` (boolean): Default false. Systematic large-scale extraction
- `priceMonitoring` (boolean): Default false. Automated price change tracking
- `contentReproduction` (boolean): Default false. Reproducing or republishing content
- `competitiveAnalysis` (boolean): Default false. Data collection for competitive intelligence
- `trainingDataUsage` (boolean): Default false. Using content to train AI models
- `note` (string): Additional context or licensing info

### agentIdentification Object
- `requireUserAgent` (boolean): Agent must include identifying User-Agent header
- `requiredFields` (array): Fields agents must provide: "agentName", "agentOperator", "agentPurpose"
- `allowAnonymousAgents` (boolean): Default true. If false, unidentified agents are blocked
- `trustedAgents` (array of objects): Whitelist. Each: {name, operator, permissions}
- `blockedAgents` (array of objects): Blacklist. Each: {pattern, reason}

### humanVerification Object
- `methods` (array of strings): Accepted methods: "redirect-to-browser", "email-confirmation", "sms-otp"
- `requiredFor` (array of strings): Action names that require human verification
- `note` (string): Additional instructions

### legal Object
- `termsUrl` (string): URL to AI-specific Terms of Service
- `complianceNote` (string): Human-readable compliance statement
- `dataRetention` (string): Rules for agent data retention
- `euAiActCompliance` (object):
  - `transparencyRequired` (boolean): Agents must identify as AI
  - `riskClassification` (string): "minimal", "limited", "high", "unacceptable"
  - `humanOversightMandatory` (boolean)

### discovery Object
- `mcpEndpoint` (string): URL to MCP server card
- `a2aAgentCard` (string): URL to A2A agent card
- `robotsTxt` (string): URL to robots.txt
- `schemaOrg` (boolean): Whether Schema.org markup is present
- `openApi` (string): URL to OpenAPI specification

### metadata Object
- `author` (string): Policy creator
- `lastUpdated` (string, ISO date): Last modification date
- `expiresAt` (string, ISO date): Policy expiration date
- `changelogUrl` (string): URL to policy change history

## Complete Examples

### Example 1: E-Commerce Store
```json
{
  "@context": "https://schema.org",
  "specVersion": "1.0",
  "identity": {
    "@type": "WebSite",
    "domain": "https://www.example-store.com",
    "name": "Example Online Store",
    "category": "e-commerce",
    "inLanguage": "en",
    "jurisdiction": "EU",
    "applicableLaw": ["EU AI Act", "GDPR"]
  },
  "defaults": {
    "agentAccess": "restricted",
    "requireIdentification": true,
    "maxRequestsPerMinute": 30
  },
  "permissions": {
    "read": {
      "productCatalog": { "allowed": true, "rateLimit": 60 },
      "pricing": { "allowed": true, "rateLimit": 60 },
      "availability": { "allowed": true, "rateLimit": 30 },
      "reviews": { "allowed": true, "rateLimit": 20 },
      "faq": { "allowed": true }
    },
    "action": {
      "search": { "allowed": true, "rateLimit": 20 },
      "addToCart": { "allowed": true },
      "checkout": { "allowed": true, "humanVerification": true, "note": "Final purchase requires human confirmation." },
      "createAccount": { "allowed": false },
      "submitReview": { "allowed": false }
    },
    "data": {
      "customerRecords": { "allowed": false },
      "orderHistory": { "allowed": false },
      "paymentInfo": { "allowed": false }
    }
  },
  "scraping": {
    "bulkDataExtraction": false,
    "priceMonitoring": false,
    "trainingDataUsage": false,
    "contentReproduction": false
  },
  "agentIdentification": {
    "requireUserAgent": true,
    "requiredFields": ["agentName", "agentOperator"],
    "allowAnonymousAgents": false
  },
  "humanVerification": {
    "methods": ["redirect-to-browser"],
    "requiredFor": ["checkout"]
  },
  "legal": {
    "termsUrl": "https://www.example-store.com/legal/ai-terms",
    "dataRetention": "Agents must not cache content beyond the user session."
  }
}
```

### Example 2: Healthcare Provider
```json
{
  "@context": "https://schema.org",
  "specVersion": "1.0",
  "identity": {
    "@type": "WebSite",
    "domain": "https://www.example-clinic.com",
    "name": "Example Medical Clinic",
    "category": "healthcare",
    "inLanguage": "en",
    "jurisdiction": "EU",
    "applicableLaw": ["EU AI Act", "GDPR"]
  },
  "defaults": {
    "agentAccess": "restricted",
    "requireIdentification": true,
    "humanVerificationRequired": true,
    "maxRequestsPerMinute": 10
  },
  "permissions": {
    "read": {
      "openingHours": { "allowed": true },
      "contactInfo": { "allowed": true },
      "companyInfo": { "allowed": true },
      "faq": { "allowed": true }
    },
    "action": {
      "search": { "allowed": true, "rateLimit": 5 },
      "bookAppointment": { "allowed": true, "humanVerification": true, "note": "Patient must confirm identity before booking." },
      "submitContactForm": { "allowed": true, "humanVerification": true },
      "createAccount": { "allowed": false }
    },
    "data": {
      "customerRecords": { "allowed": false, "note": "Patient records are strictly protected under GDPR and medical confidentiality." },
      "orderHistory": { "allowed": false },
      "paymentInfo": { "allowed": false },
      "employeeData": { "allowed": false }
    }
  },
  "scraping": {
    "bulkDataExtraction": false,
    "trainingDataUsage": false,
    "contentReproduction": false
  },
  "agentIdentification": {
    "requireUserAgent": true,
    "requiredFields": ["agentName", "agentOperator", "agentPurpose"],
    "allowAnonymousAgents": false
  },
  "humanVerification": {
    "methods": ["redirect-to-browser", "email-confirmation"],
    "requiredFor": ["bookAppointment", "submitContactForm"]
  },
  "legal": {
    "termsUrl": "https://www.example-clinic.com/legal/ai-policy",
    "dataRetention": "No patient-related data may be stored or transmitted by agents.",
    "euAiActCompliance": {
      "transparencyRequired": true,
      "riskClassification": "high",
      "humanOversightMandatory": true
    }
  }
}
```

### Example 3: Restaurant
```json
{
  "@context": "https://schema.org",
  "specVersion": "1.0",
  "identity": {
    "@type": "WebSite",
    "domain": "https://www.example-restaurant.com",
    "name": "Example Restaurant",
    "category": "restaurant",
    "inLanguage": "en",
    "jurisdiction": "EU"
  },
  "defaults": {
    "agentAccess": "open",
    "maxRequestsPerMinute": 20
  },
  "permissions": {
    "read": {
      "productCatalog": { "allowed": true, "note": "Menu items and daily specials." },
      "pricing": { "allowed": true },
      "availability": { "allowed": true, "note": "Table availability." },
      "openingHours": { "allowed": true },
      "contactInfo": { "allowed": true },
      "reviews": { "allowed": true }
    },
    "action": {
      "search": { "allowed": true },
      "bookAppointment": { "allowed": true, "humanVerification": true, "note": "Table reservation requires guest confirmation." },
      "submitReview": { "allowed": false },
      "submitContactForm": { "allowed": true, "humanVerification": true }
    },
    "data": {
      "customerRecords": { "allowed": false },
      "paymentInfo": { "allowed": false }
    }
  },
  "scraping": {
    "bulkDataExtraction": false,
    "trainingDataUsage": false
  },
  "agentIdentification": {
    "allowAnonymousAgents": true
  },
  "humanVerification": {
    "methods": ["redirect-to-browser"],
    "requiredFor": ["bookAppointment"]
  },
  "legal": {
    "termsUrl": "https://www.example-restaurant.com/legal/ai-terms"
  }
}
```

### Example 4: News / Media
```json
{
  "@context": "https://schema.org",
  "specVersion": "1.0",
  "identity": {
    "@type": "WebSite",
    "domain": "https://www.example-news.com",
    "name": "Example News Network",
    "category": "news",
    "inLanguage": "en",
    "jurisdiction": "EU",
    "applicableLaw": ["EU AI Act", "GDPR", "EU Copyright Directive"]
  },
  "defaults": {
    "agentAccess": "restricted",
    "requireIdentification": true,
    "maxRequestsPerMinute": 10
  },
  "permissions": {
    "read": {
      "productCatalog": { "allowed": true, "rateLimit": 10, "note": "Headlines and summaries only." },
      "contactInfo": { "allowed": true },
      "faq": { "allowed": true }
    },
    "action": {
      "search": { "allowed": true, "rateLimit": 5 }
    },
    "data": {
      "customerRecords": { "allowed": false }
    }
  },
  "scraping": {
    "bulkDataExtraction": false,
    "trainingDataUsage": false,
    "contentReproduction": false,
    "competitiveAnalysis": false,
    "note": "All content is protected by copyright. Contact licensing@example-news.com for licensing."
  },
  "agentIdentification": {
    "requireUserAgent": true,
    "requiredFields": ["agentName", "agentOperator", "agentPurpose"],
    "allowAnonymousAgents": false
  },
  "legal": {
    "termsUrl": "https://www.example-news.com/legal/ai-access-policy",
    "dataRetention": "Agents must not store full article text. Headlines and metadata only."
  }
}
```

### Example 5: Banking / Finance
```json
{
  "@context": "https://schema.org",
  "specVersion": "1.0",
  "identity": {
    "@type": "WebSite",
    "domain": "https://www.example-bank.com",
    "name": "Example Bank AG",
    "category": "finance",
    "inLanguage": "en",
    "jurisdiction": "EU",
    "applicableLaw": ["EU AI Act", "GDPR", "PSD2", "MiFID II"]
  },
  "defaults": {
    "agentAccess": "minimal",
    "requireIdentification": true,
    "humanVerificationRequired": true,
    "maxRequestsPerMinute": 5
  },
  "permissions": {
    "read": {
      "productCatalog": { "allowed": true, "rateLimit": 5, "note": "Public product information only." },
      "contactInfo": { "allowed": true },
      "openingHours": { "allowed": true },
      "faq": { "allowed": true }
    },
    "action": {
      "search": { "allowed": true, "rateLimit": 3 },
      "checkout": { "allowed": false, "note": "No financial transactions via agents." },
      "createAccount": { "allowed": false, "note": "KYC requirements." },
      "bookAppointment": { "allowed": true, "humanVerification": true }
    },
    "data": {
      "customerRecords": { "allowed": false },
      "orderHistory": { "allowed": false },
      "paymentInfo": { "allowed": false },
      "internalAnalytics": { "allowed": false },
      "employeeData": { "allowed": false }
    }
  },
  "scraping": {
    "bulkDataExtraction": false,
    "priceMonitoring": false,
    "trainingDataUsage": false,
    "contentReproduction": false,
    "competitiveAnalysis": false
  },
  "agentIdentification": {
    "requireUserAgent": true,
    "requiredFields": ["agentName", "agentOperator", "agentPurpose"],
    "allowAnonymousAgents": false
  },
  "humanVerification": {
    "methods": ["redirect-to-browser", "email-confirmation", "sms-otp"],
    "requiredFor": ["bookAppointment"]
  },
  "legal": {
    "termsUrl": "https://www.example-bank.com/legal/ai-access-policy",
    "complianceNote": "Regulated financial institution. Unauthorized automated access may be a criminal offense.",
    "dataRetention": "Agents must not store any data obtained from this domain.",
    "euAiActCompliance": {
      "transparencyRequired": true,
      "riskClassification": "high",
      "humanOversightMandatory": true
    }
  }
}
```

## Common Mistakes When Creating siteai.json

1. WRONG: Using arrays instead of objects for permissions
   Wrong: `"read": { "allow": ["products", "pricing"] }`
   Right: `"read": { "productCatalog": { "allowed": true }, "pricing": { "allowed": true } }`

2. WRONG: Forgetting specVersion
   Every siteai.json MUST include `"specVersion": "1.0"`

3. WRONG: Not setting humanVerification on checkout
   Financial transactions should almost always require `"humanVerification": true`

4. WRONG: Allowing anonymous agents on sensitive sites
   Healthcare, finance, and government sites should set `"allowAnonymousAgents": false`

5. WRONG: No legal.termsUrl
   Without a termsUrl, the policy has no legal backing. Always reference your AI Terms of Service.

## How to Validate

1. Ensure the file is valid JSON (use any JSON validator)
2. Check that specVersion is present and set to "1.0"
3. Check that permissions object exists with at least one sub-object
4. Verify the file is served with Content-Type: application/json
5. Verify the file is accessible via HTTPS
6. Online validator: https://a2wf.org/convert/ (coming soon)

## More Information

- Website: https://a2wf.org
- Specification: https://a2wf.org/specification/
- Examples: https://a2wf.org/examples/
- GitHub: https://github.com/a2wf/spec
- License: MIT