feat(oq): add GCF as --format gcf output option

Author: blackwell-systems

cmd/openapi/commands/openapi/query.go

@@ -60,7 +60,7 @@ var queryOutputFormat string
 var queryFromFile string
 
 func init() {
-	queryCmd.Flags().StringVar(&queryOutputFormat, "format", "table", "output format: table, json, markdown, or toon")
+	queryCmd.Flags().StringVar(&queryOutputFormat, "format", "table", "output format: table, json, markdown, toon, or gcf")
 	queryCmd.Flags().StringVarP(&queryFromFile, "file", "f", "", "read query from file instead of argument")
 
 	// Custom help template: Usage + Flags together, then Examples last
@@ -167,6 +167,8 @@ func queryOpenAPI(ctx context.Context, processor *OpenAPIProcessor, queryStr str
 		output = oq.FormatMarkdown(result, g)
 	case "toon":
 		output = oq.FormatToon(result, g)
+	case "gcf":
+		output = oq.FormatGCF(result, g)
 	default:
 		output = oq.FormatTable(result, g)
 	}

go.mod

@@ -1,6 +1,6 @@
 module github.com/speakeasy-api/openapi
 
-go 1.25.0
+go 1.26.1
 
 require (
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
@@ -13,6 +13,7 @@ require (
 )
 
 require (
+	github.com/blackwell-systems/gcf-go v1.2.1 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dlclark/regexp2 v1.11.4 // indirect
 	github.com/dprotaso/go-yit v0.0.0-20191028211022-135eb7262960 // indirect

go.sum

@@ -1,3 +1,5 @@
+github.com/blackwell-systems/gcf-go v1.2.1 h1:NsoGZKQxT8O3WKl+QssiFdvhPM0cCCyJ3a3x1H5fGDI=
+github.com/blackwell-systems/gcf-go v1.2.1/go.mod h1:sROSBELq+iEDf3pD1x4AcY2QccFd1KHsGajFzjVlCNc=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

oq/format.go

@@ -5,6 +5,7 @@ import (
 	"strconv"
 	"strings"
 
+	gcf "github.com/blackwell-systems/gcf-go"
 	"github.com/speakeasy-api/openapi/graph"
 	"github.com/speakeasy-api/openapi/oq/expr"
 	"gopkg.in/yaml.v3"
@@ -221,6 +222,54 @@ func FormatToon(result *Result, g *graph.SchemaGraph) string {
 	return sb.String()
 }
 
+// FormatGCF formats a result using GCF (Graph Compact Format).
+// GCF uses positional pipe-delimited rows with inline schemas, achieving
+// higher LLM comprehension accuracy than TOON or JSON (90.7% vs 68.5% vs 53.6%).
+// See https://gcformat.com
+func FormatGCF(result *Result, g *graph.SchemaGraph) string {
+	if result.Explain != "" {
+		return result.Explain
+	}
+
+	if result.IsCount {
+		return gcf.EncodeGeneric(map[string]interface{}{"count": result.Count})
+	}
+
+	syncGroupsFromRows(result)
+
+	if len(result.Rows) == 0 {
+		return gcf.EncodeGeneric([]interface{}{})
+	}
+
+	fields := result.Fields
+	if len(fields) == 0 {
+		fields = resolveDefaultFields(result.Rows)
+	}
+
+	rows := make([]interface{}, 0, len(result.Rows))
+	for _, row := range result.Rows {
+		m := make(map[string]interface{}, len(fields))
+		for _, f := range fields {
+			v := fieldValue(row, f, g)
+			switch v.Kind {
+			case expr.KindString:
+				m[f] = v.Str
+			case expr.KindInt:
+				m[f] = v.Int
+			case expr.KindBool:
+				m[f] = v.Bool
+			case expr.KindArray:
+				m[f] = v.Arr
+			default:
+				m[f] = nil
+			}
+		}
+		rows = append(rows, m)
+	}
+
+	return gcf.EncodeGeneric(rows)
+}
+
 // FormatYAML formats results as raw YAML from the underlying schema/operation objects.
 // For multiple results, outputs a YAML stream with --- separators.
 // This enables piping into yq for content-level queries.

oq/oq.go

@@ -85,7 +85,7 @@ type Result struct {
 	Count      int
 	Groups     []GroupResult
 	Explain    string // human-readable pipeline explanation
-	FormatHint string // format preference from format stage (table, json, markdown, toon)
+	FormatHint string // format preference from format stage (table, json, markdown, toon, gcf)
 	EmitYAML   bool   // emit raw YAML nodes instead of formatted output
 }
 

oq/parse.go

@@ -322,8 +322,8 @@ func parseStage(s string) (Stage, error) {
 
 	case "format":
 		f := strings.TrimSpace(args)
-		if f != "table" && f != "json" && f != "markdown" && f != "toon" {
-			return Stage{}, fmt.Errorf("format must be table, json, markdown, or toon, got %q", f)
+		if f != "table" && f != "json" && f != "markdown" && f != "toon" && f != "gcf" {
+			return Stage{}, fmt.Errorf("format must be table, json, markdown, toon, or gcf, got %q", f)
 		}
 		return Stage{Kind: StageFormat, Format: f}, nil