smithy-lang / smithy

Smithy is a protocol-agnostic interface definition language and set of tools for generating clients, servers, and documentation for any programming language.
https://smithy.io
Apache License 2.0
1.79k stars 213 forks source link

Allow for deciding trait location in `SmithyIdlSerializer` #2120

Open Baccata opened 9 months ago

Baccata commented 9 months ago

When writing smithy specifications by hand, traits can be written by :

  1. directly annotating the shape they're applied on, in an "inlined" fashion
  2. using the apply keyword, potentially in another file

When rendering a smithy model via the SmithyIdlSerializer, it'd be nice to have an option to control whether the trait should be inlined with the shape, or rendered using an apply statement, in which case it'd be nice to have control over the file in which the apply statement is rendered.

mtdowling commented 8 months ago

Can you say more about the use case?

Baccata commented 8 months ago

Sure : there is a use case in our organisation for automating the update of some smithy files depending on some information stored in a database somewhere.

The smithy files can also be manually edited to add some additional information, but also read by third parties that seek to manually implement the contracts represented by the smithy models when code-generators are unavailable.

In the particular case of structure shapes, a large amount of traits applied on the shape's members negatively impacts the readability of the smithy files, and the apply keyword can be used to regain some readability of the overall data structure whilst keeping the semantics identical. However, the automated edition of the files (which leverages the SmithyIdlSerializerconstruct) prevents the decision of which traits should be inlined with the members and which traits should be "externalised" using apply.

mtdowling commented 8 months ago

Thanks for sharing the use case. One thing to keep in mind with trying to automate updates to existing models is that the IDL serializer loses things like comments and any existing formatting. If that’s acceptable, then we can look into extending the serializer to address your use case. Otherwise, when trying to modify models in place and not lose comments or existing formatting, smithy-syntax should be used.

Baccata commented 8 months ago

Yup, we're aware of the loss of formatting and comments when using the serializer, that is absolutely acceptable.

The API of the serializer is very convenient, we like it very much. The lack of control over the placement of the traits is the only pain point we're experiencing around it.