docs(rulesets): remove old oas2/3-valid-example rules (#2188)

docs/getting-started/1-concepts.md

@@ -4,11 +4,11 @@ The power of integrating linting into the design-first workflow, or any workflow
 
 To achieve this, Spectral has three key concepts:
 
-- **Rulesets** act as a container for rules and functions.
 - **Rules** filter your object down to a set of target values and specify the function that is used to evaluate those values.
 - **Functions** accept a value and return issues if the value is incorrect.
+- **Rulesets** act as a container for rules and functions.
 
-Rules can be comprised of one of more functions. For example:
+Rules can be comprised of one of more functions, to standardize structured content, like making sure your OpenAPI descriptions match your [API style guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices):
 
 - HTTP Basic is not allowed at this company
 - All operations are secured with a security schema

docs/getting-started/3-rulesets.md

@@ -83,8 +83,8 @@ Formats are an optional way to specify which API description formats a rule, or
 - `aas2_4` (AsyncAPI v2.4.0)
 - `oas2` (OpenAPI v2.0)
 - `oas3` (OpenAPI v3.x)
-- `oas3.0` (OpenAPI v3.0.x)
-- `oas3.1` (OpenAPI v3.1.x)
+- `oas3_0` (OpenAPI v3.0.x)
+- `oas3_1` (OpenAPI v3.1.x)
 - `json-schema` (`$schema` says this is some JSON Schema draft)
 - `json-schema-loose` (looks like JSON Schema, but no `$schema` found)
 - `json-schema-draft4` (`$schema` says this is JSON Schema Draft 04)

docs/reference/openapi-rules.md

@@ -6,7 +6,7 @@ In your ruleset file you can add `extends: "spectral:oas"` and you'll get all of
 
 ## OpenAPI v2 & v3
 
-These rules apply to both OpenAPI v2 and v3.
+These rules apply to both OpenAPI v2.0, v3.0, and most likely v3.1, although there are some differences.
 
 ### operation-success-response
 
@@ -186,7 +186,7 @@ info:
 
 ### no-\$ref-siblings
 
-An object exposing a `$ref` property cannot be further extended with additional properties.
+Prior to OpenAPI v3.1, keywords next to `$ref` were be ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied.
 
 **Recommended:** Yes
 
@@ -195,9 +195,8 @@ An object exposing a `$ref` property cannot be further extended with additional
 ```yaml
 TheBadModel:
   $ref: "#/components/TheBadModelProperties"
-  examples: # <= This property will be ignored
-    an_example:
-      name: something
+  # This property should be ignored
+  example: May or may not show up
 ```
 
 ### no-eval-in-markdown
@@ -502,15 +501,13 @@ Ignores empty `security` values for cases where authentication is explicitly not
 
 Potential unused reusable `definition` entry has been detected.
 
-_Warning:_ This rule may identify false positives when linting a specification
-that acts as a library (a container storing reusable objects, leveraged by other
-specifications that reference those objects).
+<!-- theme: warning -->
 
-**Recommended:** Yes
-
-### oas2-valid-example
-
-Examples must be valid against their defined schema.
+> #### Warning
+>
+> This rule may identify false positives when linting a specification
+> that acts as a library (a container storing reusable objects, leveraged by other
+> specifications that reference those objects).
 
 **Recommended:** Yes
 
@@ -640,15 +637,13 @@ servers:
 
 Potential unused reusable `components` entry has been detected.
 
-_Warning:_ This rule may identify false positives when linting a specification
-that acts as a library (a container storing reusable objects, leveraged by other
-specifications that reference those objects).
-
-**Recommended:** Yes
-
-### oas3-valid-example
+<!-- theme: warning -->
 
-Examples must be valid against their defined schema.
+> #### Warning
+>
+> This rule may identify false positives when linting a specification
+> that acts as a library (a container storing reusable objects, leveraged by other
+> specifications that reference those objects).
 
 **Recommended:** Yes