feat(guidelines): Segregate SHOULD from MUST guidelines

api-guidelines/async/kafka/topics/rules/must-follow-kafka-topic-naming-convention.md

@@ -37,7 +37,7 @@ de.otto.events.checkout.payment.payment-received
 ### Data change events
 
 Topics containing data change events must be named analogue to the contained [data event types](../../../format/cloudevents/rules/must-follow-naming-schema-for-type-context-attribute.md).
-If the data topic contains data events of different types all containing the complete state of one particular entity type, the topic must be named after the entity type. The topic name should be in plural form.
+If the data topic contains data events of different types all containing the complete state of one particular entity type, the topic must be named after the entity type. The topic name [should be in plural form](./should-use-plural-form-for-data-topic-names.md).
 
 Examples:
 
@@ -53,5 +53,6 @@ This rule only applies to API topics. Topics which are not part of the API must
 ::: references
 
 - [MUST name events in past tense](../../../format/naming-conventions/rules/must-name-events-in-past-tense.md)
+- [SHOULD use plural form for data topic names](./should-use-plural-form-for-data-topic-names.md)
 - [OTTO CoE Confluent Cloud - Topic Naming Conventions (internal link)](https://otto-eg.atlassian.net/wiki/x/xMPmAQ)
   :::

api-guidelines/async/kafka/topics/rules/should-use-plural-form-for-data-topic-names.md

@@ -0,0 +1,14 @@
+---
+id: R200020
+---
+
+# SHOULD use plural form for data topic names
+
+When naming data topics that contain data events of different types all representing the complete state of one particular entity type, the topic name should be in plural form.
+
+This convention helps distinguish entity-based topics from other topic types and follows common API naming patterns.
+
+::: references
+
+- [MUST follow kafka topic naming convention](./must-follow-kafka-topic-naming-convention.md)
+  :::

api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/must-use-absolute-profile-uris.md

@@ -6,13 +6,11 @@ id: R100066
 
 Profiles must be identified by absolute URIs (as defined in [RFC 6906](https://www.rfc-editor.org/rfc/rfc6906#section-3)) and documented in the OpenAPI specification.
 
-The URI that identifies a profile must be treated as an identifier that should not change.
-While encouraged, it does not need to be resolvable.
-If it is resolvable, it should provide human-readable documentation of the profile.
+The URI that identifies a profile must be treated as an identifier. [The URI should not change](./should-treat-profile-uris-as-immutable.md) over time. While encouraged, it does not need to be resolvable. [If it is resolvable, it should provide human-readable documentation](./should-provide-documentation-for-resolvable-profiles.md) of the profile.
 
 Best practice:
 
-The URI should be in the same URL namespace as the API endpoints.
+[The URI should be in the same URL namespace as the API endpoints](./should-use-same-namespace-for-profile-uris.md).
 For example, if all API endpoints are located at `https://api.otto.de/payment/`, the profile URIs should als be located at the same context path (e.g., `https://api.otto.de/payment/profiles/payment-method+v1`).
 
 The last part of the profile URI path must be in the format "{name}+v{version}".
@@ -26,4 +24,7 @@ Examples:
 ::: references
 
 - [MUST use kebab-case for URIs](../../../resources/naming-conventions/rules/must-use-kebabcase-for-uris.md)
+- [SHOULD treat profile URIs as immutable](./should-treat-profile-uris-as-immutable.md)
+- [SHOULD provide documentation for resolvable profiles](./should-provide-documentation-for-resolvable-profiles.md)
+- [SHOULD use same namespace for profile URIs](./should-use-same-namespace-for-profile-uris.md)
   :::

api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-provide-documentation-for-resolvable-profiles.md

@@ -0,0 +1,14 @@
+---
+id: R100075
+---
+
+# SHOULD provide documentation for resolvable profiles
+
+If a profile URI is resolvable, it should provide human-readable documentation of the profile.
+
+This helps API consumers understand the purpose and usage of the profile.
+
+::: references
+
+- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md)
+  :::

api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-treat-profile-uris-as-immutable.md

@@ -0,0 +1,14 @@
+---
+id: R100073
+---
+
+# SHOULD treat profile URIs as immutable
+
+The URI that identifies a profile should be treated as an identifier that does not change over time.
+
+This ensures that clients can rely on the URI as a stable identifier for the profile, preventing breaking changes in API contracts.
+
+::: references
+
+- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md)
+  :::

api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-use-same-namespace-for-profile-uris.md

@@ -0,0 +1,16 @@
+---
+id: R100076
+---
+
+# SHOULD use same namespace for profile URIs
+
+Profile URIs should be in the same URL namespace as the API endpoints.
+
+For example, if all API endpoints are located at `https://api.otto.de/payment/`, the profile URIs should also be located at the same context path (e.g., `https://api.otto.de/payment/profiles/payment-method+v1`).
+
+This convention helps maintain consistency and makes it easier for API consumers to locate and understand the relationship between APIs and their profiles.
+
+::: references
+
+- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md)
+  :::

api-guidelines/rest/hypermedia/link-relation-types/rules/must-use-absolute-uris-for-custom-link-relation-types.md

@@ -10,9 +10,7 @@ This rule applies to APIs that have to comply with [REST maturity level 3](../..
 
 Custom link relations must be absolute URIs (as defined in [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988#section-4.2)) and documented in the OpenAPI specification.
 
-The URI used as the link relation type must be treated as an identifier that should not change.
-While encouraged, it does not need to be resolvable.
-If the URI is resolvable, it should provide human-readable documentation of the link relation type.
+The URI used as the link relation type must be treated as an identifier. [The URI should not change](./should-treat-link-relation-uris-as-immutable.md) over time. While encouraged, it does not need to be resolvable. [If the URI is resolvable, it should provide human-readable documentation](./should-provide-documentation-for-resolvable-link-relation-uris.md) of the link relation type.
 
 Here's an example of an uncuried link relation that serves for demonstration only.
 In your APIs, you [must use curied link relation types](./must-use-curied-link-relation-types.md).
@@ -32,6 +30,8 @@ In your APIs, you [must use curied link relation types](./must-use-curied-link-r
 - [MUST prefer IANA-registered link relation types](./must-prefer-iana-registered-link-relation-types.md)
 - [MUST use kebab-case for URIs](../../../resources/naming-conventions/rules/must-use-kebabcase-for-uris.md)
 - [MUST use curied link relation types](./must-use-curied-link-relation-types.md)
+- [SHOULD treat link relation URIs as immutable](./should-treat-link-relation-uris-as-immutable.md)
+- [SHOULD provide documentation for resolvable link relation URIs](./should-provide-documentation-for-resolvable-link-relation-uris.md)
 - [MUST implement REST maturity level 2](../../maturity-level/rules/must-implement-rest-maturity-level-2.md)
 - [MUST implement REST maturity level 3 for transitional APIs](../../maturity-level/rules/must-implement-rest-maturity-level-3-for-transitional-apis.md)
   :::

api-guidelines/rest/hypermedia/link-relation-types/rules/should-provide-documentation-for-resolvable-link-relation-uris.md

@@ -0,0 +1,14 @@
+---
+id: R100043
+---
+
+# SHOULD provide documentation for resolvable link relation URIs
+
+If the URI used as a link relation type is resolvable, it should provide human-readable documentation of the link relation type.
+
+This helps API consumers understand the purpose and usage of custom link relation types.
+
+::: references
+
+- [MUST use absolute URIs for custom link relation types](./must-use-absolute-uris-for-custom-link-relation-types.md)
+  :::

api-guidelines/rest/hypermedia/link-relation-types/rules/should-treat-link-relation-uris-as-immutable.md

@@ -0,0 +1,14 @@
+---
+id: R100042
+---
+
+# SHOULD treat link relation URIs as immutable
+
+The URI used as the link relation type should be treated as an identifier that does not change over time.
+
+This ensures that clients can rely on the URI as a stable identifier for the link relation type, preventing breaking changes in API contracts.
+
+::: references
+
+- [MUST use absolute URIs for custom link relation types](./must-use-absolute-uris-for-custom-link-relation-types.md)
+  :::