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 (new jq-style)
openapi spec query 'schemas.components | sort_by(depth; desc) | first(10) | pick name, depth' petstore.yaml

# Dead components (unreferenced)
openapi spec query 'schemas.components | select(in_degree == 0) | pick 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

Analysis Stages

Filter & Transform Stages

Legacy syntax (where, sort, take, head, select fields, group-by, count) is still supported.

Meta Stages

Function Definitions & Modules

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

# Inline definitions
def hot: select(in_degree > 10);
def impact($name): select(name == $name) | blast-radius;
schemas.components | hot | pick name, in_degree

# Load from file
include "stdlib.oq";
schemas.components | hot | pick name, in_degree

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 1-hop traversal stages (refs-out, refs-in, properties, union-members, items):

Expressions

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

depth > 5
type == "object"
name matches "Error.*"
property_count > 3 and not is_component
has(oneOf) and not has(discriminator)
(depth > 10 or union_width > 5) and is_component
name // "unnamed"                              # alternative: fallback if null/falsy
if is_component then depth > 3 else true end   # conditional
"prefix_\(name)"                               # string interpolation

Operators

Variables

Use let to bind values for use in later stages:

schemas | select(name == "Pet") | let $pet = name | reachable | select(name != $pet)

Output Formats

Use --format flag or inline format stage:

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

Examples

# Wide union trees
schemas | select(union_width > 0) | sort_by(union_width; desc) | first(10)

# Central schemas (most referenced)
schemas.components | sort_by(in_degree; desc) | first(10) | pick name, in_degree

# Operation sprawl
operations | sort_by(schema_count; desc) | first(10) | pick name, schema_count

# Circular references
schemas | select(is_circular) | pick name, path

# Shortest path between schemas
schemas | path(Pet; Address) | pick name

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

# Explain query plan
schemas.components | select(depth > 5) | sort_by(depth; desc) | explain

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

# Group by type
schemas | group_by(type)

# Edge annotations — how does Pet reference other schemas?
schemas.components | select(name == "Pet") | refs-out | pick name, edge_kind, edge_label, edge_from

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

# 2-hop neighborhood
schemas.components | select(name == "Pet") | neighbors(2) | pick name

# Orphaned schemas
schemas.components | orphans | pick name

# Leaf nodes
schemas.components | leaves | pick name, in_degree

# Detect cycles
schemas | cycles

# Discover clusters
schemas.components | clusters

# Cross-tag schemas
schemas | tag-boundary | pick name, tag_count

# Schemas shared across all operations
operations | shared-refs | pick name, op_count

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

# User-defined functions
def hot: select(in_degree > 10);
def impact($name): select(name == $name) | blast-radius;
schemas.components | hot | pick name, in_degree

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

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>'