Skip to content

Specification

Jump to bottom
TamTunnel edited this page Oct 29, 2025 · 8 revisions

AWAS Specification

Overview

The AI-readable Web Action Standard (AWAS) is an open specification that enables AI agents and browsers to efficiently discover and interact with website functionality. AWAS provides a standardized way for websites to declare their available actions, parameters, and workflows in a machine-readable format.

Core Concepts

What is AWAS?

AWAS is a lightweight protocol that sits alongside your existing web infrastructure. It doesn't replace your HTML, APIs, or user interfaces—it augments them by providing AI agents with a clear map of what actions are possible and how to execute them.

Think of AWAS as a "user manual for AI agents" that describes:

  • What actions your site supports (searching, booking, purchasing, etc.)
  • What parameters each action requires
  • Where to find interactive elements on your pages
  • How to handle authentication and permissions

AWAS Dual-layer Architecture

File Formats

AWAS uses two primary components:

1. AI Manifest (JSON)

The manifest is a JSON file served at /.well-known/ai-actions.json that declares all available actions on your site.

Basic Structure:

{
  "version": "1.0",
  "name": "My Website",
  "description": "A brief description of your site",
  "actions": []
}

2. HTML Attributes

AWAS extends HTML with custom data attributes that help AI agents locate and interact with page elements.

Core Attributes:

  • data-awas-action: Identifies an actionable element
  • data-awas-param: Marks input fields with parameter names
  • data-awas-context: Provides contextual information
  • data-awas-result: Indicates where results will appear

JSON Manifest Structure

The manifest follows a hierarchical structure that maps to your site's functionality.

Top-Level Properties

{
  "version": "1.0",
  "name": "Example Site",
  "description": "Human-readable site description",
  "baseUrl": "https://example.com",
  "contact": {
    "email": "support@example.com",
    "url": "https://example.com/contact"
  },
  "authentication": {
    "required": false,
    "methods": ["oauth2", "api-key"]
  },
  "rateLimit": {
    "requests": 100,
    "window": "1h",
    "scope": "ip"
  },
  "actions": []
}

Field Descriptions:

  • version (required): AWAS specification version (currently "1.0")
  • name (required): Human-readable site name
  • description (required): Brief description of site purpose
  • baseUrl (optional): Root URL for resolving relative paths
  • contact (optional): Support contact information
  • authentication (optional): Authentication requirements
  • rateLimit (optional): Rate limiting parameters
  • actions (required): Array of action definitions

Action Object Structure

{
  "id": "search-products",
  "name": "Search Products",
  "description": "Search our product catalog",
  "path": "/search",
  "method": "GET",
  "parameters": [
    {
      "name": "query",
      "type": "string",
      "required": true,
      "description": "Search query text",
      "selector": "input[data-awas-param='query']"
    },
    {
      "name": "category",
      "type": "string",
      "required": false,
      "enum": ["electronics", "clothing", "books"],
      "selector": "select[data-awas-param='category']"
    }
  ],
  "result": {
    "type": "list",
    "selector": ".product-list",
    "itemSelector": ".product-item"
  },
  "rateLimit": {
    "requests": 20,
    "window": "1m"
  }
}

Action Fields:

  • id (required): Unique identifier for the action
  • name (required): Human-readable action name
  • description (required): What the action does
  • path (required): URL path where action is available
  • method (required): HTTP method (GET, POST, etc.)
  • parameters (optional): Array of parameter definitions
  • result (optional): How to interpret results
  • rateLimit (optional): Action-specific rate limiting
  • authentication (optional): Action-specific auth requirements

Parameter Object Structure

{
  "name": "email",
  "type": "string",
  "format": "email",
  "required": true,
  "description": "User email address",
  "selector": "input[name='email']",
  "validation": {
    "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    "minLength": 5,
    "maxLength": 255
  },
  "default": null,
  "example": "user@example.com"
}

Parameter Fields:

  • name (required): Parameter identifier
  • type (required): Data type (string, number, boolean, object, array)
  • format (optional): Specific format (email, url, date, etc.)
  • required (required): Whether parameter is mandatory
  • description (required): What the parameter represents
  • selector (optional): CSS selector to find the input element
  • validation (optional): Validation rules
  • default (optional): Default value if not provided
  • example (optional): Example value for documentation
  • enum (optional): List of allowed values

Result Object Structure

{
  "type": "list",
  "selector": ".results-container",
  "itemSelector": ".result-item",
  "properties": {
    "title": ".item-title",
    "description": ".item-desc",
    "url": "a[href]",
    "price": ".item-price"
  },
  "pagination": {
    "selector": ".pagination",
    "nextButton": ".next-page",
    "currentPage": ".current-page"
  }
}

Result Fields:

  • type (required): Result type (single, list, table, form)
  • selector (required): CSS selector for result container
  • itemSelector (optional): Selector for individual items (for list/table types)
  • properties (optional): Map of property names to selectors
  • pagination (optional): Pagination information

Data Types

AWAS supports standard JSON Schema data types:

  • string: Text values
  • number: Numeric values (integer or float)
  • boolean: true/false values
  • object: Nested objects
  • array: Lists of values
  • null: Null/empty value

String Formats

Common string formats include:

  • email: Email addresses
  • uri: URIs/URLs
  • date: ISO 8601 dates (YYYY-MM-DD)
  • datetime: ISO 8601 date-times
  • time: ISO 8601 times
  • uuid: UUID identifiers
  • phone: Phone numbers

Complete Example

{
  "version": "1.0",
  "name": "BookStore API",
  "description": "Online bookstore with search and purchase capabilities",
  "baseUrl": "https://bookstore.example.com",
  "contact": {
    "email": "api@bookstore.example.com"
  },
  "rateLimit": {
    "requests": 100,
    "window": "1h"
  },
  "actions": [
    {
      "id": "search-books",
      "name": "Search Books",
      "description": "Search for books by title, author, or ISBN",
      "path": "/search",
      "method": "GET",
      "parameters": [
        {
          "name": "query",
          "type": "string",
          "required": true,
          "description": "Search query",
          "selector": "input[name='q']"
        },
        {
          "name": "sort",
          "type": "string",
          "required": false,
          "enum": ["relevance", "price-low", "price-high", "newest"],
          "default": "relevance",
          "selector": "select[name='sort']"
        }
      ],
      "result": {
        "type": "list",
        "selector": ".book-results",
        "itemSelector": ".book-item",
        "properties": {
          "title": ".book-title",
          "author": ".book-author",
          "price": ".book-price",
          "isbn": "[data-isbn]"
        }
      }
    }
  ]
}

HTML Implementation

Corresponding HTML for the search example:

<form action="/search" method="GET">
  <input type="text" name="q" data-awas-param="query" data-awas-action="search-books" placeholder="Search books..." />
  <select name="sort" data-awas-param="sort">
    <option value="relevance">Most Relevant</option>
    <option value="price-low">Price: Low to High</option>
    <option value="price-high">Price: High to Low</option>
    <option value="newest">Newest</option>
  </select>
  <button type="submit">Search</button>
</form>
<div class="book-results" data-awas-result="search-books">
  <div class="book-item">
    <h3 class="book-title">Example Book</h3>
    <p class="book-author">John Doe</p>
    <span class="book-price">$19.99</span>
    <span data-isbn="978-0-123456-78-9"></span>
  </div>
</div>

Validation

AWAS manifests should be validated against the JSON Schema. Key validation rules:

  1. Required fields must be present at each level
  2. Action IDs must be unique within a manifest
  3. Selectors should be valid CSS selectors
  4. URLs must be well-formed (if absolute)
  5. Rate limits must use valid time units (s, m, h, d)
  6. Enum values must be arrays with at least one item
  7. Type values must be valid JSON Schema types

Content Negotiation

The AI manifest should be served with:

  • Content-Type: application/json
  • Character encoding: UTF-8
  • CORS headers: Enable cross-origin requests for AI agents
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=3600

Versioning

The specification uses semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking changes
  • MINOR: New features, backward compatible
  • PATCH: Bug fixes, backward compatible Clients should support multiple versions gracefully.

Best Practices

  1. Keep manifests under 100KB for fast loading
  2. Use clear, descriptive names for actions and parameters
  3. Include examples in parameter definitions
  4. Document validation rules explicitly
  5. Test selectors to ensure they're stable
  6. Version your manifests if you make breaking changes
  7. Cache manifests appropriately (1 hour recommended)
  8. Use semantic action IDs (kebab-case recommended)

Extensions

AWAS is designed to be extensible. Custom properties can be added using the x- prefix:

{
  "id": "custom-action",
  "name": "Custom Action",
  "x-internal-id": "legacy-123",
  "x-analytics-category": "user-actions"
}

Extensions should not conflict with standard properties and should be ignored by clients that don't understand them.

MCP and A2A Integration

This section defines the normative integration points for MCP (Model Context Protocol) and A2A (Agent-to-Agent) workflows.

Discovery Endpoints

  • MCP: /.well-known/mcp-manifest.json
  • A2A: /.well-known/a2a-manifest.json

Clients MUST request these endpoints to auto-discover protocol capabilities and entry points. Servers SHOULD return HTTP 200 with JSON bodies conforming to their respective schemas.

Manifest Requirements

  • Both manifests MUST reference the AWAS actions catalog via an endpoint (e.g., /.well-known/awas.json).
  • The MCP manifest MUST include capabilities and endpoints sections describing actions and schema links.
  • The A2A manifest MUST include capabilities, endpoints, and interoperability declarations.
  • Implementations SHOULD expose schema definitions for validation (e.g., /schema/awas-schema.json).

Sample Manifests

// MCP
{
  "$schema": "https://modelcontextprotocol.io/schema/manifest.json",
  "name": "AWAS - AI-readable Web Actions Standard",
  "version": "1.0.0",
  "capabilities": ["actions", "resources", "prompts"],
  "endpoints": {"actions": "/.well-known/awas.json", "schema": "/schema/awas-schema.json"},
  "integration": {"protocol": "MCP", "version": "1.0"}
}
// A2A
{
  "$schema": "https://a2a.dev/schema/manifest.json",
  "name": "AWAS - AI-readable Web Actions Standard",
  "version": "1.0.0",
  "protocol": "A2A",
  "capabilities": {"actions": true, "workflows": true, "state_management": true},
  "endpoints": {"actions_registry": "/.well-known/awas.json", "schema_definition": "/schema/awas-schema.json"},
  "interoperability": {"cross_protocol": true, "compatible_with": ["MCP", "OpenAPI", "GraphQL"]}
}

Client Behavior

  • Clients SHOULD cache manifests per standard HTTP caching headers.
  • On failure to fetch MCP/A2A manifests, clients MAY fallback to /.well-known/ai-actions.json.
  • Clients MUST validate referenced schemas before executing actions.

Interoperability and Forward Compatibility

  • AWAS defines 100% interoperability between MCP and A2A by sharing a common actions catalog and schema definitions.
  • Servers MAY include x-* extensions for protocol-specific hints; clients MUST ignore unknown fields.
  • Future protocol versions SHOULD remain backward-compatible within MINOR versions.

Related Standards

  • JSON Schema: Parameter validation
  • OpenAPI: API documentation patterns
  • Schema.org: Semantic markup conventions
  • robots.txt: Access control patterns
  • CORS: Cross-origin resource sharing

Clone this wiki locally