exploring-gdla-api-contracts

GDLA Quick Reference

Available API Contracts

!bash -c 'find docs/gdl -name "*.gdla" -maxdepth 3 2>/dev/null | while read f; do echo "- $f"; done'

Format

@D service-name|description|version|base-url
@S SchemaName|description
 field|type|required|format|description
@EP METHOD /path|description|responses|auth
@P param|location|type|required|description
@AUTH scheme|description|header
@ENUM Name|value1,value2,value3
@R Source -> Target|relationship|via field
@PATH Entity -> Entity|traversal description

Endpoints and auth are single-line records. Schemas use indented field lines (like GDLS tables).

Grep Patterns

# All endpoints
grep "^@EP" contract.gdla

# Specific HTTP method
grep "^@EP GET" contract.gdla
grep "^@EP POST" contract.gdla

# GraphQL operations
grep "^@EP QUERY" contract.gdla
grep "^@EP MUTATION" contract.gdla
grep "^@EP SUBSCRIPTION" contract.gdla

# Find a schema and its fields
grep "@S Pet" -A 20 contract.gdla

# All schemas (just headers)
grep "^@S " contract.gdla

# Parameters for an endpoint
grep "^@EP GET /pets" -A 10 contract.gdla | grep "^@P"

# Authentication schemes
grep "^@AUTH" contract.gdla

# Endpoints requiring specific auth
grep "^@EP.*|bearer" contract.gdla

# Schema relationships
grep "^@R" contract.gdla

# Traversal paths
grep "^@PATH" contract.gdla

# Enums
grep "^@ENUM" contract.gdla

# Cross-file: all endpoints across all APIs
grep "^@EP" *.gdla

# Cross-file: find which APIs use bearer auth
grep "^@AUTH.*bearer" *.gdla

Combined Queries (Fewer Tool Calls)

# Full API surface (endpoints + auth)
grep -E "^@EP|^@AUTH" contract.gdla

# Schema + relationships
grep -E "^@S |^@R " contract.gdla

# All constraints (enums + required fields)
grep -E "^@ENUM|required" contract.gdla

# Endpoints that return a specific schema
grep "^@EP.*Pet" contract.gdla

# Cross-API: all endpoints and their auth across all contracts
grep -E "^@EP|^@AUTH" *.gdla

Tool Functions

Source the helpers:

source "${CLAUDE_PLUGIN_ROOT}/scripts/gdla-tools.sh"

Function	Usage	What it does
gdla_endpoints	gdla_endpoints [--method=M] [file.gdla]	List endpoints, optionally filtered by method
gdla_params	gdla_params "METHOD /path" [file.gdla]	List parameters for an endpoint
gdla_schemas	gdla_schemas [file.gdla]	List schema names
gdla_schema_fields	gdla_schema_fields SCHEMA [file.gdla]	List fields for a schema
gdla_auth	gdla_auth [file.gdla]	List authentication schemes
gdla_by_auth	gdla_by_auth SCHEME [file.gdla]	Find endpoints requiring a specific auth scheme
gdla_relationships	gdla_relationships [file.gdla]	List @R relationship records
gdla_paths	gdla_paths [file.gdla]	List @PATH traversal records

Cross-Layer Search

Function	Usage	What it does
gdl_about	gdl_about TOPIC [dir] [--layer=gdla]	Search across all GDL layers for TOPIC

Flags:

• --layer=gdla — restrict to API contract layer
• --exclude-layer=gdla — skip API contracts
• --summary — show match counts only, no record content

Key Rules

• @EP lines are complete — one grep returns the full endpoint with responses and auth
• @S blocks need -A context (like @T in GDLS) to see fields below the header
• @P lines follow their parent @EP — grep with context to see both
• @AUTH, @R, @PATH, @ENUM are single-line self-contained records
• Pipe within values is escaped as \| — use the tool functions for safe field extraction

Bridge Tools

Source	Bridge	Output
OpenAPI JSON/YAML	openapi2gdla.sh	.gdla contract
GraphQL SDL	graphql2gdla.sh	.gdla contract
GDLA contract	gdla2gdld.sh	.gdld diagram

Visualization Pipeline

# OpenAPI → GDLA → GDLD → Mermaid
bash "${CLAUDE_PLUGIN_ROOT}/scripts/openapi2gdla.sh" spec.json --output=api/
bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdla2gdld.sh" api/petstore.openapi.gdla > /tmp/api.gdld
bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdld2mermaid.sh" /tmp/api.gdld