Skip to content

API design-time validation — typed rule engine over schemas #189

Closed

Description

@thomas-stegemann

Problem

Most API design issues — inconsistent naming, returning passwords, returning unbounded result lists, missing pagination, missing versioning — are caught by code review IF the reviewer is sharp. They scale exactly with reviewer attention, which doesn't scale. A typed schema is the natural place to express these checks as deterministic rules.

Proposal

A rule engine that runs over schemas (.proto, OpenAPI, GraphQL SDL) and flags violations. Built-in rules, all toggleable:

Naming

  • methods-use-camel-case
  • messages-use-pascal-case
  • fields-no-suffix-id (e.g. userId not user_id_value)

Security

  • no-password-in-response — any field named password / secret / token / api_key in an output type, fail
  • no-pii-in-error-message — error type fields named email / phone / ssn

Versioning

  • request-types-versioned — input types live under a version namespace
  • breaking-change-detection — comparing two schema versions: removed fields without deprecation, type changes

Consistency

  • list-responses-paginated — output that contains a list field must also have a page_token / cursor / next field
  • time-fields-typed — fields named created_at / updated_at use a timestamp type, not a string

Rules ship as plugins so consumers can write their own ("our org bans returning tenant_id").

Acceptance

  • Rule-engine library (typed AST visitor)
  • Built-in rule set (above) toggleable
  • Per-workspace .bowire/rules.json for custom rule selection + config
  • CLI: bowire lint <schema> + as part of bowire test --suite=lint
  • Workbench: rule violations shown inline on the affected method (like inline hints)
  • Plugin SPI for custom rules

Related

  • v2.4 — Dev pillar
  • Pairs with the test pillar (bowire lint reuses the test runner skeleton)
  • Pairs with PR bot (v2.5) — rule violations become PR comments

Activity

  1. moved this to Backlog in Bowireon Jun 15, 2026
  2. thomas-stegemann commented on Aug 17, 2026

    @thomas-stegemann
    MemberAuthor

    Slices 1–3 landed on main

    The typed rule engine + first rule set + per-workspace config are in:

    • Engine — IBowireLintRule seam + BowireSchemaLinter over the BowireServiceInfo tree (the typed schema AST the workbench/bowire diff/PR bot already use). Stable finding order.
    • Built-in rules (5 so far): no-password-in-response (High), PII-in-response (Medium), list-responses-paginated (Medium — input paging param or output cursor field), time-fields-typed (Low, string-typed *_at/*_time/timestamp), missing-versioning (Low).
    • bowire lint <snapshot|url> — text / json / markdown, --fail-on none|info|low|medium|high.
    • .bowire/rules.json — rule on/off + severity overrides, walk-up discovery (mirrors the .bowire/project.json convention — checked-in workspace configuration #172 project-file convention). Linter honours it; CLI --rules <file> + auto-discover.

    ~26 unit tests + CLI smokes, all green.

    Remaining

    • Rest of the built-in set: naming (methods-use-camel-case, messages-use-pascal-case, fields-no-suffix-id), no-pii-in-error, breaking-change-detection (this one reuses bowire diff / BowireSchemaDiff directly).
    • Plugin SPI for custom rules (the IBowireLintRule seam exists; needs assembly-scan discovery).
    • bowire test --suite=lint integration.
    • Workbench inline hints.
  3. thomas-stegemann commented on Aug 17, 2026

    @thomas-stegemann
    MemberAuthor

    Shipped — closing

    Design-time API validation is live across all three surfaces, functionally equivalent:

    • CLI — bowire lint <snapshot|url> (text/json/markdown, --fail-on none|info|low|medium|high, --rules <file>).
    • Web-UI — a Lint rail in the workbench: POST /api/lint runs the linter over the discovered services and the panel lists findings by severity (auto-runs on open).
    • MCP — bowire.lint tool: an agent discovers + lints a URL and gets { findings, summary }. Verified over the real MCP stdio handshake.

    Engine + rules:

    • Typed rule engine (IBowireLintRule + BowireSchemaLinter) over the shared BowireServiceInfo tree.
    • 5 built-in rules: secrets-in-response (High), PII-in-response (Medium), missing-pagination (Medium — input paging param or output cursor), missing-versioning (Low), string-timestamp (Low).
    • .bowire/rules.json — per-rule enable/disable + severity overrides, walk-up discovery.
    • Plugin SPI — IBowireLintRule types in any loaded Kuestenlogik.Bowire* assembly are auto-discovered, so a custom rule lights up on all three surfaces at once.

    ~27 unit tests + CLI/UI/MCP smokes, all green on main.

    Deferred to #583

    The literal inline-hints workbench variant (the shipped UI is a Lint-rail panel), plus the FP-prone naming rules, no-pii-in-error (needs error-type modelling), the bowire test --suite=lint alias (bowire lint --fail-on already gates CI), and folding breaking-change (bowire diff --fail-on breaking / service-compare) into lint. Tracked in #583.

  4. moved this from Backlog to Done in Bowireon Aug 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    • Status
      Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions