Skip to content
axintdocs

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

Section titled “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

Section titled “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

Section titled “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

Section titled “Supported licenses”

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

How each tool uses it

Section titled “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

Section titled “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

Section titled “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.