feat(openapi): emit segment + status as enums with real values#205
Merged
texture-fleet-agent[bot] merged 1 commit intomainfrom May 6, 2026
Merged
feat(openapi): emit segment + status as enums with real values#205texture-fleet-agent[bot] merged 1 commit intomainfrom
texture-fleet-agent[bot] merged 1 commit intomainfrom
Conversation
Update the OpenAPI generator to accept enum hints in the per-resource
descriptions map. When a field's description is an `{ description, enum }`
object (instead of a plain string), the generator emits both a real
`enum` array and the description in the resulting schema.
Populated Utility.segment with the actual ownership categories returned
by the API (COMMUNITY_CHOICE_AGGREGATOR, DISTRIBUTION_COOPERATIVE,
GENERATION_AND_TRANSMISSION, INVESTOR_OWNED_UTILITY, MUNICIPAL_UTILITY,
POLITICAL_SUBDIVISION, TRANSMISSION_OPERATOR) instead of the incorrect
"One of: electric, gas, water, combined" placeholder.
Also emitted Utility.status as a real enum (ACTIVE, DEFUNCT, MERGED)
since it's similarly backed by a small finite set. Both sourced from
`SELECT DISTINCT <col> FROM utilities WHERE deleted_at IS NULL`.
Backwards compatible: existing descriptions stay as plain strings; only
fields that explicitly opt into the object form get an `enum` in the
spec. The FieldDescriptionMap type now supports both shapes, and the
generator switches on typeof value === "string".
Regression coverage in scripts/openapi/openapi-enum.test.ts asserts the
segment + status enums are present, uppercase snake_case, contain the
key values consumers filter on, and that the old "electric, gas, water"
description is gone.
From Morgan's Relay bug report (memory/specs/relay-commongrid-bugs-2026-05-06.md),
bug #6.
Fixes ALL-734
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fix the OpenAPI spec so
Utility.segmentis a real enum with the actual values returned by the API, not the\"One of: electric, gas, water, combined\"placeholder that's been misleading consumers.Also enumerated
Utility.statuswhile I was in the file (small finite set, same treatment).Before vs. after
Before:
```json
"segment": {
"type": "string",
"description": "One of: electric, gas, water, combined"
}
```
After:
```json
"segment": {
"type": "string",
"description": "Ownership / structural category of the utility. Sourced from EIA Form 861 filings plus manual review.",
"enum": [
"COMMUNITY_CHOICE_AGGREGATOR",
"DISTRIBUTION_COOPERATIVE",
"GENERATION_AND_TRANSMISSION",
"INVESTOR_OWNED_UTILITY",
"MUNICIPAL_UTILITY",
"POLITICAL_SUBDIVISION",
"TRANSMISSION_OPERATOR"
]
}
```
Approach
The generator's
FieldDescriptionMaptype now accepts either a plainstring(backwards compatible — unchanged for every other field) or an{ description, enum }object. When the object form is used, the generator emits a realenumarray in the schema.The enum values are pulled from the live DB:
```
SELECT DISTINCT segment FROM utilities WHERE deleted_at IS NULL ORDER BY segment;
```
Written next to the enum in a comment so the next engineer knows exactly how to refresh it if a new segment gets added (rare).
Test
scripts/openapi/openapi-enum.test.ts— asserts segment + status emit as enums, have the key values, use uppercase snake_case, and the old buggy description is gone.npm run test→ 101/101 passing.npm run lint:biomeclean for touched files.npm run buildclean.npm run openapi:checkclean.Context
From Morgan's Relay bug report (2026-05-06), bug #6. Full report:
memory/specs/relay-commongrid-bugs-2026-05-06.md.Cost Morgan some real time — initially filtered `segment=ELECTRIC_COOPERATIVE` (returned 0) before discovering the real value is
DISTRIBUTION_COOPERATIVE. This should prevent that flavor of bug for future consumers.Fixes ALL-734