docs: Adjust design principles sections of Arazzo rules

Redocly · Oct 25, 2024 · 47a7701 · 47a7701
1 parent b3f89f3
commit 47a7701
Show file tree

Hide file tree

Showing 11 changed files with 27 additions and 22 deletions.
diff --git a/docs/rules/arazzo/criteria-unique.md b/docs/rules/arazzo/criteria-unique.md
@@ -6,9 +6,9 @@ The criteria list must not contain duplicated assertions.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-The criteria list must not contain duplicated assertions.
+To avoid redundancy and confusion, the assertions in the criteria list must not be duplicated.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md
@@ -6,12 +6,12 @@ Requires unique values in the `parameters` lists.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
 A list of `parameters` that are applicable to a step or all the steps described in a workflow should not contain duplicates.
 If duplicates are present, unexpected parameter overrides could cause problems.
 
-Checks parameter lists in the following locations:
+This ruled checks parameter lists in the following locations:
 
 - `workflows.[workflow].parameters`
 - `workflows.[workflow[.steps.[step].parameters`

diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md
@@ -6,7 +6,7 @@ Requires the `replacements` in the `step.requestBody` object to be unique.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
 The list of locations and values to set within a payload must not have duplicates that might result in content override.
 

diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md
@@ -1,14 +1,15 @@
 # sourceDescriptions-name-unique
 
-The `name` property of the Source Description object must be unique across all source descriptions..
+The `name` property of the Source Description object must be unique across all source descriptions.
 
 | Arazzo | Compatibility |
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
 To avoid confusion or unexpected outputs, each Source Description object should have a unique `name` property.
+Especially in a longer list of sources, this could be difficult to identify and could have unwanted side effects.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/sourceDescriptions-not-empty.md b/docs/rules/arazzo/sourceDescriptions-not-empty.md
@@ -6,9 +6,10 @@ The Source Description must have at least one entry.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-According to the Arazzo spec `sourceDescriptions` is required and the list must have at least one entry.
+Source descriptions are an important part of an Arazzo description, and at least one entry must exist.
+If the list is empty, this could indicate an omission or another problem; this rule will alert you if that happens.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md
@@ -6,9 +6,10 @@ The `type` property of the Source Description object must be either `openapi` or
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-According to the Arazzo spec, the possible values of the Source Description `type` are `openapi` or `arazzo`.
+Arazzo currently supports either an OpenAPI file or another Arazzo file as the source description.
+This rule makes sure that the type is clearly identified and is one of the supported types.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md
@@ -6,9 +6,10 @@ Requires all of the `onFailure` actions of the `step` object to be unique.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
 Each `onFailure` action should be unique to avoid confusion or unexpected results.
+A duplicate could indicate a mistake, or cause unwanted side effects if not detected by this rule.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md
@@ -6,9 +6,10 @@ Requires the `onSuccess` actions of the `step` object to be unique.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
 Each `onSuccess` action should be unique to avoid confusion or unexpected outcomes.
+A duplicate could indicate a mistake, or cause unwanted side effects if not detected by this rule.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md
@@ -6,11 +6,12 @@ Requires the `stepId` to be unique amongst all steps described in the workflow.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-The `stepId` is a unique string that represents the step.
-The `stepId` must be unique amongst all steps described in the workflow.
-The `stepId` value is case-sensitive.
+The steps in a workflow each have a required `stepId` field and this must be unique in order to conform with the specification.
+This rule catches any accidental duplication of `stepId` values so that the workflow is valid.
+
+Note: `stepId` values are considered to be case-sensitive.
 
 ## Configuration
 

diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md
@@ -6,9 +6,8 @@ Requires the items in the `workflow` `dependsOn` property to exist and to be uni
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-A list of workflows that should be completed before current workflow can be processed.
 To avoid ambiguity or potential clashes, the `dependsOn` list values should be unique.
 
 ## Configuration

diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md
@@ -6,10 +6,10 @@ Requires the `workflowId` property to be unique across all workflows.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-The `workflowId` is a string that represents the workflow.
-According to the spec, the `workflowId` must be unique across all workflows described in the API definition.
+According to the spec, the `workflowId` must be unique across all workflows described in the API description.
+Duplication could also indicate a typo or other mistake; this rule alerts you if such a situation arises.
 
 ## Configuration