Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Default encoding behavior creates a conflict #5554

Open
witemple-msft opened this issue Jan 9, 2025 · 0 comments
Open

Default encoding behavior creates a conflict #5554

witemple-msft opened this issue Jan 9, 2025 · 0 comments

Comments

@witemple-msft
Copy link
Member

We prescribe some default encoding pairs for JSON, e.g. ["base64", string] for bytes, ["rfc3339", string] for DateTime-like scalars.

Additionally, we've said that emitters are meant to give encodings a treatment that goes something like:

When an emitter encounters an encoding pair [Encoding, Type] for a given canonical type Source, emitters should resolve this by modeling Source as if it were Type and emitting a warning advising that the emitter cannot handle the encoding and will instead require the client/server consumer/implementor to handle the wire type directly.

There are a couple of problems with this approach:

  1. The default encoding of a type depends on the MIME type of serialization. A type may be subject to multiple different serializations in the same context. Consider:

    model Data {
      created: utcDateTime;
    }
    
    op example(): {
      @header contentType: "application/json" | "application/x-protobuf";
      @body data: Data;
    }    

    In this example, the output serialization format of the body should depend on the Accept header submitted by the client and/or the type chosen by the service implementation.

    In JSON, utcDateTime has a default encoding pair ["rfc3339", string], but in Protobuf, utcDateTime has a built-in representation in Google's library. Supposing an emitter does not implement the "rfc3339" encoding for utcDateTime, how should it represent the type of Data#created in the response? The default treatment for JSON requires created: <repr string>, but the treatment for "application/x-protobuf" would require created: <repr utcDateTime>

  2. When emitters implement support for additional encodings, this will manifest as a breaking change in generated code. The type will quietly be replaced with an incompatible type when/if the emitter does eventually support the unknown encoding (e.g. created: string may eventually become created: Date or created: Temporal.Instant, and these types are nonoverlapping, leading to breaking changes in both input and output assignability of <repr Data>.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant