dotnet / dotnet/aspnetcore

API Proposal: Add `IBinaryContent` marker interface for binary content in OpenAPI descriptions

Open
#67,145 10 comments 3 reactions 1 assignee Claimed by @Youssef1313 View on GitHub
api-proposal api-suggestion area-minimal
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.