Skip to content

v0.4.0

Released: 2026-07-06

This release significantly expands the profile system with new built-in profiles, SDK-optimized rules, and adds the score-profile command for LLM-based profile quality evaluation.

Highlights

  • Default profile expanded to 106 rules with SDK generation optimization (ogen, openapi-generator)
  • New built-in profiles: comprehensive, minimal, microsoft-rest, microsoft-graph
  • New score-profile command for evaluating style guide quality using LLM-as-Judge
  • JSONPath validation system to prevent linting crashes from unsupported expressions

Installation

go install github.com/plexusone/api-style-spec/cmd/api-style@v0.4.0

Upgrade from v0.3.0

No breaking changes. All v0.3.0 commands continue to work.

New features:

  1. Use api-style score-profile <profile> to evaluate profile quality
  2. New profiles available: comprehensive, minimal, microsoft-rest, microsoft-graph
  3. Default profile now has 106 rules optimized for SDK generation

Features

Expanded Default Profile

The default profile has been completely rewritten with 106 rules across 27 categories:

  • SDK-optimized patterns for ogen and openapi-generator
  • Multi-tenancy support with ~ alias for current tenant context
  • RFC 9457 Problem Details for standardized error responses
  • Cursor-based pagination with nextCursor/hasMore pattern
  • Discriminated unions for clean polymorphism in generated code
  • CloudEvents format for webhooks and events

New Built-in Profiles

Profile Rules Categories Focus
comprehensive 88 26 Full coverage across all API design areas
minimal 29 7 Basic API hygiene for simple APIs
microsoft-rest 123 15 Enterprise REST APIs following Microsoft patterns
microsoft-graph 82 12 OData-based APIs for Microsoft 365 integration

Score Profile Command

Evaluate style guide quality using LLM-as-Judge:

# Score the default profile
api-style score-profile default

# Score with JSON output
api-style score-profile azure --format json

# Score a custom profile file
api-style score-profile ./custom-profile.json --output scores.json

Evaluates profiles on:

  • Content coverage and depth
  • Rule quality and examples
  • Enforceability ratio (Spectral vs LLM-only)
  • Consistency and accessibility

JSONPath Validation

Rules with unsupported JSONPath expressions are now automatically detected and disabled for Spectral linting while remaining available for LLM evaluation:

  • Filter expressions [?(@...)] detected
  • Quoted keys with special characters ['application/json'] detected
  • Keys starting with $ (like .$ref) detected

This prevents vacuum parser crashes while maintaining full rule coverage via LLM.

New CLI Commands

score-profile

Flag Short Default Description
--format -f text Output format: text, json
--output -o stdout Output file path
--model -m claude-3-5-haiku LLM model to use

Bug Fixes

  • Fixed Spectral ruleset generation for truthy/falsy functions (now outputs field instead of functionOptions.match)
  • Fixed error handling in file watcher (proper cleanup on close)
  • Fixed error comparison for context cancellation (use errors.Is)

Documentation

  • Profile documentation for all new profiles (comprehensive, minimal, microsoft-rest, microsoft-graph)
  • Updated default profile documentation with accurate rule counts
  • Profile comparison and scoring guides
  • Compliant API example demonstrating all style patterns
  • CLI documentation for score-profile command

Dependencies

  • Updated github.com/daveshanley/vacuum from v0.29.4 to v0.29.9
  • Updated github.com/plexusone/assistantkit from v0.13.0 to v0.14.0