@ahtmljs/schema

Types, runtime validator, JSON + token-optimal compact text formatters, structural diff, and snapshot builder DSL for AHTML — the HTML of the agent web.

npm install @ahtmljs/schema

📊 How well does an AI read it?

We asked an AI 20 questions about the same page — given in 4 different formats:

AHTML JSON: every answer right. AHTML compact: ~50% fewer tokens than HTML — and still more accurate.

What this package gives you

• TypeScript types for Snapshot, six entity primitives (Product, Document, Task, Profile, Dataset, Conversation), Action, Policy, Provenance, Links, SnapshotDiff.
• snapshot() builder DSL — fluent API to compose a typed snapshot.
• Zero-dependency runtime validator (validate) that returns a list of structured issues with path + severity.
• lint(s) snapshot quality linter — best-practice checks beyond validity: a priced product with no stock, a product-detail page with no actions, an action with charge_card side effects but no required confirmation, a truncated dataset with no next link, a dangling action target. Every finding has a stable rule id you can suppress in CI.
• Two serializations:
  • toJson(s) / fromJson(text) — canonical JSON, deterministic, signable.
  • toCompact(s) / fromCompact(text) — token-optimal text, round-trips losslessly.
• diff(prev, next) / applyDiff(prev, d) — structural snapshot diffing.
• computeEtag(s) — content-addressed weak ETag.
• JSON Schema 2020-12 spec at ./src/schema.json.

Quickstart

import { snapshot, toCompact, toJson, validate, lint } from '@ahtmljs/schema';

const snap = snapshot('https://shop.com/products/mbp-14', 'product_detail')
  .ttl(60)
  .policy({ agents_welcome: true, license: 'MIT', rate_limit: '100/min' })
  .add({
    id: 'product:mbp-14',
    type: 'product',
    name: 'MacBook Pro 14"',
    price: { amount: 1999, currency: 'USD' },
    stock: { status: 'in_stock', quantity: 42 },
  })
  .action({
    id: 'purchase',
    target: 'product:mbp-14',
    category: 'transact',
    execute_url: '/api/checkout',
    auth: 'required',
    cost: { amount: 1999, currency: 'USD', category: 'purchase' },
    reversible: { reversible: true, window: 'P30D', policy: 'full_refund' },
    side_effects: ['charge_card', 'email_buyer', 'decrement_stock'],
    confirmation: 'required',
  })
  .build();

console.log(toCompact(snap));   // token-optimal text — default for LLM agents
console.log(toJson(snap));      // canonical JSON — sign-able

const issues = validate(snap);
if (issues.some((i) => i.severity === 'error')) throw new Error('invalid');

// validate() = "is it legal?" — lint() = "is it actually useful to an agent?"
for (const w of lint(snap)) {
  console.warn(`[${w.rule}] ${w.path}: ${w.message}`);
}

What is AHTML?

AHTML turns any website into an MCP server, an OpenAPI provider, a JSON-LD source, and a token-optimal semantic snapshot — from one plugin. This package is the schema underneath. Most users want @ahtmljs/next (the Next.js plugin) or @ahtmljs/agent (the client SDK).

Documentation

• Repository: DibbayajyotiRoy/AHTML
• Spec: SPEC.md
• Plan / roadmap: PLAN.md
• For AI assistants: docs/agents.md
• Comparison vs MCP / llms.txt / schema.org / OpenAPI: docs/compare.md

License

MIT