Skip to content

Commit

Permalink
Update mixin / inline io docs
Browse files Browse the repository at this point in the history
  • Loading branch information
JordonPhillips committed Jan 18, 2022
1 parent 9da850d commit 64c2050
Show file tree
Hide file tree
Showing 5 changed files with 97 additions and 82 deletions.
68 changes: 44 additions & 24 deletions docs/source/1.0/spec/core/idl.rst
Original file line number Diff line number Diff line change
Expand Up @@ -188,17 +188,17 @@ The Smithy IDL is defined by the following ABNF:
:/ "bigDecimal" / "timestamp"
shape_members :"{" `ws` *(`shape_member_kvp` `ws`) "}"
shape_member_kvp :`trait_statements` `identifier` `ws` ":" `ws` `shape_id`
inlineable_properties :"{" *(`inlineable_property` `ws`) `ws` "}"
inlineable_property :`node_object_kvp` / `inline_structure`
inline_structure :`node_object_key` `ws` ":=" `ws` `inline_structure_value`
inline_structure_value :`trait_statements` [`mixins` ws] shape_members
list_statement :"list" `ws` `identifier` [`mixins`] `ws` `shape_members`
set_statement :"set" `ws` `identifier` [`mixins`] `ws` `shape_members`
map_statement :"map" `ws` `identifier` [`mixins`] `ws` `shape_members`
structure_statement :"structure" `ws` `identifier` [`mixins`] `ws` `shape_members`
union_statement :"union" `ws` `identifier` [`mixins`] `ws` `shape_members`
service_statement :"service" `ws` `identifier` [`mixins`] `ws` `node_object`
operation_statement :"operation" `ws` `identifier` [`mixins`] `ws` `inlineable_properties`
inlineable_properties :"{" *(`inlineable_property` `ws`) `ws` "}"
inlineable_property :`node_object_kvp` / `inline_structure`
inline_structure :`node_object_key` `ws` ":=" `ws` `inline_structure_value`
inline_structure_value :`trait_statements` [`mixins` ws] shape_members
resource_statement :"resource" `ws` `identifier` [`mixins`] `ws` `node_object`
.. rubric:: Traits
Expand Down Expand Up @@ -255,11 +255,30 @@ The :token:`control section <smithy:control_section>` of a model contains
:token:`control statements <smithy:control_statement>` that apply parser directives
to a *specific IDL file*. Because control statements influence parsing, they
MUST appear at the beginning of a file before any other statements and have
no effect on the :ref:`semantic model <semantic-model>`
no effect on the :ref:`semantic model <semantic-model>` The following control
statements are currently supported:

The :ref:`version <smithy-version>` statement is currently the only control
statement defined in the Smithy IDL. Implementations MUST ignore unknown
control statements.
.. list-table::
:header-rows: 1
:widths: 10 10 80

* - Name
- Type
- Description
* - version
- string
- Defines the :ref:`version <smithy-version>` of the Smithy IDL used in
the model file.
* - operationInputSuffix
- string
- Defines the suffix used when generating names for
:ref:`inline operation input <idl-inline-input-output>`.
* - operationOutputSuffix
- string
- Defines the suffix used when generating names for
:ref:`inline operation output <idl-inline-input-output>`.

Implementations MUST ignore unknown control statements.


.. _smithy-version:
Expand Down Expand Up @@ -1156,28 +1175,28 @@ can potentially return the ``Unavailable`` or ``BadRequest``
Inline input / output shapes
++++++++++++++++++++++++++++

In addition to targeting an existing shape id when defining an operation's
input or output property, an inline structure definition may also be used.
The input and output properties of operations can be defined using a more
succinct, inline syntax.

A structure defined this way automatically has the :ref:`input-trait` for
inputs and the :ref:`output-trait` for outputs.
A structure defined using inline syntax is automatically marked with the
:ref:`input-trait` for inputs and the :ref:`output-trait` for outputs.

A structure defined this way is given an a generated shape name. For inputs,
the generated name will be the name of the operation shape with the suffix
``Input`` added. For outputs, the generated name will be the name of the
operation shape with the ``Output`` suffix added.
A structure defined using inline syntax is given a generated shape name. For
inputs, the generated name is the name of the operation shape with the suffix
``Input`` added. For outputs, the generated name is the name of the operation
shape with the ``Output`` suffix added.

For example, the following model:

.. code-block:: smithy
operation GetUser {
// The shape name generated will be GetUserInput
// The generated shape name is GetUserInput
input := {
userId: String
}
// The shape name generated will be GetUserOutput
// The generated shape name is GetUserOutput
output := {
username: String
userId: String
Expand All @@ -1204,7 +1223,7 @@ Is equivalent to:
userId: String
}
Traits and mixins can be applied:
Traits and mixins can be applied to the inline structure:

.. code-block:: smithy
Expand Down Expand Up @@ -1241,12 +1260,12 @@ The suffixes for the generated names can be customized using the
namespace smithy.example
operation GetUser {
// The shape name generated will be GetUserRequest
// The generated shape name is GetUserRequest
input := {
userId: String
}
// The shape name generated will be GetUserResponse
// The generated shape name is GetUserResponse
output := {
username: String
userId: String
Expand Down Expand Up @@ -1305,7 +1324,8 @@ Mixins
------

:ref:`Mixins <mixins>` can be added to a shape using the optional
:token:`smithy:mixins` statement as part of the shape type's statement.
:token:`smithy:mixins` clause of a shape definition.

For example:

.. code-block:: smithy
Expand All @@ -1323,8 +1343,8 @@ For example:
@sensitive
string SensitiveString
@pattern("[a-zA-Z\.]*")
string SensitiveText with SensitiveString
@pattern("^[a-zA-Z\.]*$")
string SensitiveText with [SensitiveString]
.. _documentation-comment:
Expand Down
2 changes: 1 addition & 1 deletion docs/source/1.0/spec/core/json-ast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -647,7 +647,7 @@ Mixins
All shapes in the ``shapes`` map can contain a ``mixins`` property that
defines the :ref:`mixins` that are added to the shape. ``mixins`` is an
array of :ref:`shape references <ast-shape-reference>` that target shapes
with the :ref:`mixin trait <mixin-trait>`.
marked with the :ref:`mixin trait <mixin-trait>`.

.. code-block:: json
Expand Down
90 changes: 41 additions & 49 deletions docs/source/1.0/spec/core/model.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2705,11 +2705,11 @@ shape.
.. code-block:: smithy
@mixin
structure UserIdentifiers {
structure UserIdentifiersMixin {
id: String
}
structure UserDetails with [UserIdentifiers] {
structure UserDetails with [UserIdentifiersMixin] {
alias: String
}
Expand All @@ -2718,19 +2718,19 @@ Multiple mixins can be applied:
.. code-block:: smithy
@mixin
structure UserIdentifiers {
structure UserIdentifiersMixin {
id: String
}
@mixin
structure AccessDetails {
structure AccessDetailsMixin {
firstAccess: Timestamp
lastAccess: Timestamp
}
structure UserDetails with [
UserIdentifiers
AccessDetails
UserIdentifiersMixin
AccessDetailsMixin
] {
alias: String
}
Expand Down Expand Up @@ -2779,10 +2779,10 @@ shape, but not to a blob shape.
@mixin
@pattern("[a-zA-Z0-1]*")
string AlphaNumeric
string AlphaNumericMixin
@length(min: 8, max: 32)
string Username with [AlphaNumeric]
string Username with [AlphaNumericMixin]
Traits and mixins
Expand All @@ -2799,11 +2799,11 @@ For example, the definition of ``UserSummary`` in the following model:
/// Generic mixin documentation.
@tags(["a"])
@mixin
structure UserInfo {
structure UserInfoMixin {
userId: String
}
structure UserSummary with [UserInfo] {}
structure UserSummary with [UserInfoMixin] {}
Is equivalent to the following flattened structure because it inherits the
traits of ``UserInfo``:
Expand All @@ -2823,13 +2823,13 @@ The definition of ``UserSummary`` in the following model:
/// Generic mixin documentation.
@tags(["a"])
@mixin
structure UserInfo {
structure UserInfoMixin {
userId: String
}
/// Specific documentation
@tags(["replaced-tags"])
structure UserSummary with [UserInfo] {}
structure UserSummary with [UserInfoMixin] {}
Is equivalent to the following flattened structure because it inherits the
traits of ``UserInfo`` and traits applied to ``UserSummary`` take precedence
Expand Down Expand Up @@ -2989,15 +2989,14 @@ Alternatively, the member can be redefined if it targets the same shape:
}
Mixins are not code generated
=============================
Mixins are an implementation detail of the model
================================================

Mixins are an implementation detail of models and are only intended to reduce
duplication in Smithy shape definitions. Shapes marked with the
:ref:`mixin-trait` MUST NOT be code generated. Mixins *do not* provide any kind
of runtime polymorphism for types generated from Smithy models. Generating code
from mixins removes the ability for modelers to introduce and even remove
mixins over time as a model is refactored.
duplication in Smithy shape definitions. Mixins do not provide any kind of
runtime polymorphism for types generated from Smithy models. Smithy model
transformations like code generation or converting to other model formats
like OpenAPI SHOULD completely elide mixins by flattening the model.


Mixins cannot be referenced other than as mixins to other shapes
Expand Down Expand Up @@ -3051,9 +3050,9 @@ Mixins MUST NOT introduce circular references. The following model is invalid:
Mixin members MUST NOT conflict
===============================

The list of mixins applied to a structure or union MUST NOT attempt to define
members that use the same member name with different targets. The following
model is invalid:
The list of mixins applied to a shape MUST NOT attempt to define members that
use the same member name with different targets. The following model is
invalid:

.. code-block:: smithy
Expand Down Expand Up @@ -3129,23 +3128,22 @@ are added to the ordered list.

Given the following model:


.. code-block:: smithy
@mixin
structure FilteredByName {
structure FilteredByNameMixin {
nameFilter: String
}
@mixin
structure PaginatedInput {
structure PaginatedInputMixin {
nextToken: String
pageSize: Integer
}
structure ListSomethingInput with [
PaginatedInput
FilteredByName
PaginatedInputMixin
FilteredByNameMixin
] {
sizeFilter: Integer
}
Expand Down Expand Up @@ -3210,8 +3208,7 @@ example, in the following model:
operations: [OperationC]
}
The ``version`` property of the local shape is kept and the ``rename`` and
``operations`` properties are merged. This is equivalent to the following:
The flattened equivalent of ``C`` with no mixins is:

.. code-block:: smithy
Expand Down Expand Up @@ -3257,35 +3254,30 @@ Operation shapes with the :ref:`mixin-trait` MAY NOT define an ``input`` or
input and output shapes to be shared goes against the goal of the
:ref:`input-trait` and :ref:`output-trait`.

Operation shapes with the :ref:`mixin-trait` MAY define the errors shape.
Operation shapes with the :ref:`mixin-trait` MAY define errors.

.. code-block:: smithy
@mixin
operation MixinOperation {
errors: [MixinError]
}
operation MixedOperation with [MixinOperation] {
error: [MixedError]
operation ValidatedOperation {
errors: [ValidationError]
}
@error("client")
structure MixinError {}
@error("client")
structure MixedError {}
structure ValidationError {}
operation GetUsername with [ValidatedOperation] {
input := {
id: String
}
output := {
name: String
}
error: [NotFoundError]
}
Mixins in conversion tooling
============================

When converting Smithy models to OpenAPI, JSON Schema, and other models that
do not directly support the same mixin semantics as Smithy, tooling MUST
remove all traces of mixins by flattening mixins into their target shapes.
This removes the risk of consumers relying on mixins as normal types and still
retains the flexibility modelers need in order to refactor mixins in and out
of shapes.
@error("client")
structure NotFoundError {}
.. _metadata:
Expand Down
8 changes: 4 additions & 4 deletions docs/source/1.0/spec/core/selectors.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1237,12 +1237,12 @@ The table below lists the labeled directed relationships from each shape.
mixins. Note that these are not the shapes targeted by the member.
* - structure
- member
- Each structure member, including members from mixins. Note that these
are not the shapes targeted by the members.
- Each structure member, including members inherited from mixins. Note
that these are not the shapes targeted by the members.
* - union
- member
- Each union member, including members from mixins. Note that these are
not the shapes targeted by the members.
- Each union member, including members inherited from mixins. Note that
these are not the shapes targeted by the members.
* - member
-
- The shape targeted by the member. Note that member targets have no
Expand Down
11 changes: 7 additions & 4 deletions docs/source/1.0/spec/core/type-refinement-traits.rst
Original file line number Diff line number Diff line change
Expand Up @@ -306,13 +306,12 @@ The mixin trait is a structure that contains the following members:

.. note::

The ``mixin`` trait is considered implicitly present in the this
property and so does not need to be explicitly added.

See the :ref:`Smithy spec <mixins>` for details on how mixins work.
The ``mixin`` trait is considered implicitly present in this
property and does not need to be explicitly added.

.. code-block:: smithy
@mixin
structure BaseUser {
id: String
}
Expand All @@ -322,4 +321,8 @@ See the :ref:`Smithy spec <mixins>` for details on how mixins work.
email: String
}
.. seealso::

The :ref:`Smithy spec <mixins>` for details on how mixins work.

.. _Option type: https://doc.rust-lang.org/std/option/enum.Option.html

0 comments on commit 64c2050

Please sign in to comment.