AI Context Specification

Overview

An AI Context is a published document, typically available at a stable URL, that describes an organisation's public services, procedures, contacts and guidance in a form AI systems can interpret. The AI Context is the authoritative source for the organisation's public information.

It is analogous to how sitemap.xml helps search engines discover web pages. AI Context helps AI systems discover authoritative organisational information.

AI applications should treat this AI Context as the authoritative source for the organisation.

Purpose

The specification defines how organisations publish an AI Context as their authoritative source: portable, model-neutral, and independent of a single AI vendor. Core does not require operating a generic chatbot; optional AIContext Ask is a source-grounded hosted assistant, not a black-box bot.

With AIContext Core, the organisation does not spend model tokens every time a citizen asks a question. It publishes and maintains one official source that different AI tools can read. Only the optional AIContext Ask assistant has a separate hosted-assistant operating cost. That cost belongs to the Ask add-on, not to Core.

• The organisation owns and controls the content.
• Citizens can use their own AI tools, or the organisation can optionally offer a hosted assistant on the same source.
• The context remains portable and versioned.

The specification is open. AIContext.gr can also support official AI Context creation, publishing, verification, monitoring, and maintenance for organisations that want a managed route.

Principles

• Authoritative source: The organisation's AI Context is the authoritative source for its public information.
• Vendor neutral: No single AI platform required.
• Versioned: Changes are tracked and dated.
• Documented: Accompanied by human-readable specification.
• Public by default: Contains only information suitable for public release.
• Non-replacement: Does not replace websites, registries or administrative acts.

Structure

A conforming AI Context includes, at minimum:

• Organisation identity and scope
• Services and procedures
• Required documents and eligibility
• Contacts and hours
• Official links
• Instructions for AI (behavioural rules)
• Version and update metadata
• Optional freshness metadata (recommended for organisations with frequently changing public information)
• Optional events section for time-bound public information (parades, ceremonies, road closures, public notices)

See the demo context for a municipality profile example.

Addressable resources inside a context document use stable identifiers. See Resources and IDs and Source citations.

Resources and IDs

AI Context is a single canonical JSON document. Resources are logical parts of that document, not separate databases. Stable identifiers let consumers, validators, and future protocol adapters address the same objects consistently.

Resource types

Identifier rules

• Use lowercase ASCII slugs: letters, digits, and hyphens only.
• Start and end with a letter or digit.
• Keep identifiers stable across content updates. Change the publication version, not the resource id, when procedures or wording change.
• Identifiers must be unique within their resource type inside one context document.
• Reference related resources by identifier, not display name, for example department_id should match departments[].id.

Example

{
  "municipality": {
    "id": "demo-municipality",
    "name": "Demo Municipality"
  },
  "departments": [
    { "id": "cleanliness-lighting", "name": "Cleanliness & Public Lighting" }
  ],
  "services": [
    {
      "id": "everyday-requests",
      "department_id": "cleanliness-lighting",
      "source": {
        "id": "everyday-requests-source",
        "url": "https://example.gov/everyday-requests",
        "type": "official_form",
        "last_checked": "2026-06-28"
      }
    }
  ]
}

Source citations

Every service, event, or other answer-bearing resource should cite the organisation's official page, form, portal, or announcement. Citations must be machine-readable so AI systems and adapters can link, revalidate, and attribute answers consistently.

Recommended source object

Legacy string fields remain valid for existing publishers:

• source_url on services: equivalent to source.url
• source_last_checked on services: equivalent to source.last_checked
• official_source_url on events: equivalent to source.url

New publications should prefer the structured source object. Conforming consumers should accept either form.

Events (optional)

Proposed optional section for the next specification revision. This does not change specification_version 1.2. Publishers may adopt it now as an optional extension alongside existing context.

An AI Context may include an optional top-level events array for time-bound public information. This section is optional. It is intended for temporary municipal announcements that citizens and AI tools often get wrong when sourced from the open web: parades, public ceremonies, festivals, public meetings, road-closure events, emergency notices, and similar municipal events.

Events should use strong freshness metadata. Conforming AI tools should not present expired events as current information. Verification of a publisher does not automatically verify individual event details.

Example

{
  "events": [
    {
      "id": "independence-day-parade-2026",
      "name": "Independence Day Parade",
      "type": "parade",
      "status": "scheduled",
      "starts_at": "2026-03-25T11:00:00+02:00",
      "ends_at": "2026-03-25T13:00:00+02:00",
      "location": "Central Avenue",
      "route": ["Town Hall", "Central Square", "Memorial"],
      "road_closures": ["Central Avenue", "Square Street"],
      "parking_restrictions": ["No parking on Central Avenue from 08:00"],
      "public_transport_changes": ["Bus route 3 diverted until 14:00"],
      "accessibility": "Accessible viewing area at Central Square.",
      "official_source_url": "https://municipality.gr/parade-2026",
      "last_updated": "2026-03-24T18:00:00+02:00",
      "expires_at": "2026-03-25T15:00:00+02:00"
    }
  ]
}

Recommended fields

Event status values

• scheduled: planned and expected to proceed as published
• updated: details have changed; consumers should re-check the official source
• postponed: delayed; new timing may not yet be final
• cancelled: will not proceed as originally published
• completed: event has finished; historical reference only

Freshness guidance for events

For events, expires_at should usually be shortly after the event ends. For cancellations, road closures, emergency contacts, and public transport changes, conforming AI tools should re-check the canonical source before answering. AI Context can signal freshness; it cannot force external AI tools to refresh. External AI tools vary in how they use expiry metadata.

Conforming AI tools should not present expired events as current information. When expires_at has passed or status is cancelled or completed, assistants should direct users to the official_source_url or canonical_url for the latest announcement.

See the demo context JSON for a fictional reference event example.

Implementation Status

Full roadmap

Discovery

Applications may discover an organisation's AI Context at a standard location when they support URL fetching.

Recommended discovery path

/.well-known/ai-context

The discovery document at this path references the organisation's AI Context endpoint, specification version and update metadata. See the reference discovery file on this site.

Discovery document fields

For citizen-facing prompts, link directly to the canonical context JSON URL. Do not rely on multi-hop discovery unless the consuming tool explicitly supports it.

Public read API

The public interface is read-only JSON. Today, most publishers expose a single canonical document (context.json or equivalent) plus an optional discovery file. That document is the authoritative source of truth.

Publishers may additionally expose optional HTTP resource views under the same origin, for example /v1/services/{service_id}. These views are projections of the canonical document. They must not introduce a second datastore, divergent business logic, or mutation endpoints.

Consumption modes

Recommended read operations

Resource views should include a _meta block with at least resource_type, canonical_url, and specification_version. When a view represents one resource, include resource_id and optional self.

Read-only semantics

• The public API exposes GET only. No create, update, delete, or administrative mutation endpoints are defined.
• Responses use application/json.
• Publishers may send cache headers aligned with freshness metadata; sensitive topics should remain revalidatable against official sources.
• Adapters must treat the canonical context document as the final authority when a view and document disagree.

Error responses

When optional HTTP resource views are implemented, errors should use a consistent JSON envelope so adapters (including future MCP servers) can handle failures predictably without parsing HTML error pages.

Error envelope

{
  "error": {
    "code": "not_found",
    "message": "Service not found",
    "resource_type": "service",
    "resource_id": "unknown-service",
    "specification_version": "1.2",
    "canonical_url": "https://example.gov/ai-context/context.json"
  }
}

Standard error codes

Document-only consumers should apply the same semantics locally, for example return a structured not_found result when service_id is absent from the fetched context.

Machine-readable contracts

Alongside human-readable specification pages, AI Context defines machine-readable contracts for the canonical document and optional public read API. These contracts describe the data model; they do not create a second source of truth.

• JSON Schema: AI Context document
• JSON Schema: AI Context Discovery
• OpenAPI 3.1: public read API

Publishers may mirror these files on their own domain and reference them from discovery using json_schema and openapi. The reference copies on AIContext.gr track specification version 1.2.

Adapter compatibility

AI Context is designed so future protocol adapters, for example an MCP server, can wrap the existing public JSON interface without duplicating business logic or maintaining parallel data models.

An adapter should:

• Resolve the canonical context URL (directly or via discovery).
• Fetch and parse the canonical JSON document.
• Map each tool or resource operation to a documented read operation from Public read API, or select resources locally from the same document.
• Preserve stable resource identifiers and source citations in tool results.
• Surface freshness metadata and official source URLs in responses.

Example future tool mapping (design only)

This specification does not define MCP transport, authentication, server lifecycle, or tool registration. Those belong in a separate adapter layer.

Architecture

One authoritative source, many AI applications.

Versioning

AI Context uses two separate version concepts. Do not conflate them.

Resource identifiers (services[].id, source.id, and similar) should remain stable across content version bumps unless a resource is genuinely retired.

Each publication also carries a last-updated date. Organisations may maintain a version history for audit and public trust.

specification_version: "1.2"
version: "1.4.2"
updated: "2026-06-15"
status: "public"

# Optional freshness metadata (AI Context v1)
last_updated: "2026-06-28"
generated_at: "2026-06-28T12:00:00Z"
expires_at: "2026-06-29T12:00:00Z"
canonical_url: "https://example.gov/.well-known/ai-context"
change_log_url: "https://example.gov/ai-context/changelog"
cache_policy:
  recommended_max_age_hours: 24
  must_revalidate_for:
    - fees
    - deadlines
    - opening_hours
    - emergency_contacts
    - application_requirements

Freshness and revalidation

AI Context v1 supports optional freshness metadata. These fields do not create a new specification version. They are an optional feature organisations may publish alongside their existing context.

AI assistants may cache an old AI Context file or page snapshot. AI Context cannot force every AI tool to refresh. Freshness metadata tells AI systems when the official context was generated, when it expires, where the canonical source is, and when revalidation is recommended.

• last_updated, generated_at and expires_at: when the context was produced and when it should be considered stale
• canonical_url: the authoritative location to re-fetch the current context
• change_log_url: where consumers can review what changed
• cache_policy: recommended cache duration and topics that always require revalidation
• Per-service source_last_checked and freshness_note: guidance for sensitive answers

Conforming AI assistants should re-fetch the canonical context when expires_at has passed. They should revalidate against the official source before answering questions about fees, deadlines, opening hours, emergency contacts or application requirements. For optional events entries, the same applies to road closures, cancellations, public transport changes, and other time-sensitive event details. External AI tools vary; this is recommended behavior, not guaranteed. Consumers should prefer canonical_url over cached or mirrored copies when freshness matters.

See the demo context JSON and demo freshness section for a municipality profile example. See Events (optional) for time-bound public notices.

Examples

Municipality profile example (first reference implementation):

• Demo Municipality AI Context
• Demo JSON representation

Best Practices

• Start with high-demand services in a pilot scope.
• Link to existing official pages rather than duplicating legal text.
• Include explicit instructions for AI to avoid fabrication.
• Review and approve content before each publication.
• Display update date prominently.
• Publish optional freshness metadata so AI systems know when to re-check the official source.

Future Extensions

The specification is designed to extend to any organisation that publishes official public or customer-facing information, starting with municipalities today and universities, hospitals, utilities, financial institutions, and other institutions in future revisions.

Extensions may include additional organisation profiles, federation, and protocol adapters, without changing the core principle: one authoritative source, many AI systems. See Machine-readable contracts and Adapter compatibility for the current JSON Schema, OpenAPI, and adapter-oriented design guidance.