Documentation

Why AI Context?

Websites were designed for people. Search engines required sitemaps. APIs required OpenAPI. Artificial Intelligence requires an official AI Context.

Each era of information access introduced a standard format. AI Context is the equivalent for organisational information consumed by Artificial Intelligence systems.

• Websites: human-readable pages
• sitemap.xml: search engine discovery
• OpenAPI: machine-readable API contracts
• AI Context: official organisational information for AI

Getting Started

An organisation publishes one stable URL containing its official AI Context. Users copy that URL into the AI application they already use.

Core is the foundation: one stable official AI Context URL. Citizens can use their own AI tools, or the organisation can optionally offer AIContext Ask, a hosted assistant that answers only from that verified source.

No generic black-box chatbot required.

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.

1. Define scope (e.g. 5–20 high-demand services).
2. Gather official sources: website pages, forms, contacts.
3. Publish the official AI Context at a public URL.
4. A short usage page guides users: copy link → paste in AI → ask your question.

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.

Publishing

The organisation publishes the official AI Context. Content is reviewed and approved before release.

The published URL should remain stable across updates. Version metadata changes; the link does not.

Updating

When a procedure, fee or contact changes, the AI Context is updated and a new version or update date is recorded. Update freshness metadata (last_updated, generated_at, expires_at) when republishing.

Existing integrations continue to use the same URL. Conforming AI tools should re-fetch when freshness metadata indicates an update; external tools vary.

Versioning

Each release includes version and updated fields. A version history may be maintained for transparency.

See the specification for format details.

Freshness and revalidation

Published information changes. AI tools may reuse an old AI Context file or page snapshot even after the organisation has published an update.

AI Context v1 includes optional freshness metadata. This is not a new specification. It is an optional feature publishers can add to help AI systems know when to re-check the official source.

Best practice: treat the JSON file as live official data for AI, not static marketing copy. Publish from the canonical source, include freshness metadata, and serve it so consumers are encouraged to fetch the current version.

Freshness fields can include last updated date, generated date, expiry date, canonical source URL, changelog URL and revalidation guidance for sensitive topics such as fees, deadlines, opening hours, emergency contacts and application requirements.

AI Context cannot force every AI tool to refresh. External AI tools vary. Conforming AI assistants should re-fetch the canonical context when it has expired, and revalidate before answering questions about changing or sensitive information. Freshness metadata helps signal when re-checking is recommended; it does not prevent stale answers on its own. When freshness matters, consumers should prefer the canonical_url over cached or mirrored copies.

See the specification and the demo freshness section for a municipality profile example.

Temporary events and public notices

A municipality can use AI Context for time-bound public information such as parades, ceremonies, festivals, road closures, and public notices. This is an optional events section in the context file, useful because AI tools can easily get event details wrong (date, time, route, closures, parking, transport changes, accessibility, cancellations).

Each event entry should include an official source URL, start and end time, status, and expires_at so AI tools know when the information may be stale. Verification of the publisher does not guarantee every event detail is correct; freshness metadata helps conforming assistants decide when to re-check the official announcement.

Example citizen questions:

• What time does the parade start?
• Which roads will be closed?
• Can I park near the route?
• Is there accessible viewing?
• Has the event been cancelled because of weather?
• Where is the official announcement?

AI Context can signal freshness; external AI tools vary in how reliably they re-fetch. Conforming assistants should not treat expired events as current. See the specification for the proposed optional schema and the demo for a fictional reference example.

Compatibility

AI Context is designed for modern AI tools that accept URLs or external context, including ChatGPT, Claude, Gemini, Copilot, Perplexity and future systems.

One authoritative source. Many AI applications.

Example Prompt

Municipality profile example. A user might paste the following into their AI:

Use the municipality's official AI Context for this conversation.

https://aicontext.gr/demo-dimos/

Discover and load any published machine-readable AI Context associated with this URL. Do not answer until it has been loaded or you have determined that none exists. If loading succeeds, confirm it briefly and follow all instructions in the AI Context. If loading fails, say so explicitly. Answer only from the official context and state when information is missing.

They can then ask a specific question, for example:

• How do I report a broken streetlight?
• There is an injured stray dog near my street. What should I do?
• How do I apply for a municipal nursery place?

This prompt works as both a citizen-facing instruction and a conformance test: capable assistants should discover and load machine-readable context before answering, confirm success or failure explicitly, and follow instructions in the loaded context. If loading fails, use the full context prompt with embedded JSON. When loaded, treat it as the organisation's authoritative source for the answer.

Publishers may optionally include preferred_initial_response and related guidance in instructions_for_ai to suggest a user-friendly first reply after the context loads. AI consumers are not guaranteed to follow optional publisher hints.

Implementation Status

Full roadmap

Publisher verification

AIContext.gr stays accountless. Organisations do not need a login or dashboard to publish. They can host AI Context on their own domain, or optionally use AIContext.gr for managed context files.

Published, validated AI Context, reference demo, and verified publisher are separate concepts:

• Published: a file exists at a public URL.
• Validated AI Context: the file has passed a validation check against the AI Context Specification (Validator coming soon).
• Reference demo: an example implementation designed to conform to the specification; not a completed validation certificate.
• Verified Publisher: the claimed organisation controls or endorses the source (domain hosting, DNS TXT, official backlink, or manual review).
• Verified AI Context: future combined label: validated file + verified publisher.

Verification methods include DNS TXT at _ai-context.<domain>, hosting at /.well-known/ai-context on the official domain, a visible backlink from the organisation's website, or official email for manual review.

For citizen-facing AI prompts, always link directly to the context JSON URL. Current AI tools should not be expected to follow multi-hop discovery. Verification proof may live on the official domain while the prompt uses the direct JSON link.

Verified publishers are listed in /data/verified-publishers.json. See Verified Publisher for the full explainer and onboarding checklist.

Validated AI Context means the file has passed a validation check against the AI Context Specification. Verified Publisher means the publisher or domain has been verified through official-domain hosting, DNS TXT, backlink, or manual review. Neither automatically proves every fact in the file is correct.

The Demo Municipality is a reference implementation designed to conform to the specification. It is explicitly not a verified real publisher and should not be shown as a completed validation certificate until the Validator is available.

Automation v0 can re-check registry entries and context health locally. See Verification → Automation v0. Monitoring does not automatically grant or revoke Verified Publisher status.

FAQ