Skip to content

v0.3.0

Released: 2026-06-22

This release adds extended type definitions for rich documentation, MkDocs site generation, LLM evaluation rubric generation, and vendor API style profiles for reference implementations.

Highlights

  • Extended type definitions for patterns, principles, glossary, decision tables, and migration guidance
  • MkDocs multi-page documentation site generator with Material theme support
  • Rubric generation for structured-evaluation LLM-as-Judge integration
  • Vendor API style profiles (Microsoft Graph, Microsoft REST, PayPal, Zalando, etc.)

Installation

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

Upgrade from v0.2.0

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

New features:

  1. Use api-style generate mkdocs to create full documentation sites
  2. Use api-style generate rubric for LLM evaluation integration
  3. Extended profile format supports patterns, principles, and glossary sections

Features

Extended Type Definitions

New types for comprehensive API style documentation:

  • Pattern - Reusable API design patterns with problem/solution/when-to-use
  • Principle - High-level design principles with related rules
  • GlossaryTerm - Terminology definitions with aliases
  • Section - Document structure for navigation
  • DecisionTable - Structured decision guidance
  • DetailedExample - Rich examples with code annotations
  • MigrationGuidance - Instructions for fixing violations
  • RuleApplicability - Conditional rule application logic
  • DeprecationInfo - Deprecation tracking for rules

Enhanced Rule type with:

  • description vs rationale distinction
  • Priority and version fields
  • Decision tables and migration guidance
  • Conditional applicability
  • Enhanced judge criteria with pass/partial/fail definitions

MkDocs Site Generator

Generate complete MkDocs documentation sites:

api-style generate mkdocs --profile zalando --output ./docs

Features:

  • Material theme with dark mode, navigation tabs, search
  • Automatic navigation structure from content
  • Separate pages for principles, patterns, rules, glossary
  • Mermaid diagram support
  • Code highlighting with copy buttons
  • Optional pattern splitting (one page per pattern)

Generated structure:

output/
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── introduction.md
    ├── principles.md
    ├── patterns.md
    ├── conformance.md
    ├── glossary.md
    └── rules/
        └── {category}.md

Rubric Generation

Generate structured-evaluation rubrics for LLM-as-Judge evaluation:

api-style generate rubric --profile azure --output rubric.json

The generator:

  • Groups rules by category into rubric categories
  • Converts error-severity rules to required criteria
  • Aggregates pass/partial/fail criteria from rule definitions
  • Includes few-shot examples for each category
  • Sets pass criteria (no critical/high findings allowed)

Compatible with the structured-evaluation framework.

Vendor API Style Profiles

Reference implementations demonstrating the extended type system:

Profile Source
microsoft-graph Microsoft Graph API Guidelines
microsoft-rest Microsoft REST API Guidelines
omniagent-rest OmniAgent REST API Guidelines
paypal-rest PayPal REST API Guidelines
plexusone-rest PlexusOne REST API Guidelines
zalando-rest Zalando RESTful API Guidelines

Each profile includes:

  • *.api-style.json - Full specification
  • *.api-style.md - Generated Markdown documentation
  • *.spectral.yaml - Generated Spectral ruleset
  • *.rubric.json - Generated evaluation rubric
  • *.evaluation.{json,md,txt} - Sample evaluation outputs

New CLI Commands

generate mkdocs

Flag Short Default Description
--profile -p default Style profile to use
--output -o ./docs Output directory
--site-name from profile MkDocs site name
--site-url Base URL for the site
--repo-url from profile Repository URL
--theme material MkDocs theme
--split-patterns false Create separate pages per pattern
--no-split-categories false Keep all rules in one page
--no-search false Disable search plugin

generate rubric

Flag Short Default Description
--profile -p default Style profile to use
--output -o stdout Output file path

generate guide (enhanced)

New flags:

Flag Description
--no-patterns Exclude design patterns section
--no-principles Exclude design principles section
--no-glossary Exclude glossary

Documentation

New documentation added:

  • CI/CD Integration Guide - Exit codes, pipeline examples, pre-commit hooks
  • Documentation Generation Guide - Markdown vs MkDocs comparison

Updated documentation:

  • CLI Reference with new commands and flags
  • Getting Started guide with documentation generation
  • Profiles guide with extended capabilities

Dependencies

  • Added github.com/plexusone/structured-evaluation v0.8.0
  • Updated github.com/plexusone/omniskill v0.8.0 → v0.9.0
  • Updated github.com/plexusone/assistantkit v0.12.0 → v0.13.0
  • Updated github.com/daveshanley/vacuum v0.29.2 → v0.29.4