API Proposal: Add `IBinaryContent` marker interface for binary content in OpenAPI descriptions
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 281
Description
## Background and Motivation
Today there is no "right" way to indicate that a request or response body is binary content (i.e., should be described with `type: string, format: binary` in OpenAPI). The existing approaches all have flaws:
- `byte[]` produces a schema of `type: string, format: byte` (base64-encoded), not `type: string, format: binary`.
- Types like `FileContentResult` are special-cased to produce `type: string, format: binary`, but they are "result" types that describe how the response is sent, not the type of the body content itself. Using them in `ProducesResponseType` is semantically incorrect.
We need a dedicated marker interface that can be used as the type parameter in `ProducesAttribute`, `ProducesResponseTypeAttribute`, or the `Produces` extension method to clearly express that the body content is binary.
## Proposed API
```diff
namespace Microsoft.AspNetCore.Http;
+ ///
+ /// A marker interface that indicates binary content. When used as the type in a
+ /// or Produces extension method,
+ /// the content is described with a schema of type: string, format: binary.
+ ///
+ public interface IBinaryContent
+ {
+ }
```
## Usage Examples
```csharp
// In a Minimal API endpoint
app.MapGet("/files/{id}", async (string id) =>
{
var bytes = await GetFileBytes(id);
return Results.File(bytes, "application/octet-stream");
})
.Produces(StatusCodes.Status200OK, "application/octet-stream");
// With ProducesResponseTypeAttribute on a controller action
[ProducesResponseType(StatusCodes.Status200OK, "application/octet-stream")]
public IActionResult DownloadFile(string id) { ... }
// For request body description
app.MapPost("/upload", async (HttpRequest request) =>
{
using var stream = request.Body;
// process binary upload
})
.Accepts("application/octet-stream");
```
## Alternative Designs
- Use `byte[]` — produces `format: byte` (base64), not `format: binary`.
- Use `Stream` or `FileContentResult` as the type — these are result/transport types, not content schema types. Using them in metadata attributes is semantically misleading.
- Use schema transformers to manually patch the OpenAPI output — works but is non-discoverable and error-prone.
## Risks
No known risks. This is a purely additive API with no breaking changes.
Contributor guide
Assessment
This issue has not been assessed yet.