axint.json

Every Axint project has an axint.json at its root. The file is written by axint init and read by axint publish; the registry validates it server-side before accepting a publish. One schema, three consumers.

The canonical JSON Schema document lives at https://docs.axint.ai/schema/axint.json — point your editor at it with the $schema key for autocomplete and inline validation.

Canonical example

{
  "$schema": "https://docs.axint.ai/schema/axint.json",
  "namespace": "@nima",
  "slug": "create-event",
  "version": "1.0.0",
  "name": "Create Event",
  "description": "Creates a calendar event from natural language.",
  "primary_language": "typescript",
  "entry": "intents/create-event.ts",
  "license": "Apache-2.0",
  "tags": ["calendar", "productivity"],
  "surface_areas": ["Calendar"]
}

Required fields

Field	Type	Constraint
namespace	string	^@[a-z0-9][a-z0-9-]{0,38}$ — the registry namespace, leading @ required
slug	string	^[a-z0-9][a-z0-9-]{0,48}$ — URL-safe package slug, unique within the namespace
version	string	Semver (1.0.0, 1.0.0-beta.1)
name	string	Human-readable display name
entry	string	Path to the intent source file, relative to the project root

First publish under a namespace claims it permanently. slug + version must be unique for each publish.

Optional fields

Field	Type	Default	What it does
$schema	string	—	Points editors at the published JSON Schema for autocomplete
description	string	—	One-sentence summary surfaced in search and listings (≤ 500 chars)
primary_language	"typescript" | "python" | "both"	inferred	Source language hint
readme	string	README.md	Path to the README uploaded with the publish
license	string	Apache-2.0	SPDX identifier from the supported set
homepage	string	—	URL to the project homepage
repository	string	—	URL to the source repository
tags	string[]	[]	Lowercase kebab-case tags for search — max 10
surface_areas	string[]	[]	Apple surface areas (Calendar, Shortcuts, …) — max 5

Supported licenses

Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, 0BSD, Unlicense.

How each tool uses it

• axint init writes a complete file with every required field populated and namespace set to a placeholder (@your-handle) for you to replace before your first publish.
• axint publish parses the file, validates it against this schema, and exits with a clear error pointing to the failing path if anything is wrong.
• The registry re-validates the payload server-side. A publish that doesn’t match the schema is rejected before any storage is touched.
• Editors — VS Code, Cursor, and any JSON-Schema-aware editor follow the $schema URL and give you autocomplete + inline diagnostics as you type.

Editor integration

Point your editor at the schema once and you get autocomplete for every field, enum values for license and primary_language, and live validation on every save:

{
  "$schema": "https://docs.axint.ai/schema/axint.json"
}

No plugin needed — this is standard JSON Schema behaviour.

Changing the schema

The regexes and limits here are kept in lockstep with:

• axint/src/core/axint-config.ts — the CLI validator
• axint-registry/packages/shared/src/constants.ts — the server-side mirror
• The Postgres CHECK constraints on the registry database

Change one, change all three. The CLI test suite (tests/core/axint-config.test.ts) pins the contract.