protobuf emitter maps unknown to Any (should have an option for Struct)

[DaveB93]

Our TypeSpec has several free form "arbitrary JSON object" fields authored as plain YAML maps. they're typed unknown in TypeSpec, but the emitter renders them as google.protobuf.Any. Any requires a @type URL to be set in the JSON representation so a plain YAML object like {foo: 1} cannot be parsed into the field. Arbitrary JSON should map to google.protobuf.Struct or google.protobuf.Value.

it would be nice if there were decorators to determine what protobuf type is generated here.

Playground Link

Minimal playground spec

import "@typespec/protobuf";

using TypeSpec.Protobuf;

@package({
  name: "repro",
})
namespace Repro;

model Thing {
  @field(1)
  name: string;

  // Free-form, arbitrary JSON object authored as a plain YAML/JSON map, e.g. { foo: 1 }.
  // We want this to be google.protobuf.Struct in the emitted proto.
  @field(2)
  arguments?: unknown;
}

Actual emitter output

syntax = "proto3";

package repro;

import "google/protobuf/any.proto";

message Thing {
  string name = 1;
  google.protobuf.Any arguments = 2;
}

Expected / desired output

syntax = "proto3";

package repro;

import "google/protobuf/struct.proto";

message Thing {
  string name = 1;
  google.protobuf.Struct arguments = 2;
}

Ask

unknown represents "any JSON value", which round-trips through google.protobuf.Struct
(object) / google.protobuf.Value (any value) - not google.protobuf.Any, whose JSON form
requires a @type URL. Options for the emitter:

1. Map unknown to google.protobuf.Value (or Struct for object-shaped data) by default; or
2. Provide an opt-in decorator / config to choose the well-known mapping (e.g.
   @TypeSpec.Protobuf.wellKnownType(Struct)).

Either removes the need for downstream post-processing of the generated .proto.

[github-actions]

🎯 Issue Triage

The protobuf emitter currently maps TypeSpec's unknown type to google.protobuf.Any, but users need it to map to google.protobuf.Struct (or google.protobuf.Value) for plain JSON object fields, since Any requires a @type URL that makes it incompatible with arbitrary JSON maps.

Category: Feature Request
Area: emitter:protobuf

🔗 [Playground Reproduction]((typespec.io/redacted)

📋 Reproduction code

import "`@typespec/protobuf`";

using TypeSpec.Protobuf;

`@package`({
  name: "repro",
})
namespace Repro;

model Thing {
  `@field`(1)
  name: string;

  `@field`(2)
  arguments?: unknown;
}

🔍 Analysis

• Affected component: @typespec/protobuf emitter
• Current behavior: unknown maps to google.protobuf.Any (requires a @type URL in JSON, incompatible with plain JSON objects)
• Desired behavior: unknown maps to google.protobuf.Struct or google.protobuf.Value (natively round-trips arbitrary JSON)
• Proposed solutions (from author):
  1. Change default mapping of unknown to google.protobuf.Value (any JSON value) or google.protobuf.Struct (object-shaped) — potentially breaking
  2. Add an opt-in decorator (e.g. @wellKnownType(Struct)) — non-breaking but requires new API surface

📝 Suggested next steps

• Decide whether to change the default mapping of unknown (breaking) or add an opt-in decorator (non-breaking)
• If adding a decorator, design its API
• Update protobuf emitter to handle google.protobuf.Struct / google.protobuf.Value mappings
• Add tests covering unknown to Struct/Value mapping

Generated by Agentic Triage