openquality

# Open Quality

An open corpus of healthcare quality measures, and a shared record of what
implementers have learned about each one. Founder-stewarded today, with a written
commitment to community governance as it grows; see [GOVERNANCE](GOVERNANCE.md)
and [VISION](VISION.md).

Publish a measure in CQL, SQL, or SQL-on-FHIR. Everything is validated, versioned, and
open for review. Alongside the measures sits the part that usually gets lost: a typed
record of interpretation questions, defects, and test cases, attached to the measure and
pinned to a version.

Site: https://openquality.us

## Why this exists

Quality measurement is rebuilt from scratch inside every organization that does it.
Payers, health systems, and vendors each staff teams to implement the same national
measures against their own data, then pay auditors to certify the result. The same
ambiguities in the same specifications get rediscovered independently, the code is rarely
shared, and what one team learns about a measure rarely reaches the next.

There is no common unit for exchanging measure logic, and no shared place to record what
the community has figured out. Open Quality is an attempt at both: a package format
anyone can publish, and a knowledge corpus anyone can read.

The goal is an open marketplace for measure logic. Somewhere to find a measure, see what
other implementers already learned about it, and take the artifacts, without a vendor
contract, a licensing negotiation, or knowing the right person to ask. Today a researcher
or a small team has none of those things, and pays for access or goes without.

Browsing and downloading work now, through the [library](https://openquality.us/library),
a machine-readable [catalogue](https://openquality.us/index.json), and git. Publishing
still goes through a pull request. See [Status](#status).

### Who this is for

Today, getting an answer about a measure depends on knowing the right person.

A recent example. A PhD candidate wrote a Hospital at Home eligibility library that ran
at 30 to 40 seconds per patient. He could not tell whether the cause was his logic, his
engine, or his data. Someone made an introduction to an engineer who had spent years
optimizing CQL. That engineer explained it in one email: defines cache, functions do not,
every retrieve iterates the whole bundle. The library now runs in under a second, and
returns the same results.

That answer existed because of one introduction. It is not searchable, it is not attached
to a measure, and the next person will not find it.

Most people doing this work are not on Zulip, do not attend connectathons, hold no NCQA
support contract, and do not work at an insurer with a staff of analysts. As quality
measurement moves from manual abstraction to digital, they need somewhere to go that does
not depend on who they happen to know.

This is early and honest about it. The package format and the validation core work; the
hosted registry does not exist yet. See [Status](#status).

## How this fits the ecosystem

Open Quality is not another measure engine and not a competitor to the tools people
already rely on. It is the open corpus and community layer that sits alongside them.

- **[cqframework](https://github.com/cqframework)** builds the CQL language, the
  translator, the execution engines, and the annual eCQM/dQM content. Open Quality reuses
  that tooling and shared libraries rather than reinventing them, and points its content
  at the same connectathons.
- **[HL7 CRMI](https://build.fhir.org/ig/HL7/crmi-ig/)** (Canonical Resource Management
  Infrastructure) defines how knowledge artifacts are packaged, versioned, and moved
  through a lifecycle. That is the interoperability target, and Open Quality tracks it
  rather than inventing a parallel model. `oq fhir-bundle` emits the package as a CRMI
  artifact Bundle, the shape CRMI's `$package` operation returns, written as a file
  because there is no server here to run an operation on. `oq fhir-package` emits a FHIR
  NPM package that CQL Studio, the FHIR package registry, and IG Publisher already read.
  Both are built from one list of resources, so the two forms cannot drift apart.

  What still does not exist is a repository *service*: no `$package`, no `$data-requirements`,
  no search API. The artifacts are CRMI-shaped; the operations are not implemented.

  Format is deliberately not the product. Open Quality aims to ingest whatever standard
  format a tool already emits, so nobody has to adopt anything of ours to publish here.
  What is missing from the ecosystem is not another way to package a measure. It is an
  open place to find one. See [`spec/`](spec/).
- **Reason Health / ReasonHub** and other CRMI-native platforms are authoring and
  syndication systems. Open Quality is deliberately the *open, public-good* end of the
  same space, and aims to interoperate, not overlap.
- **[The FHIR package registry](https://registry.fhir.org)** distributes FHIR conformance
  artifacts, and does that well. It answers "where do I get this package." It is not built
  to answer "why is this measure slow," "does a missing HbA1c count as poor control," or
  "how did someone else read this denominator." Different problem, not a smaller one.
- **[NCQA's Digital Quality Implementers Community](https://www.ncqa.org/digital-quality-implementers-community/)**
  (DQIC) is a consensus effort focused, in NCQA's own description, first on *CQL engines*,
  with other tooling and languages as future work. Engines are well covered. Measures and
  analytics practice are not.

What Open Quality adds that isn't already covered: radical openness, first-class support
for **SQL and SQL-on-FHIR** (not just FHIR-canonical artifacts), and the
[knowledge corpus](#the-knowledge-corpus) of interpretation issues.

Being open source is also what makes the corpus possible. There is no HEDIS license to
negotiate and no legacy vendor to pay for the right to discuss a measure in public.

## Status

Pre-launch.

| Piece | State | What it is |
|-------|-------|------------|
| Package format | shipped | Manifest schema, conformance levels, license policy, content scanning, provenance |
| Validation core | shipped | Validates a package directory and computes its level |
| `oq` CLI | shipped | `oq validate`, `oq validate-all`, `oq pack`, `oq fhir-package`, `oq fhir-bundle` |
| Seed corpus | shipped | 52 CC0 eCQM packages imported from cqframework, plus the 17 shared CQL libraries they depend on as packages of their own, with a CI drift check |
| MCP server | shipped | Read-only, five tools, at `https://openquality.us/mcp`; see [below](#connecting-an-agent-or-ide-mcp) |
| Deep validators | next | CQL to ELM, FHIR profile validation, SQL parsing, VSAC resolution |
| Registry | planned | Publish, search, install |
| Registry-hosted feedback | planned | The [`knowledge/`](knowledge/) corpus, searchable and writable from a web UI instead of a pull request |

Local validation stops at Level 1, and so does the seeded corpus. Level 2 needs
the deep validators, which do not exist yet.

## Repository map

This is a single repository, laid out so the intent is legible at a glance.

| Path | What lives here |
|------|-----------------|
| [VISION.md](VISION.md) | The problem, the mission, and the next year's goals |
| [`spec/`](spec/) | The package format, the conformance levels, and the CRMI mapping |
| [`measures/`](measures/) | Measure package collections, indexed by data model and year |
| [`knowledge/`](knowledge/) | The interpretation-issue corpus — questions, defects, and test cases per measure |
| [`TERMINOLOGY.md`](TERMINOLOGY.md) | Which code systems may be redistributed, and with or without display text |
| `packages/` | The tooling: `@openquality/core`, the `oq` CLI, the importer, and the MCP server (`@openquality/mcp`) |
| `site/` | The openquality.us front end, and the hosted MCP endpoint (`site/api/mcp.ts`) |
| `docs/` | Design specs, implementation plans, and the [connectathon scenario](docs/connectathon-clinical-reasoning.md) |

## Try it

Requires Node 22 and pnpm.

```bash
pnpm install
pnpm test
pnpm oq validate-all measures/cms-fhir-2026
```

Expected output:

```text
Checked 69 packages, 0 below Level 1
```

That is 52 measures and the 17 shared CQL libraries they depend on, each published once.

## Reading the corpus from a tool

There is no registry server, and a tool that wants to list or fetch packages does not
need one. The whole read interface is one static document:

```text
https://openquality.us/index.json
```

No credentials, no OAuth, no host for anyone to run. It lists every package with its
id, version, steward, data model, licence, conformance level, and the repository paths
of its manifest and artifacts, plus every knowledge entry. A client reads it, decides
what it wants, and fetches those paths from the `raw` base URL the document names.

The conformance level in that file is computed by running the same validator
`oq validate` runs, not asserted, and CI fails if the file drifts from the corpus it
describes.

`ref` is `main`, which moves. Pin a commit or tag and substitute it into `raw` if you
need the same bytes twice.

## Connecting an agent or IDE (MCP)

The corpus is also served over the [Model Context Protocol](https://modelcontextprotocol.io),
so a coding agent can read a measure's code and the context around it while you work:

```text
https://openquality.us/mcp
```

Streamable HTTP, read-only, no account or key. In Claude Code:

```bash
claude mcp add --transport http openquality https://openquality.us/mcp
```

It is listed in the official [MCP Registry](https://registry.modelcontextprotocol.io)
as `us.openquality/mcp`. Configs for Cursor, VS Code and the MCP Inspector are at
[openquality.us/mcp-setup](https://openquality.us/mcp-setup).

| Tool | Returns |
|------|---------|
| `search_measures` | Packages matching a CMS id, title words, steward or package id |
| `get_measure` | License, provenance