# identity.json Specification
# Version: 1.8.0
# https://www.ai-visibility.org.uk/specifications/identity-json/

meta:
  title: identity.json Specification
  description: The canonical specification for identity.json files - structured canonical identity data in JSON format.
  version: "1.8.0"
  versionDate: "2026-06-11"
  canonicalUrl: https://www.ai-visibility.org.uk/specifications/identity-json/
  publisher:
    name: 365i
    url: https://www.365i.co.uk/
  license:
    name: Creative Commons Attribution 4.0 International
    identifier: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  datePublished: "2026-01-12T00:00:00Z"
  dateModified: "2026-06-11T00:00:00Z"
  language: en-GB
  alignment:
    vocabulary: Schema.org Organization
    url: https://schema.org/Organization

specification:
  filename: identity.json
  location: Website root directory
  urlPattern: https://example.com/identity.json
  mimeType: application/json
  encoding: UTF-8
  purpose: Provide a single, authoritative source of factual identity data for an organisation. Enables AI systems to obtain canonical identity information without parsing multiple sources.

  distinction:
    identity.json: Who we officially are (facts)
    ai.json: How AI should interact with us (guidance)

  schema:
    url: https://www.ai-visibility.org.uk/specifications/identity-json/v1/identity-json.schema.json
    latestUrl: https://www.ai-visibility.org.uk/specifications/identity-json/identity-json.schema.json
    version: "1.0.0"

  format:
    type: JSON
    description: Strict JSON, schema-validated, aligned with Schema.org Organization vocabulary
    requirements:
      valid: MUST be valid JSON per RFC 8259
      schema: MUST include $schema reference
      encoding: Must be UTF-8 encoded

  properties:
    required:
      - property: $schema
        type: string
        description: Reference to the identity.json JSON Schema. Publishers SHOULD pin to the versioned URL for stability; the unversioned URL is also accepted as a 'latest' alias.
        example: https://www.ai-visibility.org.uk/specifications/identity-json/v1/identity-json.schema.json

      - property: name
        type: string
        description: Official registered business name
        schemaOrg: name

      - property: url
        type: string
        format: uri
        description: Canonical website URL
        schemaOrg: url

      - property: type
        type: string
        description: Type of organisation
        schemaOrg: "@type"
        examples:
          - Organization
          - Corporation
          - LocalBusiness
          - ProfessionalService

      - property: description
        type: string
        description: Factual description of the organisation
        schemaOrg: description

    recommended:
      - property: alternateName
        type: array
        description: Trading names, abbreviations, and other names used
        schemaOrg: alternateName

      - property: foundingDate
        type: string
        description: "Date the organisation was founded: full ISO 8601 date (YYYY-MM-DD) or bare year (YYYY)"
        schemaOrg: foundingDate

      - property: location
        type: object
        description: Headquarters or primary location
        schemaOrg: location

      - property: locations
        type: array
        description: All office locations
        schemaOrg: location (multiple)

      - property: contactPoints
        type: array
        description: Contact information for different purposes
        schemaOrg: contactPoint

      - property: sameAs
        type: array
        description: Official social profiles and directory listings
        schemaOrg: sameAs

      - property: areaServed
        type: array
        description: Geographic areas where services are offered, as plain strings (e.g. ISO 3166-1 codes) or structured objects with type, name, and code
        schemaOrg: areaServed

    optional:
      - property: language
        type: string
        description: BCP 47 language tag (e.g. en-GB) declaring the natural language of human-readable content in this file. See /specifications/conventions/#language-declaration.
        example: en-GB

      - property: identifier
        type: array
        description: Official identifiers (company registration, VAT, etc.)
        schemaOrg: identifier

      - property: founder
        type: object or array
        description: Founding individual or individuals (a single person object or an array of person objects)
        schemaOrg: founder

      - property: employees
        type: array
        description: Notable employees
        schemaOrg: employee

      - property: parentOrganization
        type: object
        description: Parent company if applicable
        schemaOrg: parentOrganization

      - property: subOrganization
        type: array
        description: Subsidiary organisations
        schemaOrg: subOrganization

      - property: metadata
        type: object
        description: File metadata
        properties:
          - property: version
            type: string
          - property: lastUpdated
            type: string
            format: date

  locationObject:
    description: Structure for location entries
    properties:
      name:
        type: string
        description: Location name (e.g., 'Headquarters', 'Dublin Office')
      streetAddress:
        type: string
      addressLocality:
        type: string
        description: City or town
      addressRegion:
        type: string
        description: State, province, or region
      postalCode:
        type: string
      addressCountry:
        type: string
        description: ISO 3166-1 alpha-2 country code

  contactPointObject:
    description: Structure for contact point entries
    properties:
      type:
        type: string
        description: Contact type (e.g., 'general', 'press', 'sales')
      email:
        type: string
        format: email
      telephone:
        type: string

  validation:
    rules:
      - MUST be valid JSON
      - MUST validate against identity.json JSON Schema
      - MUST include $schema reference
      - MUST include name, url, type, and description
      - URLs MUST be valid URI format
      - Dates MUST be ISO 8601 format (foundingDate accepts a full date or a bare year)
      - Country codes SHOULD be ISO 3166-1 alpha-2
      - Extension properties beyond this specification are permitted and MAY be ignored by consumers, but MUST NOT redefine or contradict documented properties
    commonErrors:
      - Missing $schema reference
      - Invalid JSON syntax
      - Missing required properties
      - Invalid date formats
      - Inconsistent naming across files
      - Invalid country codes

  relationships:
    llms.txt: Identity information must be consistent
    ai.txt: Organisation name and URL must match
    ai.json: Organisation details must be consistent
    brand.txt: Alternate names should align with brand.txt naming rules

example:
  url: https://www.ai-visibility.org.uk/specifications/examples/identity.json
  business: Horizon Strategic Consulting

versionHistory:
  - version: "1.8.0"
    date: "2026-06-11"
    changes: "Schema.org alignment: alternateNames renamed to alternateName, founders renamed to founder (single person or array). areaServed accepts plain strings or structured objects. foundingDate accepts a bare year or a full ISO 8601 date. Schema validation opened to extension properties (additionalProperties is now true) and $schema accepts both the unversioned and versioned /v1/ URLs. The canonical example now validates against the published schema."
  - version: "1.7.0"
    date: "2026-05-11"
    changes: "Phase 6 standardisation release. Added /specifications/roadmap/ (theme-pegged forward plan with Active/Next/Future/On hold status flags), /specifications/extensions/ (rules for experimental x- prefixed files and the promotion path), and /specifications/i18n-a11y/ (multi-language publication, locale-tagged identity fields, RTL handling, accessibility of llms.html). Added the Discovery: directive to the robots-ai.txt specification (publishers MAY advertise AI Discovery Files on the same host). Added a formal media-type stance to the HTTP behaviour page (existing IANA types, no bespoke registrations). Expanded the file integrity and signing section on the security and privacy page with four candidate mechanisms, cross-cutting concerns, and interim publisher / consumer guidance. The Discovery: directive is the only normative addition to publisher behaviour; all other additions are forward-looking documentation."
  - version: "1.6.0"
    date: "2026-05-11"
    changes: "Phase 5 standardisation release. Added /specifications/related-standards/ (positioning vs llmstxt.org, IETF AI Preferences, robots.txt, Schema.org, BCP 14, JSON Schema 2020-12, SemVer) and /specifications/implementations/ (public record of conformant implementations, IETF-style). Added an explicit llmstxt.org backward-compatibility statement to the llms.txt specification. Added a formal multi-domain and subdomain scoping rule to both the llms.txt and identity.json specifications (host-scoped files, cross-host identity asserted via sameAs). No normative requirements changed for existing publishers; the new scoping rules formalise behaviour the specification already implied."
  - version: "1.5.0"
    date: "2026-05-11"
    changes: "Phase 4 standardisation release. Added /specifications/processing-model/ (seven-stage algorithm for conformant consumers), /specifications/consumer-guidance/ (what AI systems should do with AI Discovery Files), /specifications/test-vectors/ (canonical test suite framing), and reference-implementation framing on the AI Visibility Checker. No normative requirements changed."
  - version: "1.4.0"
    date: "2026-05-11"
    changes: "Phase 3 standardisation release. Added /specifications/versioning/ (Semantic Versioning 2.0.0 commitments, deprecation timeline, lifecycle), /specifications/governance/ (proposal lifecycle, editorial process, working principles), /specifications/security-privacy/ (trust model, content-injection patterns, GDPR considerations, integrity primitives roadmap), and /specifications/http-behaviour/ (status codes, redirects, soft-404 detection, caching, rate limits). No normative requirements changed."
  - version: "1.3.0"
    date: "2026-05-11"
    changes: "Phase 2 standardisation release. Added formal conformance specification (Essential / Recommended / Complete classes). Published machine-readable registry at /specifications/registry.json, spec meta-schema, and validator-output schema. Introduced versioned JSON Schema URLs (/v1/) alongside unversioned 'latest' aliases. Added optional BCP 47 language declaration field across all applicable AI Discovery Files. No normative requirements changed."
  - version: "1.2.0"
    date: "2026-05-10"
    changes: "Phase 1 standardisation release. Added 'Status of This Document' block (Stable). Normalised normative requirement keywords to uppercase per RFC 2119 and RFC 8174. Added References section linking to /specifications/conventions/ and /licensing/. No normative requirements changed."
  - version: "1.1.1"
    date: "2026-02-13"
    changes: Added AI Visibility Directory registration guidance. Minor documentation update.
  - version: "1.1.0"
    date: "2026-01-14"
    changes: Added expanded optional properties (subOrganization, numberOfEmployees, logo) and Content Not Permitted guidance. Clarifies Schema.org alignment and privacy considerations.
  - version: "1.0.0"
    date: "2026-01-12"
    changes: Initial specification release. Establishes JSON format for canonical identity data aligned with Schema.org Organisation vocabulary.
