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

Change recommended operation IDL syntax #253

Merged
merged 1 commit into from
Jan 13, 2020
Merged

Conversation

mtdowling
Copy link
Member

@mtdowling mtdowling commented Jan 12, 2020

The old operation syntax is now deprecated in favor of a syntax that's
more consistent with the rest of the IDL.

The following operation,

operation Foo(Input) -> Output errors[X, Y, Z]

Is now defined as:

operation Foo {
    input: Input,
    output: Output,
    errors: [X, Y, Z]
}

Why?

  • This new syntax is more consistent with other shapes like resources,
    operations, structures, etc. This consistency makes it easier to
    implement parsers, formatters, etc.
  • Virtually all actual models define operations with errors. When an
    operation uses long input names, output, and defines errors, they
    either are one really long line or span multiple lines. How an
    operation definition was broken across multiple lines is something
    that has been approached with great inconsistency within AWS and
    Amazon. Using a syntax format that removes all ambiguity will help
    drive consistency in models, thereby making them easier to read.

The old syntax is still supported, but no longer documented. A
validation event is emitted when it is encountered. Support for the old
syntax will be removed in Smithy 1.0.

Issue #, if available:

Description of changes:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

The old operation syntax is now deprecated in favor of a syntax that's
more consistent with the rest of the IDL.

The following operation,

operation Foo(Input) -> Output errors[X, Y, Z]

Is now defined as:

operation Foo {
    input: Input,
    output: Output,
    errors: [X, Y, Z]
}

Why?

- This new syntax is more consistent with other shapes like resources,
  operations, structures, etc. This consistency makes it easier to
  implement parsers, formatters, etc.
- Virtually all *actual* models define operations with errors. When an
  operation uses long input names, output, *and* defines errors, they
  either are one really long line or span multiple lines. How an
  operation definition was broken across multiple lines is something
  that has been approached with great inconsistency within AWS and
  Amazon. Using a syntax format that removes all ambiguity will help
  drive consistency in models, thereby making them easier to read.

The old syntax is still supported, but no longer documented. A
validation event is emitted when it is encountered. Support for the old
syntax will be removed in Smithy 1.0.
@mtdowling mtdowling merged commit 96a684b into master Jan 13, 2020
@mtdowling mtdowling deleted the normalize-idl-shapes branch January 13, 2020 21:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants