[Security Solution] Improve documentation for version and revision fields (#216074)

**Resolves: elastic/security-docs#3545

## Summary

I am fixing documentation for the version and revision fields.
I used this page as the base documentation:
https://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions

The changes:
- by marking the RuleVersion as read-only I am making sure we are
properly documenting that this field is not to be used in the request.
It is only returned in the response.
- by introducing RuleRevision type and marking it as read-only, I am
doing the same for this field, saying that this field is not supposed to
be used in the request.
- I am not changing any code in the app, as the ticket says we shouldn't
do any breaking changes and the update of the version should not cause
400 error. Basically current behavior is kept: users can still update
the version to whatever value they want, including going backwards, and
the changes to revision field is completely ignored.
- I am adding a condensed description of these fields.

I wanted to introduce an internal link between these two fields, but I
couldn't make it work in Bump.sh (even though this should work, normal
Markdown links) so I abandoned this idea.

You can also use this [link](https://bump.sh/jkelas2/doc/kibana_wip2)
where I deployed the generated bundled doc.

Screenshots:

<img width="664" alt="image"
src="https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447"
/>

<img width="660" alt="image"
src="https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6"
/>

---------

Co-authored-by: kibanamachine <[email protected]>

Author: Jacek Kolezynski

oas_docs/output/kibana.serverless.yaml

@@ -53198,8 +53198,7 @@ components:
         required_fields:
           $ref: '#/components/schemas/Security_Detections_API_RequiredFieldArray'
         revision:
-          minimum: 0
-          type: integer
+          $ref: '#/components/schemas/Security_Detections_API_RuleRevision'
         rule_id:
           $ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
         rule_source:
@@ -53545,6 +53544,15 @@ components:
         - $ref: '#/components/schemas/Security_Detections_API_EsqlRule'
       discriminator:
         propertyName: type
+    Security_Detections_API_RuleRevision:
+      description: |
+        The rule's revision number.
+
+        It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
+        > info
+        > Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
+      minimum: 0
+      type: integer
     Security_Detections_API_RuleSignatureId:
       description: Could be any string, not necessarily a UUID
       type: string
@@ -53573,7 +53581,13 @@ components:
       discriminator:
         propertyName: type
     Security_Detections_API_RuleVersion:
-      description: The rule's version number.
+      description: |
+        The rule's version number.
+
+        - For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules). 
+        - For custom rules it is set to `1` when the rule is created. 
+        > info
+        > It is not incremented on each update. Compare this to the `revision` field.
       minimum: 1
       type: integer
     Security_Detections_API_SavedObjectResolveAliasPurpose:

oas_docs/output/kibana.yaml

@@ -62042,8 +62042,7 @@ components:
         required_fields:
           $ref: '#/components/schemas/Security_Detections_API_RequiredFieldArray'
         revision:
-          minimum: 0
-          type: integer
+          $ref: '#/components/schemas/Security_Detections_API_RuleRevision'
         rule_id:
           $ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
         rule_source:
@@ -62389,6 +62388,15 @@ components:
         - $ref: '#/components/schemas/Security_Detections_API_EsqlRule'
       discriminator:
         propertyName: type
+    Security_Detections_API_RuleRevision:
+      description: |
+        The rule's revision number.
+
+        It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
+        > info
+        > Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
+      minimum: 0
+      type: integer
     Security_Detections_API_RuleSignatureId:
       description: Could be any string, not necessarily a UUID
       type: string
@@ -62417,7 +62425,13 @@ components:
       discriminator:
         propertyName: type
     Security_Detections_API_RuleVersion:
-      description: The rule's version number.
+      description: |
+        The rule's version number.
+
+        - For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules). 
+        - For custom rules it is set to `1` when the rule is created. 
+        > info
+        > It is not incremented on each update. Compare this to the `revision` field.
       minimum: 1
       type: integer
     Security_Detections_API_SavedObjectResolveAliasPurpose:

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.gen.ts

@@ -35,11 +35,28 @@ export type RuleDescription = z.infer<typeof RuleDescription>;
 export const RuleDescription = z.string().min(1);
 
 /**
- * The rule's version number.
- */
+  * The rule's version number.
+
+- For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules). 
+- For custom rules it is set to `1` when the rule is created. 
+> info
+> It is not incremented on each update. Compare this to the `revision` field.
+
+  */
 export type RuleVersion = z.infer<typeof RuleVersion>;
 export const RuleVersion = z.number().int().min(1);
 
+/**
+  * The rule's revision number.
+
+It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
+> info
+> Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
+
+  */
+export type RuleRevision = z.infer<typeof RuleRevision>;
+export const RuleRevision = z.number().int().min(0);
+
 export type QueryLanguage = z.infer<typeof QueryLanguage>;
 export const QueryLanguage = z.enum(['kuery', 'lucene', 'eql', 'esql']);
 export type QueryLanguageEnum = typeof QueryLanguage.enum;

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml

@@ -24,7 +24,23 @@ components:
     RuleVersion:
       type: integer
       minimum: 1
-      description: The rule's version number.
+      description: |
+        The rule's version number.
+
+        - For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules). 
+        - For custom rules it is set to `1` when the rule is created. 
+        > info
+        > It is not incremented on each update. Compare this to the `revision` field.
+
+    RuleRevision:
+      type: integer
+      minimum: 0
+      description: |
+        The rule's revision number.
+
+        It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
+        > info
+        > Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
 
     QueryLanguage:
       type: string

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/rule_schemas.gen.ts

@@ -59,6 +59,7 @@ import {
   RuleSignatureId,
   IsRuleImmutable,
   RuleSource,
+  RuleRevision,
   RequiredFieldArray,
   RuleQuery,
   IndexPatternArray,
@@ -166,7 +167,7 @@ export const ResponseFields = z.object({
   updated_by: z.string(),
   created_at: z.string().datetime(),
   created_by: z.string(),
-  revision: z.number().int().min(0),
+  revision: RuleRevision,
   required_fields: RequiredFieldArray,
   execution_summary: RuleExecutionSummary.optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/rule_schemas.schema.yaml

@@ -193,8 +193,7 @@ components:
         created_by:
           type: string
         revision:
-          type: integer
-          minimum: 0
+          $ref: './common_attributes.schema.yaml#/components/schemas/RuleRevision'
         # NOTE: For now, Required Fields are
         # supported for prebuilt rules only. We don't want to allow users to edit these 3
         # fields via the API. If we added them to baseParams.defaultable, they would

x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml

@@ -5105,8 +5105,7 @@ components:
         required_fields:
           $ref: '#/components/schemas/RequiredFieldArray'
         revision:
-          minimum: 0
-          type: integer
+          $ref: '#/components/schemas/RuleRevision'
         rule_id:
           $ref: '#/components/schemas/RuleSignatureId'
         rule_source:
@@ -5495,6 +5494,25 @@ components:
         - $ref: '#/components/schemas/EsqlRule'
       discriminator:
         propertyName: type
+    RuleRevision:
+      description: >
+        The rule's revision number.
+
+
+        It represents the version of rule's object in Kibana. It is set to `0`
+        when the rule is installed or created and then gets incremented on each
+        update.
+
+        > info
+
+        > Not all updates to any rule fields will increment the revision. Only
+        those fields that are considered static `rule parameters` can trigger
+        revision increments. For example, an update to a rule's query or index
+        fields will increment the rule's revision by `1`. However, changes to
+        dynamic or technical fields like enabled or execution_summary will not
+        cause revision increments.
+      minimum: 0
+      type: integer
     RuleSignatureId:
       description: Could be any string, not necessarily a UUID
       type: string
@@ -5528,7 +5546,21 @@ components:
       discriminator:
         propertyName: type
     RuleVersion:
-      description: The rule's version number.
+      description: >
+        The rule's version number.
+
+
+        - For prebuilt rules it represents the version of the rule's content in
+        the source [detection-rules](https://github.com/elastic/detection-rules)
+        repository (and the corresponding `security_detection_engine` Fleet
+        package that is used for distributing prebuilt rules). 
+
+        - For custom rules it is set to `1` when the rule is created. 
+
+        > info
+
+        > It is not incremented on each update. Compare this to the `revision`
+        field.
       minimum: 1
       type: integer
     SavedObjectResolveAliasPurpose:

x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml

@@ -4364,8 +4364,7 @@ components:
         required_fields:
           $ref: '#/components/schemas/RequiredFieldArray'
         revision:
-          minimum: 0
-          type: integer
+          $ref: '#/components/schemas/RuleRevision'
         rule_id:
           $ref: '#/components/schemas/RuleSignatureId'
         rule_source:
@@ -4754,6 +4753,25 @@ components:
         - $ref: '#/components/schemas/EsqlRule'
       discriminator:
         propertyName: type
+    RuleRevision:
+      description: >
+        The rule's revision number.
+
+
+        It represents the version of rule's object in Kibana. It is set to `0`
+        when the rule is installed or created and then gets incremented on each
+        update.
+
+        > info
+
+        > Not all updates to any rule fields will increment the revision. Only
+        those fields that are considered static `rule parameters` can trigger
+        revision increments. For example, an update to a rule's query or index
+        fields will increment the rule's revision by `1`. However, changes to
+        dynamic or technical fields like enabled or execution_summary will not
+        cause revision increments.
+      minimum: 0
+      type: integer
     RuleSignatureId:
       description: Could be any string, not necessarily a UUID
       type: string
@@ -4787,7 +4805,21 @@ components:
       discriminator:
         propertyName: type
     RuleVersion:
-      description: The rule's version number.
+      description: >
+        The rule's version number.
+
+
+        - For prebuilt rules it represents the version of the rule's content in
+        the source [detection-rules](https://github.com/elastic/detection-rules)
+        repository (and the corresponding `security_detection_engine` Fleet
+        package that is used for distributing prebuilt rules). 
+
+        - For custom rules it is set to `1` when the rule is created. 
+
+        > info
+
+        > It is not incremented on each update. Compare this to the `revision`
+        field.
       minimum: 1
       type: integer
     SavedObjectResolveAliasPurpose: