Skip to content

Example AI Manifest

Jump to bottom
TamTunnel edited this page Dec 1, 2025 · 2 revisions

Example AI Manifest

Below is a realistic AWAS v1.1 manifest for a fictional bookstore. It demonstrates v1.1 features including specVersion, conformance levels, typed inputs/outputs, intent classification, and safety contracts.

{
  "specVersion": "1.1",
  "lastUpdated": "2025-12-01T00:00:00Z",
  "name": "Acme Books",
  "description": "Online bookstore with search, product detail, cart, and checkout",
  "baseUrl": "https://books.acme.example",
  "conformanceLevel": "L2",
  "contact": {
    "email": "devrel@acme.example",
    "url": "https://acme.example/developers"
  },
  "authentication": {
    "required": true,
    "methods": ["oauth2"],
    "oauth2": {
      "authorizationUrl": "https://auth.acme.example/authorize",
      "tokenUrl": "https://auth.acme.example/token",
      "scopes": ["catalog:read", "cart:write", "order:write"]
    }
  },
  "security": {
    "csrfRequired": true,
    "csrfTokenHeader": "X-CSRF-Token",
    "requiredHeaders": ["X-Request-ID"],
    "allowedOrigins": ["https://books.acme.example"],
    "sameSite": "strict"
  },
  "rateLimit": {
    "requests": 300,
    "window": "1h",
    "scope": "token"
  },
  "actions": [
    {
      "id": "search-books",
      "name": "Search Books",
      "description": "Search books by query and optional sort",
      "path": "/search",
      "method": "GET",
      "intent": "read",
      "sideEffect": "safe",
      "conformanceLevel": "L1",
      "parameters": [
        {
          "name": "query",
          "type": "string",
          "required": true,
          "description": "Search text",
          "selector": "input[data-awas-param='query']",
          "minLength": 2
        },
        {
          "name": "sort",
          "type": "string",
          "required": false,
          "enum": ["relevance", "price-asc", "price-desc", "newest"],
          "default": "relevance",
          "selector": "select[data-awas-param='sort']"
        },
        {
          "name": "page",
          "type": "number",
          "required": false,
          "default": 1
        }
      ],
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 2,
            "description": "Search text"
          },
          "sort": {
            "type": "string",
            "enum": ["relevance", "price-asc", "price-desc", "newest"],
            "default": "relevance"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          }
        },
        "required": ["query"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {"type": "string"},
                "author": {"type": "string"},
                "price": {"type": "number"},
                "isbn": {"type": "string"},
                "url": {"type": "string", "format": "uri"}
              }
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "currentPage": {"type": "integer"},
              "totalPages": {"type": "integer"},
              "hasNext": {"type": "boolean"}
            }
          }
        }
      },
      "rateLimitHint": "60/minute"
    },
    {
      "id": "get-book",
      "name": "Get Book Details",
      "description": "Open a book detail page",
      "path": "/book/{isbn}",
      "method": "GET",
      "intent": "read",
      "sideEffect": "safe",
      "conformanceLevel": "L1",
      "parameters": [
        {
          "name": "isbn",
          "type": "string",
          "required": true,
          "pattern": "^[0-9X-]+$",
          "description": "ISBN-10/13"
        }
      ],
      "inputSchema": {
        "type": "object",
        "properties": {
          "isbn": {
            "type": "string",
            "pattern": "^[0-9X-]+$",
            "description": "ISBN-10 or ISBN-13"
          }
        },
        "required": ["isbn"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "author": {"type": "string"},
          "price": {"type": "number"},
          "availability": {"type": "string", "enum": ["in-stock", "out-of-stock", "pre-order"]}
        }
      }
    },
    {
      "id": "add-to-cart",
      "name": "Add To Cart",
      "description": "Add a book to the shopping cart",
      "path": "/cart/add",
      "method": "POST",
      "intent": "write",
      "sideEffect": "idempotent",
      "conformanceLevel": "L2",
      "authScopes": ["cart:write"],
      "previewUrl": "/cart/preview",
      "dryRunSupported": true,
      "idempotencyKeySupported": true,
      "idempotencyKeyHeader": "Idempotency-Key",
      "preconditions": ["User must be authenticated", "Book must be in stock"],
      "parameters": [
        {
          "name": "isbn",
          "type": "string",
          "required": true,
          "x-sensitive": false
        },
        {
          "name": "qty",
          "type": "number",
          "required": true,
          "default": 1,
          "minimum": 1
        }
      ],
      "inputSchema": {
        "type": "object",
        "properties": {
          "isbn": {"type": "string", "pattern": "^[0-9X-]+$"},
          "qty": {"type": "integer", "minimum": 1, "default": 1}
        },
        "required": ["isbn", "qty"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "cartId": {"type": "string"},
          "itemCount": {"type": "integer"},
          "subtotal": {"type": "number"}
        }
      },
      "rateLimitHint": "20/minute"
    },
    {
      "id": "checkout",
      "name": "Checkout",
      "description": "Begin checkout flow",
      "path": "/checkout",
      "method": "POST",
      "intent": "write",
      "sideEffect": "destructive",
      "conformanceLevel": "L3",
      "authScopes": ["order:write"],
      "previewUrl": "/checkout/preview",
      "dryRunSupported": true,
      "idempotencyKeySupported": true,
      "idempotencyKeyHeader": "Idempotency-Key",
      "preconditions": ["Cart must not be empty", "User must be authenticated", "Payment method must be valid"],
      "parameters": [
        {
          "name": "email",
          "type": "string",
          "format": "email",
          "required": true,
          "x-sensitive": true
        },
        {
          "name": "paymentMethodId",
          "type": "string",
          "required": true,
          "x-sensitive": true
        }
      ],
      "inputSchema": {
        "type": "object",
        "properties": {
          "email": {"type": "string", "format": "email"},
          "paymentMethodId": {"type": "string"}
        },
        "required": ["email", "paymentMethodId"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "orderId": {"type": "string"},
          "total": {"type": "number"},
          "confirmationUrl": {"type": "string", "format": "uri"}
        }
      },
      "x-required-confirmation": true
    }
  ]
}

What's New in v1.1

This manifest demonstrates AWAS v1.1 features:

Version Negotiation

  • specVersion: Declares v1.1 compliance for version negotiation
  • lastUpdated: Timestamp for caching and ETags

Conformance Levels

  • Manifest-level: "conformanceLevel": "L2" indicates overall site capability
  • Action-level: Each action specifies L1 (read-only), L2 (write with preview), or L3 (transactional)

Typed Inputs/Outputs

  • inputSchema: JSON Schema for input validation with examples
  • outputSchema: JSON Schema for response structure
  • Both schemas enable better type safety and agent understanding

Safety Contracts

  • intent: Classifies action as read, write, delete, or execute
  • sideEffect: Declares safety level (safe, idempotent, destructive)
  • preconditions: Lists requirements before execution
  • previewUrl: URL for preview before committing (L2/L3)
  • dryRunSupported: Indicates support for dry-run mode

Idempotency Support

  • idempotencyKeySupported: Declares support for idempotent operations
  • idempotencyKeyHeader: Specifies header name for idempotency keys

Security Enhancements

  • security: Manifest-level security descriptors (CSRF, headers, origins)
  • authScopes: OAuth2 scopes required per action
  • rateLimitHint: Per-action rate limit guidance

How this manifest works

  • specVersion/lastUpdated: Enable agents to negotiate version compatibility and cache effectively
  • conformanceLevel: Declares L1/L2/L3 capabilities for phased adoption
  • authentication: OAuth2 with scopes; agents obtain tokens before executing write actions
  • security: Descriptive security requirements (not privileged access)
  • actions: Each action now includes intent, side effects, and typed schemas
  • inputSchema/outputSchema: Replace loose parameter definitions with formal JSON Schema
  • L1 actions (search, get): Safe, read-only operations
  • L2 actions (add-to-cart): Write operations with preview and dry-run support
  • L3 actions (checkout): Transactional operations with full safety contracts

Related HTML snippets

<form action="/search" method="GET" data-awas-action="search-books">
  <input type="text" data-awas-param="query" />
  <select data-awas-param="sort">
    <option value="relevance">Relevance</option>
    <option value="price-asc">Price: Low to High</option>
    <option value="price-desc">Price: High to Low</option>
    <option value="newest">Newest</option>
  </select>
</form>

<div class="results" data-awas-result="search-books"></div>

Clone this wiki locally