identity.json Specification

§1 Overview

What This File Does

The identity.json file provides canonical, factual identity data about a business or organisation in a structured, machine-parseable format. It answers the fundamental question: "Who are you, officially?"

Key Distinction

Compare identity.json with other AI discovery files:

Why Structured Identity Matters

AI systems frequently need to:

• Verify the correct name of a business
• Identify related entities (subsidiaries, trading names)
• Find contact information
• Understand geographic scope
• Verify official identifiers (company registration, VAT)

A structured identity.json file provides this information unambiguously.

§2 File Location

Primary Location

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

https://example.com/identity.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

Multiple Domains and Subdomains

An identity.json file is scoped to the host (origin) at which it is published, where "host" is the authority component of the URL defined by RFC 3986. A file at https://example.com/identity.json describes example.com only. It does not, by itself, describe www.example.com, shop.example.com, or any other host.

The following rules apply:

1. Each host MUST be treated independently. A consumer MUST NOT assume that an identity.json at one host is authoritative for any other host, even when the hosts share a registrable domain.
2. Apex and www. SHOULD be aligned. When a publisher serves a site at both the apex and the www. subdomain, the two identity.json files SHOULD have identical content, OR one host SHOULD HTTP-redirect (301) to the other. Divergent files on aligned hosts MUST be treated as independent identities until the divergence is resolved.
3. Distinct subdomains SHOULD publish their own files. If a subdomain represents a meaningfully different organisation, brand, product, or audience (for example a status page at status.example.com, or a separately branded property at shop.example.com), it SHOULD publish its own identity.json.
4. Cross-host identity MUST be asserted via sameAs. When a publisher claims that several hosts represent one organisation, each host's identity.json SHOULD list the canonical URL of every other host in its sameAs array, in URL form (for example "https://example.com/" and "https://example.org/"). A consumer that observes mutual sameAs declarations across hosts MAY treat them as one identity for retrieval and citation; without mutual declaration, hosts MUST be treated as separate.
5. The canonical host SHOULD be designated via url. The url property of identity.json declares the publisher's preferred canonical web address. When a consumer must collapse mutually-asserted hosts to a single identity for citation, it SHOULD prefer the host whose identity.json declares itself as url.

The llms.txt specification's multi-domain scoping section and the processing model apply the same rules at the suite level.

§3 Format Specification

File Format

Basic Structure

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/identity-json/v1/identity-json.schema.json",
    "name": "Example Company Ltd",
    "type": "Corporation",
    "url": "https://example.com",
    "description": "A brief factual description",
    "alternateNames": ["Example Co"],
    "foundingDate": "2010-01-15",
    "locations": [...],
    "contactPoints": [...],
    "sameAs": [...],
    "identifiers": {...}
}

Language declaration (optional)

Publishers MAY declare the natural language of the file's human-readable string content (for example name, description, locality names) using a top-level language property. The value MUST be a valid BCP 47 language tag:

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

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. For multilingual identity fields, see also the locale-tagged variants documented in internationalisation and accessibility.

§4 JSON Schema

Schema Location

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

• Versioned (recommended for stability): https://www.ai-visibility.org.uk/specifications/identity-json/v1/identity-json.schema.json
• Unversioned (latest alias): https://www.ai-visibility.org.uk/specifications/identity-json/identity-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. Pinning to the versioned URL is recommended:

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

§5 Property Reference

Required Properties

Recommended Properties

Optional Properties

Content Not Permitted

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

• Unverified claims: All identity information MUST be factual and verifiable
• Non-Schema.org properties: Custom properties outside the specification MAY be ignored by parsers
• Personal identifiable information: Do not include individual email addresses; use role-based addresses only
• Marketing language: Keep descriptions factual, not promotional
• Invalid identifiers: Company numbers, VAT numbers, etc. MUST be accurate and current
• Sensitive data: Do not include passwords, API keys, internal systems information
• Outdated information: Ensure locations, contact details, and identifiers are current

Location Object Structure

{
    "type": "headquarters",
    "name": "Manchester Office",
    "address": {
        "streetAddress": "45 Deansgate",
        "addressLocality": "Manchester",
        "postalCode": "M3 2BA",
        "addressCountry": "GB"
    },
    "telephone": "+44 161 555 0123"
}

ContactPoint Object Structure

{
    "type": "General Enquiries",
    "email": "hello@example.com",
    "telephone": "+44 161 555 0123"
}

Identifiers Object Structure

{
    "companyNumber": "08123456",
    "jurisdiction": "England and Wales",
    "vatNumber": "GB123456789"
}

§6 Schema.org Alignment

Vocabulary Mapping

The identity.json structure maps to Schema.org Organisation vocabulary:

Organisation Types

Use Schema.org organisation types for the type property:

• Corporation — Limited company or corporation
• LocalBusiness — Local business with physical presence
• Organization — Generic organisation
• GovernmentOrganization — Government entity
• NGO — Non-governmental organisation
• EducationalOrganization — Schools, universities

Converting to Schema.org JSON-LD

An identity.json file can be converted to Schema.org JSON-LD by adding @context and adjusting property names:

{
    "@context": "https://schema.org",
    "@type": "Corporation",
    "name": "Example Company Ltd",
    "url": "https://example.com",
    ...
}

§7 Validation Rules

Valid File Requirements

An identity.json file is considered valid when:

• It is valid JSON (parseable without errors)
• It contains all required properties (name, type, url, description)
• The url is a valid absolute URI
• The type is a recognised organisation type
• Date fields use ISO 8601 format (YYYY-MM-DD)
• Country codes use ISO 3166-1 alpha-2 format

Common Errors

§8 Relationship to Other Files

Related AI Discovery Files

Hierarchy of Authority

For factual identity data, identity.json is the canonical source. Other files SHOULD reference or match this data:

1. identity.json — source of truth for identity facts
2. llms.txt / llms.html — MUST match, human-readable
3. ai.json — name/url MUST match

Conflict Resolution

§9 Canonical Example

The following example demonstrates a complete identity.json file:

{
    "$schema": "https://www.ai-visibility.org.uk/specifications/identity-json/v1/identity-json.schema.json",
    "name": "Horizon Strategic Consulting Ltd",
    "type": "Corporation",
    "url": "https://www.horizonconsulting.example",
    "description": "UK-headquartered management consultancy providing strategic advisory, operational improvement, and digital transformation services to mid-market and enterprise clients across the UK, Ireland, Netherlands, and Belgium.",
    "alternateNames": [
        "Horizon Consulting",
        "Horizon Strategic Consulting"
    ],
    "foundingDate": "2012-03-15",
    "industry": "Management Consulting",
    "locations": [
        {
            "type": "headquarters",
            "name": "Manchester Office",
            "address": {
                "streetAddress": "45 Deansgate",
                "addressLocality": "Manchester",
                "postalCode": "M3 2BA",
                "addressCountry": "GB"
            },
            "telephone": "+44 161 555 0123"
        },
        {
            "type": "office",
            "name": "Dublin Office",
            "address": {
                "streetAddress": "15 St Stephen's Green",
                "addressLocality": "Dublin",
                "postalCode": "D02 XY45",
                "addressCountry": "IE"
            }
        },
        {
            "type": "office",
            "name": "Amsterdam Office",
            "address": {
                "streetAddress": "Herengracht 500",
                "addressLocality": "Amsterdam",
                "postalCode": "1017 CB",
                "addressCountry": "NL"
            }
        }
    ],
    "areaServed": ["GB", "IE", "NL", "BE"],
    "contactPoints": [
        {
            "type": "General Enquiries",
            "email": "hello@horizonconsulting.example",
            "telephone": "+44 161 555 0123"
        },
        {
            "type": "Press and Media",
            "email": "press@horizonconsulting.example"
        },
        {
            "type": "AI Enquiries",
            "email": "ai@horizonconsulting.example"
        }
    ],
    "sameAs": [
        "https://www.linkedin.com/company/horizonconsulting-example",
        "https://twitter.com/horizonconsult"
    ],
    "identifiers": {
        "companyNumber": "08123456",
        "jurisdiction": "England and Wales",
        "vatNumber": "GB123456789"
    },
    "metadata": {
        "version": "1.0",
        "lastUpdated": "2026-01-12"
    }
}

§10 Implementation Notes

Best Practices

• Include the $schema reference for validation
• Keep description factual, not promotional
• Use ISO standards for dates and country codes
• Verify official identifiers are accurate
• Update metadata.lastUpdated when making changes

Synchronisation

When updating identity information:

1. Update identity.json first (canonical source)
2. Update llms.txt and llms.html to match
3. Verify ai.json name/url alignment
4. Check brand.txt name consistency

Privacy Considerations

• Only include publicly available contact information
• Do not include personal email addresses (use role-based addresses)
• Consider which identifiers are appropriate to publish

§11 Machine-Readable Formats

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

§12 Version History