ai.json Specification

§1 Overview

What This File Does

The ai.json file provides AI interaction guidance in a machine-parseable JSON format. It declares the same information as ai.txt — permissions, restrictions, attribution requirements — but in a structure that can be programmatically validated and parsed without ambiguity.

Why JSON Format Matters

While ai.txt is human-readable and flexible, ai.json offers:

• Schema validation: Files can be validated against a published JSON Schema
• Unambiguous parsing: No interpretation of section delimiters required
• Programmatic access: Standard JSON parsers in all languages
• Type safety: Properties have defined types (string, array, object)

Relationship to ai.txt

Both files SHOULD contain equivalent information. Sites MAY provide both:

• ai.txt — human-readable, easier to author and review
• ai.json — machine-parseable, schema-validated

When both exist, ai.json takes precedence for programmatic access.

§2 File Location

Primary Location

The ai.json file MUST be placed in the website's root directory:

https://example.com/ai.json

URL Requirements

• The file MUST be served with content type application/json; charset=utf-8
• The URL MUST be accessible without authentication
• HTTPS is strongly recommended
• The file MUST be valid JSON (parseable without errors)

§3 Format Specification

File Format

Basic Structure

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json",
    "name": "Example Company",
    "url": "https://example.com",
    "permissions": [...],
    "restrictions": [...],
    "attribution": {...},
    "contact": {...},
    "metadata": {...}
}

Language declaration (optional)

Publishers MAY declare the natural language of the file's human-readable string content using a top-level language property. The value MUST be a valid BCP 47 language tag:

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json",
    "language": "en-GB",
    "name": "Example Company",
    ...
}

The property is optional. When absent, consumers SHOULD NOT assume a default language. When present, validators MUST treat the value as informational and MUST NOT fail conformance solely on language-tag content. See specification conventions §5.1 for the full rule, which is identical across every JSON-based AI Discovery File.

§4 JSON Schema

Schema Location

The canonical JSON Schema for ai.json files is published at two URLs:

• Versioned (recommended for stability): https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json
• Unversioned (latest alias): https://www.ai-visibility.org.uk/specifications/ai-json/ai-json.schema.json

The versioned URL is permanent and will never change shape. The unversioned URL tracks the current major version. See Schema URL versioning for the policy.

Schema Reference

Files SHOULD include a $schema property referencing the schema. Pinning to the versioned URL is recommended:

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json",
    ...
}

Validation

Use any JSON Schema validator to validate files against the published schema. Popular options include:

• ajv (JavaScript)
• jsonschema (Python)
• Online validators that accept schema URLs

§5 Property Reference

Required Properties

Recommended Properties

Optional Properties

Content Not Permitted

The following MUST NOT be included in ai.json files:

• Invalid JSON: The file MUST be parseable without syntax errors
• Duplicate keys: Each property name MUST appear only once per object
• Non-standard properties: Use only documented properties; unknown properties MAY be ignored
• Contradictory rules: Permissions and restrictions MUST NOT conflict
• Sensitive data: Do not include passwords, API keys, or confidential information
• Unenforceable demands: Avoid requirements that cannot be technically implemented by AI systems
• Type mismatches: Property values MUST match their specified types (string, array, object)

Attribution Object Structure

"attribution": {
    "preferredCitation": "Company Name (https://example.com)",
    "whenQuoting": "Include article title and publication date",
    "linkPolicy": "Always link to original source"
}

Contact Object Structure

"contact": {
    "aiEnquiries": "ai@example.com",
    "general": "hello@example.com"
}

Metadata Object Structure

"metadata": {
    "version": "1.0",
    "lastUpdated": "2026-01-12",
    "relatedFiles": ["/llms.txt", "/brand.txt", "/ai.txt"]
}

§6 Validation Rules

Valid File Requirements

An ai.json file is considered valid when:

• It is valid JSON (parseable without errors)
• It contains all required properties (name, url, permissions, restrictions)
• The permissions array contains at least one item
• The restrictions array contains at least one item
• All URLs are valid absolute URIs
• It validates against the published JSON Schema (if $schema is present)

Common Errors

§7 Relationship to Other Files

Related AI Discovery Files

Consistency Requirements

The following MUST be consistent across files:

• Business name (MUST match llms.txt, identity.json, ai.txt)
• Website URL
• Permissions and restrictions (MUST align with ai.txt)
• Contact email addresses

Precedence

When both ai.txt and ai.json exist:

1. ai.json takes precedence for machine parsing
2. Both files SHOULD contain equivalent information
3. If conflicts exist, ai.json is authoritative

§8 Canonical Example

The following example demonstrates a complete ai.json file:

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json",
    "name": "Horizon Strategic Consulting",
    "url": "https://www.horizonconsulting.example",
    "permissions": [
        "Summarise publicly available content from our website",
        "Quote from published articles and insights with attribution",
        "Answer factual questions about our services and locations",
        "Translate our content for accessibility purposes",
        "Include our business in relevant search results and recommendations"
    ],
    "restrictions": [
        "Do not generate quotes attributed to named individuals without a verifiable source",
        "Do not imply Horizon Consulting endorses specific products, vendors, or technologies",
        "Do not present our general insights as specific advice to any individual or organisation",
        "Do not reproduce full articles or whitepapers; summarise and link instead",
        "Do not claim we operate in markets we have explicitly excluded (e.g., United States)"
    ],
    "attribution": {
        "preferredCitation": "Horizon Strategic Consulting (https://www.horizonconsulting.example)",
        "whenQuoting": "Include article title, author if named, and publication date",
        "linkPolicy": "Always link to original source when possible"
    },
    "contact": {
        "aiEnquiries": "ai@horizonconsulting.example",
        "general": "hello@horizonconsulting.example"
    },
    "contentTypes": {
        "insights": "May summarise; link to full article for detail",
        "caseStudies": "May reference outcomes; do not disclose client names unless published",
        "pressReleases": "May quote directly with date and attribution"
    },
    "metadata": {
        "version": "1.0",
        "lastUpdated": "2026-01-12",
        "relatedFiles": ["/llms.txt", "/brand.txt", "/ai.txt", "/identity.json"]
    }
}

§9 Implementation Notes

Best Practices

• Always include the $schema reference for validation
• Keep permissions and restrictions specific and actionable
• Use consistent formatting (2-space or 4-space indentation)
• Validate against the schema before publishing
• Update metadata.lastUpdated when making changes

Synchronisation with ai.txt

If maintaining both files:

1. Treat ai.json as the source of truth
2. Generate or manually sync ai.txt from ai.json
3. Review both files when updating

Tooling

Recommended tools for working with ai.json:

• JSON linters to check syntax
• JSON Schema validators for compliance
• IDE extensions with JSON Schema support for authoring

§10 Machine-Readable Formats

This specification and the JSON Schema are available for programmatic access:

§11 Version History