From b13fc762b31156515a3569cb633c94767c66a129 Mon Sep 17 00:00:00 2001 From: tkrop Date: Thu, 27 Jun 2024 17:52:35 +0000 Subject: [PATCH] deploy: 815821712a263a1afa0bd8c1e7785a4222b5efbe --- index.html | 49 +++++++++++++++++++++++++++++-------------------- rules | 2 +- rules.json | 2 +- 3 files changed, 31 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index bca7c7a7..7613e10e 100644 --- a/index.html +++ b/index.html @@ -1595,7 +1595,7 @@

MUST use media type versioning
  • MUST not use URL versioning
  • MUST always return JSON objects as top-level data structures
    • -
  • SHOULD used open-ended list of values (x-extensible-enum) for enumerations
    • +
  • SHOULD use open-ended list of values (x-extensible-enum) for enumeration types
  • 16. REST Design - Deprecation @@ -8057,19 +8057,19 @@

    SH make sure that all constraints are clearly defined in description.

  • -

    Enum ranges can be reduced when used as input parameters, only if the server -is ready to accept and handle old range values too. Enum range can be reduced +

    enum ranges can be reduced when used as input parameters, only if the server +is ready to accept and handle old range values too. The range can be reduced when used as output parameters.

  • -

    Enum ranges cannot be extended when used for output parameters — clients may +

    enum ranges cannot be extended when used for output parameters — clients may not be prepared to handle it. However, enum ranges can be extended when used for input parameters.

  • -

    Use x-extensible-enum, if range is used for output parameters and likely to -be extended with growing functionality. It defines an open list of explicit -values and clients must be agnostic to new values.

    +

    You SHOULD use open-ended list of values (x-extensible-enum) for enumeration types that are used for output parameters and likely to +be extended with growing functionality. The API definition should be updated +first before returning new values.

  • Consider SHOULD be aware of services not fully supporting JSON/unicode in case a URL has to change.

    @@ -8169,8 +8169,8 @@

    MUST subsequent PUT requests.

  • -

    Be prepared that x-extensible-enum return parameter may deliver new values; -either be agnostic or provide default behavior for unknown values.

    +

    Be prepared that x-extensible-enum return parameters (see rule 112) may deliver new values; +either be agnostic or provide default behavior for unknown values, and do not eliminate them.

  • Be prepared to handle HTTP status codes not explicitly specified in endpoint @@ -8411,12 +8411,12 @@

    MUST
    -

    SHOULD used open-ended list of values (x-extensible-enum) for enumerations

    +

    SHOULD use open-ended list of values (x-extensible-enum) for enumeration types

    -

    Enumerations are per definition closed sets of values that are assumed to be +

    JSON schema enum is per definition a closed set of values that is assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid -these issues, we strongly recommend to use an open-ended list of values instead +these issues, we recommend to use an open-ended list of values instead of an enumeration unless:

    @@ -8432,8 +8432,7 @@

    SH

    -

    To specify an open-ended list of values use the marker x-extensible-enum as -follows:

    +

    To specify an open-ended list of values via the x-extensible-enum property as follows:

    @@ -8446,18 +8445,26 @@

    SH

    -

    Note: x-extensible-enum is not JSON Schema conform but will be ignored by -most tools.

    +

    Note: x-extensible-enum is a proprietary extension of the JSON Schema standard that +is e.g. visible via Swagger UI, but ignored by most other tools.

    See SHOULD declare enum values using UPPER_SNAKE_CASE string about enum value naming conventions.

    +

    Note, x-extensible-enum is a different concept than JSON schema examples which is +just a list of a few example values, whereas x-extensible-enum defines all valid +values (for a specific API and service version) and has the advantage of an extensible +full type-range specification that is validated by the service.

    +
    +

    Important: Clients must be prepared for extensions of enums returned with server responses, i.e. must implement a fallback / default behavior to handle unknown new enum values — see MUST prepare clients to accept compatible API extensions. API owners must take care to extend enums in a compatible way that does not change the semantics of already existing enum values, for instance, do not split an old enum value -into two new enum values.

    +into two new enum values. Services should only extend x-extensible-enum ranges, and only accept +and return values listed in the API definition, i.e. the API definition needs to be updated first +before the service accepts/returns new values — see also SHOULD prefer compatible extensions.

    @@ -9907,6 +9914,9 @@

    MUST

  • Removing an individual value from an enumeration.

    • +
  • +

    Adding new value to a x-extensible-enum field (see rule 112 and rule 108).

    +
    • @@ -9933,8 +9943,7 @@

    MUST field (also known as a co-occurrence constraint).

  • -

    Adding a value to an enumeration (note that x-extensible-enum -is not available in JSON Schema)

    +

    Adding a value to an enumeration. Instead, you SHOULD use open-ended list of values (x-extensible-enum) for enumeration types.

    • @@ -10987,7 +10996,7 @@

    Rule Changes

    diff --git a/rules b/rules index 8c41f632..e0ce6abe 100644 --- a/rules +++ b/rules @@ -50,7 +50,7 @@ }, { "id": "#112", - "title": "SHOULD used open-ended list of values (`x-extensible-enum`) for enumerations" + "title": "SHOULD use open-ended list of values (`x-extensible-enum`) for enumeration types" }, { "id": "#113", diff --git a/rules.json b/rules.json index 8c41f632..e0ce6abe 100644 --- a/rules.json +++ b/rules.json @@ -50,7 +50,7 @@ }, { "id": "#112", - "title": "SHOULD used open-ended list of values (`x-extensible-enum`) for enumerations" + "title": "SHOULD use open-ended list of values (`x-extensible-enum`) for enumeration types" }, { "id": "#113",