@ahtmljs/schema 0.1.0

package/dist/validate.js

@@ -0,0 +1,179 @@
+/**
+ * Zero-dependency structural validator for AHTML snapshots.
+ *
+ * Returns a list of human-readable issues. Empty array = valid.
+ * For full JSON Schema validation, run schema.json through any standard
+ * JSON Schema validator (ajv, etc.). This validator is intentionally lean
+ * so the @ahtmljs/schema package has zero runtime dependencies.
+ */
+const ENTITY_TYPES = new Set([
+    'product',
+    'document',
+    'task',
+    'profile',
+    'dataset',
+    'conversation',
+]);
+const PAGE_TYPES = new Set([
+    'home',
+    'product_detail',
+    'product_list',
+    'article',
+    'document',
+    'profile',
+    'task_list',
+    'task_detail',
+    'dataset',
+    'conversation',
+    'checkout',
+    'search_results',
+    'category',
+    'other',
+]);
+export function validate(snap) {
+    const issues = [];
+    if (typeof snap !== 'object' || snap === null) {
+        issues.push({ path: '', message: 'snapshot must be an object', severity: 'error' });
+        return issues;
+    }
+    const s = snap;
+    if (s.ahtml !== '0.1') {
+        issues.push({
+            path: 'ahtml',
+            message: `unsupported version "${String(s.ahtml)}" (expected "0.1")`,
+            severity: 'error',
+        });
+    }
+    if (typeof s.url !== 'string' || !s.url) {
+        issues.push({ path: 'url', message: 'url is required', severity: 'error' });
+    }
+    if (typeof s.fetched_at !== 'string' || !isIso8601(s.fetched_at)) {
+        issues.push({
+            path: 'fetched_at',
+            message: 'fetched_at must be an ISO 8601 timestamp',
+            severity: 'error',
+        });
+    }
+    if (typeof s.page_type !== 'string' || !PAGE_TYPES.has(s.page_type)) {
+        issues.push({
+            path: 'page_type',
+            message: `unknown page_type "${String(s.page_type)}"`,
+            severity: 'error',
+        });
+    }
+    if (!Array.isArray(s.entities)) {
+        issues.push({ path: 'entities', message: 'entities must be an array', severity: 'error' });
+    }
+    else {
+        const seen = new Set();
+        s.entities.forEach((e, i) => {
+            const p = `entities[${i}]`;
+            issues.push(...validateEntity(e, p));
+            if (e?.id) {
+                if (seen.has(e.id)) {
+                    issues.push({ path: p + '.id', message: `duplicate entity id "${e.id}"`, severity: 'error' });
+                }
+                seen.add(e.id);
+            }
+        });
+    }
+    if (!Array.isArray(s.actions)) {
+        issues.push({ path: 'actions', message: 'actions must be an array', severity: 'error' });
+    }
+    else {
+        const seen = new Set();
+        s.actions.forEach((a, i) => {
+            const p = `actions[${i}]`;
+            issues.push(...validateAction(a, p));
+            if (a?.id) {
+                if (seen.has(a.id)) {
+                    issues.push({ path: p + '.id', message: `duplicate action id "${a.id}"`, severity: 'error' });
+                }
+                seen.add(a.id);
+            }
+        });
+    }
+    if (s.ttl !== undefined && (typeof s.ttl !== 'number' || s.ttl < 0)) {
+        issues.push({ path: 'ttl', message: 'ttl must be a non-negative number', severity: 'error' });
+    }
+    return issues;
+}
+function validateEntity(e, path) {
+    const issues = [];
+    if (typeof e !== 'object' || e === null) {
+        issues.push({ path, message: 'entity must be an object', severity: 'error' });
+        return issues;
+    }
+    const ent = e;
+    if (!ent.id || typeof ent.id !== 'string') {
+        issues.push({ path: path + '.id', message: 'entity.id is required', severity: 'error' });
+    }
+    else if (!/^[a-z_]+:[A-Za-z0-9_\-.]+$/.test(ent.id)) {
+        issues.push({
+            path: path + '.id',
+            message: `entity id "${ent.id}" should match "type:slug" (e.g. "product:mbp-14")`,
+            severity: 'warning',
+        });
+    }
+    if (!ent.type || !ENTITY_TYPES.has(ent.type)) {
+        issues.push({
+            path: path + '.type',
+            message: `unknown entity type "${String(ent.type)}"`,
+            severity: 'error',
+        });
+    }
+    else if (ent.id && !ent.id.startsWith(ent.type + ':')) {
+        issues.push({
+            path: path + '.id',
+            message: `id prefix should match type ("${ent.type}:..."), got "${ent.id}"`,
+            severity: 'warning',
+        });
+    }
+    if (ent.type === 'product') {
+        if (!ent.name) {
+            issues.push({ path: path + '.name', message: 'product.name is required', severity: 'error' });
+        }
+        if (ent.price) {
+            if (typeof ent.price.amount !== 'number') {
+                issues.push({ path: path + '.price.amount', message: 'price.amount must be a number', severity: 'error' });
+            }
+            if (typeof ent.price.currency !== 'string') {
+                issues.push({ path: path + '.price.currency', message: 'price.currency must be a string (ISO 4217)', severity: 'error' });
+            }
+        }
+    }
+    return issues;
+}
+function validateAction(a, path) {
+    const issues = [];
+    if (typeof a !== 'object' || a === null) {
+        issues.push({ path, message: 'action must be an object', severity: 'error' });
+        return issues;
+    }
+    const act = a;
+    if (!act.id || typeof act.id !== 'string') {
+        issues.push({ path: path + '.id', message: 'action.id is required', severity: 'error' });
+    }
+    if (act.cost && !['free', 'purchase', 'subscription', 'rate_limited', 'compute'].includes(act.cost.category)) {
+        issues.push({
+            path: path + '.cost.category',
+            message: `unknown cost category "${act.cost.category}"`,
+            severity: 'error',
+        });
+    }
+    if (act.confirmation && !['none', 'recommended', 'required'].includes(act.confirmation)) {
+        issues.push({
+            path: path + '.confirmation',
+            message: `confirmation must be none|recommended|required`,
+            severity: 'error',
+        });
+    }
+    return issues;
+}
+function isIso8601(s) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(s);
+}
+export function isValid(snap) {
+    return validate(snap).every((i) => i.severity !== 'error');
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ahtmljs/schema",
+  "version": "0.1.0",
+  "description": "AHTML semantic snapshot schema — types, validator, builder, and dual-format serializers (JSON + token-optimal compact text).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema.json": "./src/schema.json"
+  },
+  "files": ["dist", "src/schema.json"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "keywords": ["ahtml", "agent", "semantic-web", "ai", "llm", "crawler", "mcp"],
+  "license": "MIT"
+}

package/src/schema.json

@@ -0,0 +1,222 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ahtml.dev/schema/v0.1/snapshot.json",
+  "title": "AHTML Snapshot",
+  "description": "Canonical agent-facing representation of a web page.",
+  "type": "object",
+  "required": ["ahtml", "url", "fetched_at", "page_type", "entities", "actions"],
+  "properties": {
+    "ahtml": { "const": "0.1" },
+    "url": { "type": "string", "format": "uri" },
+    "fetched_at": { "type": "string", "format": "date-time" },
+    "ttl": { "type": "integer", "minimum": 0 },
+    "etag": { "type": "string" },
+    "page_type": {
+      "type": "string",
+      "enum": ["home", "product_detail", "product_list", "article", "document", "profile", "task_list", "task_detail", "dataset", "conversation", "checkout", "search_results", "category", "other"]
+    },
+    "policy": { "$ref": "#/$defs/Policy" },
+    "provenance": { "$ref": "#/$defs/Provenance" },
+    "entities": { "type": "array", "items": { "$ref": "#/$defs/Entity" } },
+    "actions": { "type": "array", "items": { "$ref": "#/$defs/Action" } },
+    "links": { "$ref": "#/$defs/Links" },
+    "schemas": { "type": "object", "additionalProperties": true },
+    "meta": { "type": "object", "additionalProperties": true }
+  },
+  "$defs": {
+    "Money": {
+      "type": "object",
+      "required": ["amount", "currency"],
+      "properties": {
+        "amount": { "type": "number" },
+        "currency": { "type": "string", "minLength": 3, "maxLength": 3 }
+      }
+    },
+    "Stock": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["in_stock", "low_stock", "out_of_stock", "preorder", "discontinued"] },
+        "quantity": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "Entity": {
+      "type": "object",
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z_]+:[A-Za-z0-9_\\-.]+$" },
+        "type": { "enum": ["product", "document", "task", "profile", "dataset", "conversation"] },
+        "freshness": { "enum": ["live", "near_realtime", "daily", "static"] },
+        "updated_at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": true,
+      "oneOf": [
+        { "$ref": "#/$defs/Product" },
+        { "$ref": "#/$defs/Document" },
+        { "$ref": "#/$defs/Task" },
+        { "$ref": "#/$defs/Profile" },
+        { "$ref": "#/$defs/Dataset" },
+        { "$ref": "#/$defs/Conversation" }
+      ]
+    },
+    "Product": {
+      "type": "object",
+      "required": ["id", "type", "name"],
+      "properties": {
+        "type": { "const": "product" },
+        "name": { "type": "string" },
+        "brand": { "type": "string" },
+        "description": { "type": "string" },
+        "price": { "$ref": "#/$defs/Money" },
+        "list_price": { "$ref": "#/$defs/Money" },
+        "stock": { "$ref": "#/$defs/Stock" },
+        "sku": { "type": "string" },
+        "rating": {
+          "type": "object",
+          "properties": {
+            "average": { "type": "number", "minimum": 0, "maximum": 5 },
+            "count": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "Document": {
+      "type": "object",
+      "required": ["id", "type", "title"],
+      "properties": {
+        "type": { "const": "document" },
+        "title": { "type": "string" },
+        "author": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
+        "published_at": { "type": "string", "format": "date-time" },
+        "summary": { "type": "string" },
+        "content": { "type": "string" },
+        "word_count": { "type": "integer", "minimum": 0 },
+        "language": { "type": "string" }
+      }
+    },
+    "Task": {
+      "type": "object",
+      "required": ["id", "type", "title", "state"],
+      "properties": {
+        "type": { "const": "task" },
+        "title": { "type": "string" },
+        "state": { "enum": ["open", "in_progress", "blocked", "done", "cancelled"] },
+        "priority": { "enum": ["low", "medium", "high", "urgent"] },
+        "assignee": { "type": "string" },
+        "due_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "Profile": {
+      "type": "object",
+      "required": ["id", "type", "name", "kind"],
+      "properties": {
+        "type": { "const": "profile" },
+        "name": { "type": "string" },
+        "kind": { "enum": ["person", "organization", "bot"] }
+      }
+    },
+    "Dataset": {
+      "type": "object",
+      "required": ["id", "type", "name", "columns", "rows"],
+      "properties": {
+        "type": { "const": "dataset" },
+        "name": { "type": "string" },
+        "columns": { "type": "array" },
+        "rows": { "type": "array" }
+      }
+    },
+    "Conversation": {
+      "type": "object",
+      "required": ["id", "type", "participants", "messages"],
+      "properties": {
+        "type": { "const": "conversation" },
+        "participants": { "type": "array", "items": { "type": "string" } },
+        "messages": { "type": "array" }
+      }
+    },
+    "Action": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "target": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
+        "auth": {
+          "oneOf": [
+            { "enum": ["none", "optional", "required"] },
+            {
+              "type": "object",
+              "required": ["scheme"],
+              "properties": {
+                "scheme": { "type": "string" },
+                "scopes": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          ]
+        },
+        "cost": {
+          "type": "object",
+          "required": ["category"],
+          "properties": {
+            "amount": { "type": "number" },
+            "currency": { "type": "string" },
+            "category": { "enum": ["free", "purchase", "subscription", "rate_limited", "compute"] }
+          }
+        },
+        "reversible": {
+          "type": "object",
+          "required": ["reversible"],
+          "properties": {
+            "reversible": { "type": "boolean" },
+            "window": { "type": "string" },
+            "policy": { "type": "string" }
+          }
+        },
+        "side_effects": { "type": "array", "items": { "type": "string" } },
+        "confirmation": { "enum": ["none", "recommended", "required"] },
+        "category": { "enum": ["read", "search", "navigate", "create", "update", "delete", "transact", "send", "auth"] }
+      }
+    },
+    "Policy": {
+      "type": "object",
+      "required": ["agents_welcome"],
+      "properties": {
+        "agents_welcome": { "type": "boolean" },
+        "license": { "type": "string" },
+        "rate_limit": { "type": "string" },
+        "actions_require": { "type": "string" },
+        "contact": { "type": "string" },
+        "republish": { "enum": ["allowed", "denied", "attribution_only"] }
+      }
+    },
+    "Provenance": {
+      "type": "object",
+      "properties": {
+        "issuer": { "type": "string" },
+        "signed": { "type": "boolean" },
+        "signature": { "type": "string" },
+        "signature_alg": { "type": "string" }
+      }
+    },
+    "Links": {
+      "type": "object",
+      "properties": {
+        "self": { "type": "string" },
+        "canonical": { "type": "string" },
+        "parent": { "type": "string" },
+        "related": { "type": "array", "items": { "type": "string" } },
+        "next": { "$ref": "#/$defs/PaginationLink" },
+        "prev": { "$ref": "#/$defs/PaginationLink" }
+      }
+    },
+    "PaginationLink": {
+      "type": "object",
+      "properties": {
+        "cursor": { "type": "string" },
+        "url": { "type": "string" },
+        "expected": { "type": "integer" },
+        "total": { "type": "integer" }
+      }
+    }
+  }
+}