AI support on specifications.openehr.org

Specifications
, ,
1

Hi all,

Over the past weeks I’ve been working on a set of changes to specifications.openehr.org aimed at making the openEHR specifications easier for LLMs, AI assistants, and agent-based tools to read, cite, and reason about — while at the same time reducing load and token usage on the hosting side.

Why bother

When someone asks ChatGPT, Claude, Gemini or a coding agent a question about openEHR, those assistants end up fetching and paraphrasing from this very site. A cleaner surface means more accurate citations back to the normative specs — assistants that quote us correctly rather than hallucinate around the edges. There’s also a hosting angle: AI systems typically issue 10–16 parallel sub-queries per user question, and for a small standards site that traffic adds up fast.

What changed

  • Robots and sitemap tuning. Per-bot crawl delays for the major AI crawlers, and proper <priority> / <changefreq> signals in the sitemap so crawlers understand that released specifications never change once published.
  • An /llms.txt index. Following the emerging llmstxt.org convention — still a proposal rather than a formal standard, but already honoured by most of the major engines — a curated plain-text map of the site is now at specifications.openehr.org/llms.txt.
  • A Markdown representation of every spec page. Append .md to any spec URL, or send Accept: text/markdown. That cuts per-page token cost by roughly 80% compared with the rendered HTML. Class attribute and function tables remain HTML-only for now; /api/classes.json resolves any class name to its authoritative location.
  • Structured JSON APIs. Small, cache-friendly endpoints under /api/ (components.json, classes.json, releases.json) for tool-builders, MCP servers, and RAG pipelines that want the catalogue without scraping HTML.

None of this changes what we see as human readers, and the normative specification content is untouched.

There are a few more features planned on this AI domain, also as we move to Antora based rendering, but they will come a bit later.

Feedback welcome. Two questions in particular:

  • If you work on tooling — MCP servers, copilots, openEHR SDKs, internal RAG systems — would these representations be useful as they stand? What else would help?
  • If you’ve caught an AI assistant giving an inaccurate answer about the openEHR specifications, please share the example. Concrete cases are genuinely useful for evaluating whether these changes actually move the needle.

Best regards,
Sebastian

2

Thanks @sebastian.iancu this is great work - incredible progress and very useful to the community. Great to have the JSON, Markdown, and text endpoints. I’ll keep an eye on the server load on specifications but over the past 30 days it hasn’t been over 20% and both disk IO and network traffic are fine.

With similar intentions, I’ve installed a plugin which generates llms.txt for this forum as well, which can help in researching things like the practicalities of openEHR clinical modelling, and other ‘softer’ non-specification questions. The URL is https://discourse.openehr.org/llms-full.txt and as per the Specifications it enables LLMs a cleaner view of the forum’s content.

Nothing is visible in llms.txt that wasn’t already public to the internet, the plugin doesn’t divulge anything that was login-only or private.

3

@sebastian.iancu, great work! Perheps the links in https://specifications.openehr.org/llms.txt should point to the .md rather than .html files, so:

  • ADL 2: Archetype Definition Language 2
    …rather than…
  • ADL 2: Archetype Definition Language 2
4

By the way @sebastian.iancu is something like this already available or planned in your MCP tooling: Creating a GraphRAG index for openEHR documentation ?

5

Well, I was actually looking into something like this - but not particularly this solution, I was not aware of MS support; I might need to re-asses and adapt…
Bu anyways, I am looking/planning for something similar - just that I don’t have time right now to explore it.