From b1d04750da7271612e331856fe123928f84c886a Mon Sep 17 00:00:00 2001 From: Michael Dowling Date: Wed, 14 Oct 2020 16:33:18 -0700 Subject: [PATCH] Clarify enum names and their usage --- .../1.0/spec/core/constraint-traits.rst | 52 +++++++++++-------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/docs/source/1.0/spec/core/constraint-traits.rst b/docs/source/1.0/spec/core/constraint-traits.rst index dadce62c2f4..d6c850bcb04 100644 --- a/docs/source/1.0/spec/core/constraint-traits.rst +++ b/docs/source/1.0/spec/core/constraint-traits.rst @@ -22,12 +22,12 @@ Summary Trait selector ``string`` Value type - ``list`` of enum definition structures. + ``list`` of *enum definition* structures. Smithy models SHOULD apply the enum trait when string shapes have a fixed set of allowable values. -An enum definition is a structure that supports the following members: +An *enum definition* is a structure that supports the following members: .. list-table:: :header-rows: 1 @@ -42,22 +42,28 @@ An enum definition is a structure that supports the following members: Values MUST be unique across all enum definitions in an ``enum`` trait. * - name - string - - Defines a constant name to use when referencing an enum value. - - Enum constant names MUST start with an upper or lower case ASCII Latin - letter (``A-Z`` or ``a-z``), or the ASCII underscore (``_``) and be - followed by zero or more upper or lower case ASCII Latin letters - (``A-Z`` or ``a-z``), ASCII underscores (``_``), or ASCII digits - (``0-9``). That is, enum constant names MUST match the following - regular expression: ``^[a-zA-Z_]+[a-zA-Z_0-9]*$``. - - The following stricter rules are recommended for consistency: Enum - constant names SHOULD NOT contain any lowercase ASCII Latin letters - (``a-z``) and SHOULD NOT start with an ASCII underscore (``_``). That - is, enum names SHOULD match the following regular expression: - ``^[A-Z]+[A-Z_0-9]*$``. - - Names MUST be unique across all enum definitions in an ``enum`` trait. + - Defines a constant name that can be used in programming languages to + reference an enum ``value``. A ``name`` is not required, though + their use is strongly encouraged to help tools like code generators + safely and reliably create symbols that represent specific values. + + Validation constraints: + + * Names MUST start with an upper or lower case ASCII Latin letter + (``A-Z`` or ``a-z``), or the ASCII underscore (``_``) and be + followed by zero or more upper or lower case ASCII Latin letters + (``A-Z`` or ``a-z``), ASCII underscores (``_``), or ASCII digits + (``0-9``). That is, names MUST match the following regular + expression: ``^[a-zA-Z_]+[a-zA-Z_0-9]*$``. + * The following stricter rules are recommended for consistency: Enum + constant names SHOULD NOT contain any lowercase ASCII Latin letters + (``a-z``) and SHOULD NOT start with an ASCII underscore (``_``). + That is, enum names SHOULD match the following regular expression: + ``^[A-Z]+[A-Z_0-9]*$``. + * Names MUST be unique across all enum definitions of an ``enum`` + trait. + * If any enum definition has a ``name``, then all entries in the + ``enum`` trait MUST have a ``name``. * - documentation - string - Defines documentation about the enum value in the CommonMark_ format. @@ -72,11 +78,11 @@ An enum definition is a structure that supports the following members: .. note:: - Consumers of a Smithy model MAY choose to represent enum values as - constants. Those that do SHOULD use the enum definition's ``name`` - property, if specified. Consumers that choose to represent enums as - constants SHOULD ensure that unknown enum names returned from a service - do not cause runtime failures. + Code generators MAY choose to represent enums as programming language + constants. Those that do SHOULD use the enum definition's ``name`` property, + if specified. Consumers that choose to represent enums as constants SHOULD + ensure that unknown enum names returned from a service do not cause runtime + failures. The following example defines an enum of valid string values for ``MyString``.