An open specification for the q language

Open Q Language describes the q language as a language: what it evaluates, how it prints, what it puts on a wire, and what it writes to disk — so that any implementation can be checked against it, by anyone, without a licensed binary at test time.

It is three things in one repository:

• a normative specification, written as plain text because every ASCII glyph carries meaning in q and markdown formatting would be ambiguous;
• an executable conformance suite — roughly sixteen thousand single-line assertions, each one generated and self-verified against the reference implementation;
• a benchmark harness, so a runtime can be measured on speed as well as correctness.

kdb+ is the reference implementation. Where this specification and the reference disagree, the reference is right and the specification has a bug.

Every rule is observed, never quoted

Nothing here is transcribed from documentation. The wire format was read off a socket. The on-disk layout came from building a database and inspecting the bytes. Where a detail could not be observed — the compressed IPC payload needs a non-loopback peer — the specification says so explicitly instead of guessing.

That discipline has already paid. Reframing an inherited draft against the reference turned up ten claims that said "q" while describing something q does not do: a wrong epoch, attributes described as discarded, mmu described as promoting integers when it signals 'type, and a column-naming rule wrong in two of its four examples.

Assertions, not recorded output

Every corpus line is a self-contained assertion that must evaluate to 1b:

(1+2)~3
(0W+0W)~-2
(@[value;"1 2+1 2 3";{x}]) like "length*"

This matters more than tidiness. The suite used to compare each result's rendered text, which made every test a test of the printer too: a runtime that spells enlist 1 where kdb+ spells ,1 failed thousands of assertions about behaviour it implements perfectly. Moving to ~ cut one runtime's reported failures by 63% without changing the runtime at all.

Rendering is still specified and still tested — deliberately, in one category that owns it.