Research: industry rulesets, and why there is only one

_posts/2026-09-11-one-industry-ruleset.md

@@ -0,0 +1,96 @@
+---
+title: One industry ruleset
+description: >-
+  The ecosystem has exactly one ruleset encoding an industry standard. Not because the demand is
+  missing, but because nobody has said what such a ruleset is allowed to claim.
+---
+
+Count the rulesets that encode an industry standard and the answer is **one**. OWASP API Security,
+published by Stoplight, last functionally changed in September 2024, twenty-one open issues.
+
+There is no FHIR ruleset. There has never been one — not on npm, not in the `stoplightio`
+organization, and not at any point in the history of the project's own community index, which has
+never contained the word. No ISO 20022. No FDX, CAMARA, TM Forum, Peppol, or X12.
+
+Meanwhile the same ecosystem happily carries a dozen **vendor** style guides — Adidas, Azure,
+DigitalOcean, Red Hat, IBM Cloud. Those exist because they have an obvious owner with an obvious
+motive. An industry standard has neither: the body publishing it is not in the linting business, and
+every organization implementing it solves the problem privately, if at all.
+
+The [full research is here](/research/industry-rulesets/), read against a public catalog of 610
+standards. This is the short version.
+
+## It is not a demand problem
+
+The catalog types 118 standards as industry standards — call it 95 after stripping catalog buckets
+and Java platform specs that got filed under the same label. Where implementer counts exist, they
+cluster hard in payments and healthcare: NACHA at 83 companies, ISO 20022 at 27, FHIR and EDIFACT at
+20 each, FIX at 13, DICOM and ISO 8583 at 11.
+
+So the demand is there and it is concentrated. Which makes the absence of rulesets a design failure
+rather than an appetite one.
+
+## It is a "what can this thing even see" problem
+
+A ruleset lints a structured document. That is the entire capability. Sort industry standards by
+whether a linter can inspect the thing at all, and they fall into three tiers that are nothing like
+each other.
+
+**Tier A — the standard is an API description.** The body publishes OpenAPI, conformance is a
+property of the description, and a ruleset can check it directly. CAMARA, TM Forum, FDX, UK Open
+Banking, Berlin Group, the Australian CDR, OGC API, RESO. **This tier is servable today and nothing
+serves it.**
+
+**Tier B — the standard is a data model appearing inside descriptions.** FHIR, US Core, GS1, MISMO,
+ACORD. A ruleset can check a useful subset — required elements present, obvious cardinality
+violations, declared extensions — and it **cannot** validate conformance, because conformance is
+defined against profile logic living outside the description. Most useful tier, most dangerous tier.
+Passing is not conformance, and a badge implying otherwise is worse than no badge.
+
+**Tier C — the wire format is not a structured document.** NACHA is fixed-width files. X12 and
+EDIFACT are segment grammars. FIX is tag-value, ISO 8583 is bitmapped binary, HL7 v2 is
+pipe-delimited. A JSON linter cannot see any of it.
+
+Now re-read the demand table. **The standard with the largest implementer count is the one a ruleset
+can say least about.** That inversion is the actual story, and it is why "just write more rulesets"
+has never worked.
+
+## What the format is missing
+
+Four things, and none of them is more rules.
+
+**A ruleset cannot declare what it encodes, or which version.** "FHIR" is not a version — R4 and R5
+differ, US Core layers on both, and a rule correct for one is wrong for another. There is no
+vocabulary for stating this, which is why nobody can tell whether a published ruleset is current.
+
+**A ruleset cannot declare what it does not check.** Tier B stated as a format feature. Without it
+every industry ruleset silently overclaims, and any conformance badge inherits the overclaim.
+
+**Composition has no precedence.** House style plus OWASP plus a regulator is the normal case. When
+a regulator's naming requirement contradicts a house style — and it will — nothing says which wins.
+
+**And the maintenance model is the real blocker.** Standards bodies version on their own cadence and
+are not going to maintain rulesets. Three of the ecosystem's four published add-on rulesets have been
+unmaintained since 2024. Any design assuming a maintainer per standard is designing for a world that
+has not existed once.
+
+Underneath all of it, the distribution problem: fifteen of the nineteen entries in the community
+index are consumed by pointing at a file path in a Git repository. No version, no integrity, no
+release.
+
+## Where a first one starts
+
+Not with FHIR, despite it being the obvious flag to plant.
+
+The criteria that fall out of the above are: Tier A, so the ruleset can assert conformance rather
+than a proxy for it; a body already publishing machine-readable artifacts, so rules are derived
+rather than transcribed from a PDF; real implementer count; and a live conformance question somebody
+wants answered.
+
+That points at **FDX and CAMARA** first. FHIR is the more valuable target and the harder one, and
+taking it second rather than first is the difference between a demonstration and an overclaim.
+
+This is all argued at [spotlight-spec#21]({{ site.repo_rules }}/issues/21), which asks where industry
+rulesets sit in the layer model. The answer this research suggests is that they cannot just be filed
+somewhere — the layer has to say what a ruleset of this kind is permitted to claim. Otherwise the
+first serious industry ruleset ships with a badge nobody should trust.

research/index.md

@@ -84,6 +84,20 @@ open.
     </div>
   </div>
 
+  <div class="col-md-4">
+    <div class="card shadow-sm">
+      <div class="card-body d-flex flex-column">
+        <h5 class="card-title">Industry rulesets, and why there is only one</h5>
+        <p class="card-text flex-grow-1 small">
+          The ecosystem has exactly one ruleset encoding an industry standard, against a public
+          catalog tracking over a hundred. Sorted by what a linter could actually check — and why
+          the most-implemented standards are the ones it can say least about.
+        </p>
+        <a href="/research/industry-rulesets/" class="fw-semibold">Read →</a>
+      </div>
+    </div>
+  </div>
+
 </div>
 
 ---

research/industry-rulesets.md

@@ -0,0 +1,181 @@
+---
+layout: default
+nav: research
+title: Industry rulesets, and why there is only one
+description: >-
+  The ecosystem has exactly one industry ruleset. A public catalog tracks over a hundred industry
+  standards. The gap is not appetite — it is that nobody has said what an industry ruleset is
+  allowed to assert.
+permalink: /research/industry-rulesets/
+---
+
+# Industry rulesets, and why there is only one
+
+Governance conversations reach the same place every time: *we need the OWASP rules, and our own
+house rules, and whatever our regulator requires.* The first two are solved. The third is almost
+entirely unbuilt, and the reason is more interesting than "nobody got round to it."
+
+This page is the evidence behind [spotlight-spec#21]({{ site.repo_rules }}/issues/21), which asks
+where industry rulesets sit in the layer model. It argues that the question cannot be answered by
+filing them — the layer has to say what a ruleset of this kind is *allowed to claim*, and that turns
+out to differ enormously by standard.
+
+> **Disclosure.** The standards catalog used below as a demand signal is
+> [API Evangelist Standards](https://standards.apievangelist.com), which is maintained by the same
+> person who maintains this fork. It is used here because it is public, sizeable and checkable — not
+> because it is neutral. Treat it as one worked dataset, not as the industry's register. Anyone with
+> a better one should say so.
+
+---
+
+## What exists
+
+**One industry ruleset.** [OWASP API Security](https://github.com/stoplightio/spectral-owasp-ruleset),
+published by Stoplight, last functionally changed September 2024, 21 open issues.
+
+That is the entire tier. There is no FHIR ruleset — not on npm, not in the `stoplightio`
+organization, and not at any point in the history of the project's own
+[community index](https://github.com/stoplightio/spectral-rulesets), which has never contained the
+string. No ISO 20022 ruleset. No FDX, no CAMARA, no TM Forum, no Peppol, no X12.
+
+For contrast, the same ecosystem carries a dozen or more **vendor style guides** — Adidas, Azure,
+DigitalOcean, Red Hat, IBM Cloud, VTEX, SPS Commerce — because those have an obvious owner with an
+obvious motive. Industry standards have neither. The body that publishes the standard is not in the
+linting business, and the organizations implementing it each solve it privately, if at all.
+
+## What is being tracked
+
+The catalog holds **610 standards**, of which **118 are typed `industry-standard`** and 37 more are
+`regulation-compliance`.
+
+Two honest caveats before anyone quotes the 118:
+
+- **It is not 118 candidates.** Roughly two dozen entries are either catalog buckets ("ISO",
+  "ISO Standard", "IT Standards", "Health Standards", "Accounting Standards") or Java platform
+  specifications filed under the same type (Java EE, Jakarta EE, JPA, JSF, JAX-WS, Bean Validation,
+  JSR-303). The realistic count of distinct vertical standards is closer to **95**. That is a data
+  quality note for the catalog, not a criticism of the number.
+- **Demand data is partial.** Only 25 of the 118 carry a company count, so the ranking below covers
+  a fifth of the set and undercounts everything else.
+
+Where company counts do exist, they point somewhere specific:
+
+| Standard | Companies |
+|---|---|
+| [NACHA](https://standards.apievangelist.com/store/nacha) | 83 |
+| [ISO 20022](https://standards.apievangelist.com/store/iso-20022) | 27 |
+| [HL7 FHIR](https://standards.apievangelist.com/store/fhir) | 20 |
+| [EDIFACT](https://standards.apievangelist.com/store/edifact) | 20 |
+| [FIX Protocol](https://standards.apievangelist.com/store/fix-protocol) | 13 |
+| [DICOM](https://standards.apievangelist.com/store/dicom) | 11 |
+| [ISO 8583](https://standards.apievangelist.com/store/iso-8583) | 11 |
+| [X12 EDI](https://standards.apievangelist.com/store/x12-edi) | 8 |
+| [HL7 v2](https://standards.apievangelist.com/store/hl7-v2) | 5 |
+| [FDX](https://standards.apievangelist.com/store/fdx) | 3 |
+
+Payments and healthcare, overwhelmingly. Which is what you would expect, and also — as the next
+section shows — the worst possible news for a linter.
+
+## The problem nobody has named
+
+**A ruleset lints a structured document.** That is the whole capability. It can assert things about
+an OpenAPI, AsyncAPI or Arazzo description, or any JSON/YAML you point it at.
+
+Most industry standards are not structured documents in that sense. Sorting the catalog by *what a
+ruleset could actually check* produces three very different tiers, and they are not equally
+serviceable.
+
+### Tier A — the standard *is* an API description
+
+The body publishes OpenAPI (or equivalent), and conformance is a property of the description. Here a
+ruleset can check real conformance: required paths present, response schemas matching, naming
+conventions held, mandatory security schemes declared.
+
+Examples: CAMARA, TM Forum Open API, FDX, UK Open Banking, Berlin Group NextGenPSD2, Australian
+Consumer Data Standards, OGC API, RESO Web API, CDS Hooks, GSMA Open Gateway.
+
+**This tier is genuinely servable today, and nothing serves it.**
+
+### Tier B — the standard is a data model that shows up inside API descriptions
+
+FHIR, US Core, USCDI, C-CDA, GS1, MISMO, HR Open, ACORD. The standard defines resources and fields.
+An API implementing it usually has an OpenAPI description whose schemas *should* reflect the model.
+
+A ruleset here can check a meaningful subset — that a resource named `Patient` carries the elements
+the profile requires, that cardinality is not obviously violated, that required extensions are
+declared. It **cannot** validate conformance, because conformance is defined against
+StructureDefinitions and profile logic that live outside the description entirely.
+
+This is the tier where a ruleset is most useful and most dangerous. Useful because it catches the
+common errors early and cheaply. Dangerous because **passing it is not conformance**, and a badge
+that implies otherwise is worse than no badge.
+
+### Tier C — the wire format is not a structured document at all
+
+NACHA (fixed-width files), X12 and EDIFACT (segment grammars), FIX (tag-value), ISO 8583 (bitmapped
+binary), DICOM (binary), HL7 v2 (pipe-delimited). A JSON/YAML linter cannot inspect any of these.
+
+Note what this does to the demand table above: **the standard with the largest company count in the
+catalog is the one a ruleset can say least about.** The most a ruleset can do here is govern the API
+*around* the format — that an endpoint accepting NACHA files declares the right content type, sets a
+size limit, documents its error semantics. Worth doing, easy to oversell.
+
+## What this means for the layer model
+
+The classification above is a first pass and is offered as something to argue with rather than as a
+finished taxonomy. But it already forces four requirements onto whatever #21 lands on:
+
+1. **A ruleset must be able to declare what it encodes, and which version.** "FHIR" is not a
+   version. R4 and R5 differ, US Core layers on top of both, and a rule written for one is wrong for
+   another. Today a ruleset cannot say this at all, which is why nobody can tell whether a published
+   ruleset is current.
+2. **A ruleset must be able to declare what it does *not* check.** This is the Tier B problem stated
+   as a format feature. Without it, every industry ruleset silently overclaims, and the conformance
+   badge in [#10]({{ site.repo_rules }}/issues/10) inherits the overclaim.
+3. **Composition needs precedence.** House style plus OWASP plus a regulator's rules is the normal
+   case, not the exotic one. When they disagree — and a regulator's naming requirement will disagree
+   with a house style — something has to say which wins, and the format currently has no vocabulary
+   for it.
+4. **The maintenance model is the actual blocker.** Standards bodies version on their own cadence
+   and are not going to maintain rulesets. Three of the ecosystem's four published add-on rulesets
+   have been unmaintained since 2024. A layer model that assumes a maintainer per standard is
+   designing for a world that has not existed once.
+
+And the distribution problem underneath all of it: fifteen of the nineteen entries in the community
+index are consumed by pointing at a file path in someone's Git repository. No version, no integrity,
+no release. Whatever industry rulesets turn out to be, they cannot be distributed that way.
+
+## Where a first one should start
+
+If the point is to prove the tier is servable rather than to boil the ocean, the selection criteria
+fall out of the above:
+
+- **Tier A**, so the ruleset can assert conformance rather than a proxy for it.
+- **A body that already publishes machine-readable artifacts**, so the rules can be derived from a
+  source of truth rather than hand-transcribed from a PDF.
+- **Real implementer count**, so it is used.
+- **A live conformance question**, so someone cares about the answer.
+
+On those criteria the catalog points at **FDX** and **CAMARA** ahead of FHIR — not because they
+matter more, but because they are the two where a ruleset can make a claim it can actually stand
+behind. FHIR is the more valuable target and the harder one, and doing it second rather than first
+is the difference between a demonstration and an overclaim.
+
+## Open
+
+- Is "industry" a dimension of the layer model, or a well-known custom ruleset? This page argues it
+  has to be a dimension, on the strength of requirements 1 and 2 — but that is an argument, not a
+  finding.
+- Who is the maintainer of an industry ruleset when the standards body will not be?
+- Does a Tier B ruleset that cannot assert conformance still deserve the standard's name in its
+  title? "FHIR ruleset" and "some FHIR checks" are different products.
+- What happens to a published ruleset when the standard versions and nobody updates it? Silence is
+  the current answer, and silence is how the existing three got to 2026.
+
+<div class="card bg-light border-0 mt-4">
+  <div class="card-body text-center py-4">
+    <p class="mb-3">Disagree with the tiers, or know of an industry ruleset this missed?</p>
+    <a class="btn btn-primary" href="{{ site.repo_rules }}/issues/21">Argue on the issue →</a>
+    <a class="btn btn-outline-secondary ms-2" href="{{ site.discussion }}">Or in the discussion →</a>
+  </div>
+</div>