[Bug]: FilePart structure is incompatible between JSON and gRPC specs

[adarshnarayanhegde]

What happened?

File attachments don't work when converting between JSON-RPC and gRPC because the structures are completely different.

Proto structure:

message FilePart {
  oneof file {
    string file_with_uri = 1;      // Just the URI string
    bytes file_with_bytes = 2;
  }
  string mime_type = 3;            // Separate field
  string name = 4;
}

Proto outputs:

{
  "fileWithUri": "https://example.com/doc.pdf",
  "mimeType": "application/pdf",
  "name": "document.pdf"
}

JSON schema expects:

{
  "kind": "file",
  "file": {
    "uri": "https://example.com/doc.pdf",
    "mimeType": "application/pdf",
    "name": "document.pdf"
  }
}

The proto treats file_with_uri as a string with separate metadata fields, while JSON groups everything into a file object. They can't be converted without custom code.

Impact

All file attachments break when switching between transports. This affects messages with images, documents, or any file content.

Proposed Solutions

Option 1: Update proto to match JSON (recommended)

Change proto to group file properties together:

message FilePart {
  oneof file {
    FileWithUri file_with_uri = 1;
    FileWithBytes file_with_bytes = 2;
  }
}

message FileWithUri {
  string uri = 1;
  string mime_type = 2;
  string name = 3;
}

This matches the JSON structure and is more idiomatic for REST APIs. Braking change.

Option 2: Update JSON schema to match proto

Flatten the JSON structure to have all fields at the top level. Simpler but less common in REST APIs and still a breaking change.

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[adarshnarayanhegde]

I’d be happy to contribute a PR implementing Option 1 if the maintainers agree that’s the preferred direction.

[darrelmiller]

We are working on a significant refactoring that consolidates all the models around a single definition. At the moment that is the proto definition. We need to make a decision on all the discriminated union types.

This matches the JSON structure and is more idiomatic for REST APIs

Using discriminators is common, but it can be a real pain for deserialization and JSON Schema doesn't have a great way of representing them.