experiment: google.api.http annotations on CommandService (Peaceful Studio internal)

[monsieurleberre]

Side-by-side rendered comparison (SwaggerHub)

• After (annotated proto → grpc-gateway openapiv2): CommandService.SubmitAndWait
• Before (current tapir-emitted spec from Canton 3.5.1-SNAPSHOT): postV2CommandsSubmit-and-wait

Open both, compare the request/response schemas at the bottom of each operation. The "before" spec references JsCommands (which transitively pulls in numbered duplicates, single-key oneOf envelopes, and inline-duplicated enums); the "after" spec references com.daml.ledger.api.v2.Commands directly with proper proto-qualified types throughout.

---

Summary

Proof-of-concept for the upstream fix outlined as Option 4 of the C# SDK funding proposal: annotate Canton's .proto files with google.api.http so the JSON HTTP surface can be regenerated cleanly from the protos, bypassing the tapir translation layer that introduces the structural defects catalogued in documentation/dev-funding/openApi/why-openapi-is-not-enough.md.

Scope: one service end-to-end (CommandService, 3 RPCs) + go_package options on the 22 v2 protos + value.proto.

Not for upstream submission yet — internal Peaceful Studio review only. See documentation/dev-funding/openApi/upstream-fork-experiment.md for the full write-up, proposed upstream-PR split, CLA notes, and verification details.

What's in this PR

Change	Why
command_service.proto: import "google/api/annotations.proto"; + option (google.api.http) = {...} on each of the 3 RPCs	The annotation experiment. Matches the existing tapir routes (/v2/commands/submit-and-wait, submit-and-wait-for-transaction, submit-and-wait-for-reassignment).
22 v2 protos + value.proto: option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2";	Precondition for every off-the-shelf OpenAPI tool. Canton has no Go target today, so this option was missing. Harmless to existing C#/Java/Scala codegen.

Built and verified with the canton dependency stack as-is. No build-system changes required for the annotation parsing step.

Verification (reproducible end-to-end)

# 1. Fetch a buf binary
brew install bufbuild/buf/buf

# 2. Make the google.api / google.rpc protos available where buf.work.yaml expects them
#    (sbt's PB.unpackDependencies would normally put them here)
cd canton/community/lib/google-common-protos-scala
mkdir -p target/protobuf_external/google/api target/protobuf_external/google/rpc
curl -sS -o target/protobuf_external/google/api/annotations.proto \
  https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto
curl -sS -o target/protobuf_external/google/api/http.proto \
  https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto
curl -sS -o target/protobuf_external/google/rpc/status.proto \
  https://raw.githubusercontent.com/googleapis/googleapis/master/google/rpc/status.proto

# 3. Verify the annotated proto compiles
cd ../../../community/ledger-api-proto/src/main/protobuf
buf build      # exits 0, no output

# 4. Generate a clean OpenAPI from the annotated proto
mkdir -p /tmp/canton-openapi-gen
cat > /tmp/canton-openapi-gen/buf.gen.yaml <<'YAML'
version: v2
plugins:
  - remote: buf.build/grpc-ecosystem/openapiv2:v2.28.0
    out: gen/openapi
    opt:
      - allow_delete_body=true
      - json_names_for_fields=true
      - openapi_naming_strategy=fqn
YAML

cd /tmp/canton-openapi-gen
buf generate \
  --path "<path-to-fork>/community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto" \
  "<path-to-fork>/community/ledger-api-proto/src/main/protobuf"

# 5. Inspect
less gen/openapi/com/daml/ledger/api/v2/command_service.swagger.json

The generated OpenAPI (1,372 lines) demonstrably fixes all four type-system defects from why-openapi-is-not-enough.md:

• ✅ No numbered duplicates (Empty1–Empty10): types are qualified by proto package (com.daml.ledger.api.v2.Commands, com.daml.ledger.api.v2.Record).
• ✅ No single-key oneOf envelopes: oneof branches emit as sibling optional properties.
• ✅ No inline duplicated enums: each enum extracted once (e.g. com.daml.ledger.api.v2.TransactionShape) and referenced everywhere.
• ✅ DAML payloads are typed: createArguments → $ref: com.daml.ledger.api.v2.Record, choiceArgument → $ref: com.daml.ledger.api.v2.Value.

Out of scope for this PR (next steps)

• Annotating the remaining 21–25 RPCs across command_submission_service.proto, command_completion_service.proto, state_service.proto, update_service.proto, package_service.proto, etc.
• Wiring the google-common-protos-scala includeFilter to also generate Scala bindings for annotations.proto / http.proto, then writing a MethodDescriptor → tapir.Endpoint helper so tapir routes are derived from the annotation instead of hand-written. Feasibility analysis in the companion write-up.
• Splitting into two upstream PRs to digital-asset/canton (PR-1 = go_package cross-language enablement, PR-2 = annotations + tapir derivation). Not now — internal review first.

[monsieurleberre]

Superseded by #2, which now carries the experiment-evidence/ bundle from this branch (fold commit aa5ec09) and extends the annotation coverage to every HTTP-exposed RPC. Closing per SDK ADR 0012 fork-hygiene decision: fold, close, merge into fork main only.