[8.x] [Security Solution] Improve documentation for version and revision fields (#216074) (#216531)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Security Solution] Improve documentation for `version` and
`revision` fields
(#216074)](#216074)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Jacek
Kolezynski","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-03-31T18:06:13Z","message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:Detections
and Resp","Team: SecuritySolution","Feature:Rule
Management","APIDocs","Team:Detection Rule Management","Feature:Prebuilt
Detection Rules","backport:version","9.1
candidate","v9.1.0","v8.19.0"],"title":"[Security Solution] Improve
documentation for `version` and `revision`
fields","number":216074,"url":"https://github.com/elastic/kibana/pull/216074","mergeCommit":{"message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/216074","number":216074,"mergeCommit":{"message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f"}},{"branch":"8.x","label":"v8.19.0","branchLabelMappingKey":"^v8.19.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Jacek Kolezynski <[email protected]>

Author: kibanamachine

oas_docs/output/kibana.serverless.yaml

@@ -50145,8 +50145,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:
@@ -50492,6 +50491,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
@@ -50520,7 +50528,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

@@ -35675,8 +35675,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:
@@ -36022,6 +36021,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
@@ -36050,7 +36058,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

@@ -5115,8 +5115,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:
@@ -5505,6 +5504,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
@@ -5538,7 +5556,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

@@ -4109,8 +4109,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:
@@ -4499,6 +4498,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
@@ -4532,7 +4550,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: