Research: the alias layer as it actually is, plus a post published today arguing spotlight-spec#20

[kinlane]

Adds a research page on how aliases actually work today, and a post for 2026-09-11 arguing the case in api-commons/spotlight-spec#20.

Both were read from @stoplight/spectral-core 1.23.1 as vendored at v6.16.2, plus the published ruleset schema — not from memory. The research page cites files for every claim so it can be checked and shown wrong.

What is here

• research/aliases.md → /research/aliases/ — the evidence. Both alias forms, the six that ship built-in, the extends boundary, three behaviours worth knowing, and an explicit list of four things the read could not settle.
• research/index.md — a fourth card, and a "Format behaviour" note in the Method section.
• _posts/2026-09-11-… — the argument, at a slightly higher altitude, linking out to the research page.

The finding that matters

Aliases do not cross extends, and it is deliberate. A rule resolves against the ruleset it was written in, not the one it runs in. The test is named should refuse to resolve externally defined aliases.

So an alias is private to the file that declares it — which is why the JSONPath criticism survives a feature built to answer it. Everyone extending the OpenAPI ruleset redeclares PathItem themselves or goes back to raw JSONPath.

The refusal also buys something real: two extended rulesets can define the same alias name differently and never collide, with a fixture asserting exactly that. Both documents say so. #20 inherits that problem rather than dodging it.

None of this is documented outside a test name.

Also worth noting: six aliases ship, all in oas. AsyncAPI and Arazzo define none, against a standing promise in docs/guides/4c-aliases.md that the core rulesets would ship a common set for both.

Notes

• The post is future-dated, so it will not appear until 2026-09-11. Merging is safe before then.
• Jekyll builds clean locally with --future; the page and post render, and the index card links correctly.
• Three claims in the research page are flagged inline as code-reads with no test either way, rather than stated as fact.

[kinlane]

Re-dated the post from 2026-09-11 to 2026-08-17 — it now publishes on merge rather than waiting three weeks. The three later posts (08-21, 08-28, 09-04) stay queued and are still skipped by the build.

Verified with a plain jekyll build (no --future): the post renders at /2026/08/17/…, and the other three are correctly skipped as future-dated.

One consequence worth naming — this lands ahead of the 08-21 and 08-28 posts that were written before it, so the blog order is now alias post, then those. Nothing in them depends on reading order.