aiax-validate

A command line tool that fetches a site's AIAX manifest and its sections, validates them against the AIAX 0.1 schemas, scores the site and explains every failure.

Built for the Kognai LAX bundle "AIAX validator CLI" (job 814c4f35). MIT licensed. The AIAX schemas in src/schemas/ are copied unchanged from https://github.com/Godman-s/aiax (CC BY 4.0, see src/schemas/NOTICE.md).

Use

npx aiax-validate https://lax.kognai.ai
npx aiax-validate https://www.kognai.ai --json
npx aiax-validate https://site.example --fixtures fixtures/broken/section-id-mismatch

Until it is on the npm registry: npx -y https://agentgate-source.pages.dev/aiax-validate/aiax-validate.tgz https://lax.kognai.ai.

Exit codes: 0 the site is valid, 1 it is not, 2 a usage error. Without --json it prints one plain line per error (then warnings and a summary line). --fixtures <dir> answers every fetch from a file, the URL path under the folder (dir/.well-known/aiax.json); a missing file is a 404, so the tool runs offline.

As a library:

import { validateSite } from 'aiax-validate';
const report = await validateSite('https://lax.kognai.ai', { fetch });

Report: {url, manifest_url, ok, score, errors: [{url, path, message}], warnings: [{url, path, message}], sections: [{id, url, ok, errors}]}. path is a JSON pointer into the document; message names the field and says what is wrong in plain words.

What it checks

• The manifest at /.well-known/aiax.json, then /aiax/manifest.json, against manifest.schema.json: required fields, types, additionalProperties: false, enums, lengths, patterns, ranges, formats (uri, uri reference, date time). A missing or non JSON manifest is an error. Repeated entry point ids are an error.
• Every entry point url, resolved against the manifest URL, fetched and checked against section.schema.json. A section that cannot be fetched or is not JSON, and a section_id that differs from its entry point id, are errors.
• Warnings, which never make a site invalid: a manifest far over its token target, and an est_tokens off by more than a factor of 2.
• Score: 100 with no error and no warning; minus 15 per error and 2 per warning; never below 0.

On 21 Oct 2026 both lax.kognai.ai (5 sections) and www.kognai.ai (6 sections) score 100.

Tests

npm ci
npm test            # offline: recorded copies of both sites and the broken fixtures
npm run test:live   # the same A1 check against the real sites

| Test | Acceptance item | |---|---| | A1 | Passes on lax.kognai.ai and www.kognai.ai (recorded fixtures in fixtures/live/, plus a live run), ok, exit 0, score 90 or more; the fallback manifest path | | A2 | A broken manifest (missing field, wrong type, extra field, bad entry point id) fails with one clear message per problem naming its field; several problems give one message each; missing and non JSON manifests | | A3 | A broken section (missing field, bad pricing, section_id differing from its entry point, missing, not JSON) fails with clear messages; the other sections are still checked | | A4 | --json prints the Report; exit codes 0, 1 and 2; --fixtures offline with 404 for missing files | | A5 | Ready for npm: bin aiax-validate, no runtime dependency, the packed file list, broken case fixtures in fixtures/broken/ |