oq

oq — OpenAPI Query Language

oq is a pipeline query language for exploring OpenAPI schema reference graphs. It lets you ask structural and semantic questions about schemas and operations at the command line.

Quick Start

# Count all schemas
openapi spec query 'schemas | count' petstore.yaml

# Top 10 deepest component schemas
openapi spec query 'schemas | where(isComponent) | sort-by(depth, desc) | take(10) | select name, depth' petstore.yaml

# Dead components (unreferenced)
openapi spec query 'schemas | where(isComponent) | where(inDegree == 0) | select name' petstore.yaml

Stdin is supported:

cat spec.yaml | openapi spec query 'schemas | count'

Pipeline Syntax

Queries are left-to-right pipelines separated by |:

source | stage | stage | ... | terminal

Sources

Traversal Stages

Navigation Stages

Navigate into the internal structure of operations. These stages produce new row types (parameters, responses, etc.) that can be filtered and inspected.

Analysis Stages

Filter & Transform Stages

Meta Stages

The to-yaml stage uses path (JSON pointer) as the wrapper key for each emitted node, giving full attribution to the source location in the spec.

Function Definitions & Modules

Define reusable functions with def and load them from .oq files with include:

# Inline definitions
def hot: where(inDegree > 10);
def impact($name): where(name == $name) | blast-radius;
schemas | where(isComponent) | hot | select name, inDegree

# Load from file
include "stdlib.oq";
schemas | where(isComponent) | hot | select name, inDegree

Def syntax: def name: body; or def name($p1, $p2): body; Module search paths: current directory, then ~/.config/oq/

Fields

Schema Fields

Operation Fields

Edge Annotation Fields

Available on rows produced by traversal stages (refs, properties, members, items, path).

Parameter Fields

Produced by the parameters navigation stage.

Response Fields

Produced by the responses navigation stage.

Request Body Fields

Produced by the request-body navigation stage.

Content Type Fields

Produced by the content-types navigation stage.

Header Fields

Produced by the headers navigation stage.

Server Fields

Tag Fields

Link Fields

Expressions

oq supports a rich expression language used in where(), let, and if-then-else:

depth > 5
type == "object"
name matches "Error.*"
propertyCount > 3 and not isComponent
has(oneOf) and not has(discriminator)
(depth > 10 or unionWidth > 5) and isComponent
name // "unnamed"                              # alternative: fallback if null/falsy
name default "unnamed"                         # same as above (alias)
if isComponent then depth > 3 else true end   # conditional
"prefix_\(name)"                               # string interpolation

Operators

Variables

Use let to bind values for use in later stages:

schemas | where(name == "Pet") | let $pet = name | refs(out) | where(name != $pet)

Output Formats

Use --format flag or inline format stage:

openapi spec query 'schemas | count' spec.yaml --format json
openapi spec query 'schemas | take(5) | format(markdown)' spec.yaml

Examples

# Wide union trees
schemas | where(unionWidth > 0) | sort-by(unionWidth, desc) | take(10)

# Central schemas (most referenced)
schemas | where(isComponent) | sort-by(inDegree, desc) | take(10) | select name, inDegree

# Operation sprawl
operations | sort-by(schemaCount, desc) | take(10) | select name, schemaCount

# Circular references
schemas | where(isCircular) | select name, path

# Shortest path between schemas
schemas | path(Pet, Address) | select name

# Walk an operation to connected schemas and back to operations
operations | where(name == "GET /users") | to-schemas | to-operations | select name, method, path

# Explain query plan
schemas | where(isComponent) | where(depth > 5) | sort-by(depth, desc) | explain

# Regex filter
schemas | where(name matches "Error.*") | select name, path

# Group by type
schemas | group-by(type)

# Edge annotations — how does Pet reference other schemas?
schemas | where(isComponent) | where(name == "Pet") | refs(out) | select name, via, key, from

# Blast radius — what breaks if Error changes?
schemas | where(isComponent) | where(name == "Error") | blast-radius | length

# 1-hop bidirectional refs (with direction arrows)
schemas | where(isComponent) | where(name == "Pet") | refs | select name, direction, via, key

# Orphaned schemas
schemas | where(isComponent) | orphans | select name

# Leaf nodes
schemas | where(isComponent) | leaves | select name, inDegree

# Detect cycles
schemas | cycles

# Discover clusters
schemas | where(isComponent) | clusters

# Cross-tag schemas
schemas | cross-tag | select name, tagCount

# Schemas shared across all operations
operations | shared-refs | select name, opCount

# Variable binding — find Pet's refs(out) schemas (excluding Pet itself)
schemas | where(name == "Pet") | let $pet = name | refs(out) | where(name != $pet) | select name

# User-defined functions
def hot: where(inDegree > 10);
def impact($name): where(name == $name) | blast-radius;
schemas | where(isComponent) | hot | select name, inDegree

# Alternative operator — fallback for missing values
schemas | where(name // "unnamed" != "unnamed") | select name

# --- Navigation examples ---

# List all parameters for a specific operation
operations | where(name == "GET /pets") | parameters | select name, in, required

# Find operations with required query parameters
operations | parameters | where(in == "query" and required) | select name, operation

# Inspect responses for an operation
operations | where(name == "GET /pets") | responses | select statusCode, description

# Drill into content types of a response
operations | where(name == "GET /pets") | responses | where(statusCode == "200") | content-types | select mediaType, hasSchema

# Extract schemas from content types
operations | where(name == "GET /pets") | responses | content-types | to-schema | select name, type

# List response headers
operations | responses | where(statusCode == "200") | headers | select name, required, operation

# Navigate from parameter back to its operation
operations | parameters | where(name == "limit") | operation | select name, method, path

# Request body content types
operations | where(method == "post") | request-body | content-types | select mediaType, hasSchema, operation

# Extract raw YAML for a schema
schemas | where(name == "Pet") | to-yaml

# --- New capabilities ---

# Webhook operations
webhooks | select name, method, path

# Document servers
servers | select url, description, variableCount

# Tags with operation counts
tags | select name, operationCount | sort-by(operationCount, desc)

# Callback operations
operations | where(callbackCount > 0) | callbacks | select name, callbackName

# Response links
operations | responses | links | select name, operationId

# Additional/pattern properties
schemas | where(has(additionalProperties)) | additional-properties
schemas | where(has(patternProperties)) | pattern-properties

# Schemas with default values
schemas | properties | where(has(default)) | select from, key, default

# Extension fields (use underscores for dashes in expressions)
operations | where(has(x_speakeasy_name_override)) | select name, x_speakeasy_name_override

CLI Reference

# Run query-reference for the full language reference
openapi spec query-reference

# Inline query
openapi spec query '<query>' <spec-file>

# Query from file
openapi spec query -f query.oq <spec-file>

# With output format
openapi spec query '<query>' <spec-file> --format json

# From stdin
cat spec.yaml | openapi spec query '<query>'