From 251c16513d345a74c139f61c1540eb370bf07edf Mon Sep 17 00:00:00 2001 From: SyniRon <66834451+SyniRon@users.noreply.github.com> Date: Sun, 7 Jun 2026 03:01:33 -0400 Subject: [PATCH] openapi: document position-search empty-result semantics (#137 ruled expected) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Diagnosis on the mirror confirmed the matcher is a correct case-insensitive unanchored substring LIKE (squad leader: 0 rows; section leader: 125; SECTION LEADER: 125; platoon leader: 22 — through the exact join+filter shape). Empty results are data-truthful: the org's billet vocabulary has Section/Platoon Leaders, no "Squad Leader" title. Closes #137 Co-Authored-By: Claude Opus 4.8 (1M context) --- openapi/openapi.yaml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 4ebac82..e9f3344 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -313,10 +313,17 @@ paths: get: operationId: MilpacService_SearchByPosition summary: Search for profiles by position title + # Empty-result semantics ruled expected at #137: the matcher was + # verified correct against the mirror; {} is data-truthful when the + # phrase occurs in no current position title. description: >- - Search for profiles by position title substring (SQL LIKE '%query%' - against primary and secondary-capable position titles); returns lite - profiles. The live route is a multi-segment glob + Search for profiles by position title substring (SQL LIKE '%query%', + case-insensitive, unanchored, against primary and secondary-capable + position titles); returns lite profiles. An empty profiles map means + no current position title contains the query — terms must follow the + unit's own billet vocabulary (line leadership is "Section Leader" / + "Platoon Leader"; there is no "Squad Leader" billet, so that query + returns {}). The live route is a multi-segment glob ({position_query=**}, proto/milpacs.proto): slashes inside the query and the bare trailing-slash form also reach the handler — forms an OpenAPI path template cannot express; this document records the