docs(schema): add schema versioning (#3845)

Signed-off-by: Jiyong Huang <huangjy@emqx.io>

Author: ngjaying

docs/en_US/api/restapi/schemas.md

@@ -111,3 +111,36 @@ PUT http://localhost:9081/schemas/protobuf/{name}
   "file": "http://ahot.com/test2.proto"
 }
 ```
+
+## Versioning
+
+The schema can have an optional **version** field. This field is essential for controlling updates and ensuring that new
+schemas are correctly applied. When you update a schema, the system compares the new version string to the existing one.
+An update is only accepted if the new version is **lexically greater** than the old one. This comparison is a
+character-by-character string comparison, not a numerical one.
+
+### Versioning Logic
+
+- **No Version Specified:** If neither the old nor the new schema has a `version` field, the update will proceed. This
+  behavior aligns with the original, unversioned logic.
+- **Versioning Set:** If a `version` field is present in either the old or the new schema, the system will always
+  perform a version comparison. The presence of any version string triggers the new comparison logic.
+- **Lexical Comparison:** Updates are based on a lexical (string) comparison. The new schema's `version` must be
+  lexicographically greater than the current one for the update to be successful.
+- **Smallest Version:** A schema without a `version` field is considered to have the "smallest possible" version. This
+  means that adding a version field to an existing, unversioned schema will always result in a successful update, as any
+  new version string will be lexically greater than the non-existent one.
+
+To avoid confusion and ensure correct ordering, it's highly recommended to use a **timestamp** as the version string.
+Timestamps, such as Unix epoch time, provide a universally unique and monotonically increasing value that naturally
+satisfies the lexical comparison rule.
+
+Below is an example schema request with version:
+
+```json
+{
+  "name": "schema2",
+  "file": "file:///tmp/ekuiper/internal/schema/test/test2.proto",
+  "version": "1756436910"
+}
+```

docs/en_US/guide/serialization/protobuf_tutorial.md

@@ -25,7 +25,7 @@ message Book {
 2. In the schema creation window, fill in the fields as shown in the following figure. The schema type is `protobuf`; the schema name can be entered as a custom unique name to identify the schema id in the subsequent rule creation; the schema content can be filled in as a file or text content. If you choose file, you need to fill in the url of the file; the schema used in this tutorial is simple, so you can choose content and fill in the text of the proto file in the content box.
    ![create schema detail](./resources/create_detail.png)
 3. Click Submit. You should be able to see the newly created schema in the list of schemas. You can then use the buttons in the action bar to modify or delete it.
-   ![lsit schemas](./resources/list_schema.png)
+   ![list schemas](./resources/list_schema.png)
 
 At this point, we have registered a schema named `schema1`, which defines the type `Book`, and the registered schema can be used in the source and sink of the rule. Users can also continue to register and manage more schemas in this page.
 

docs/zh_CN/api/restapi/schemas.md

@@ -112,3 +112,28 @@ PUT http://localhost:9081/schemas/protobuf/{name}
   "file": "http://ahot.com/test2.proto"
 }
 ```
+
+## 版本控制 (Versioning)
+
+模式（schema）可以包含一个可选的 **version** 字段。此字段对于控制更新和确保正确应用新模式至关重要。当您更新一个模式时，系统会将新的版本字符串与现有版本进行比较。只有当新版本在
+**词典顺序上更大**时，更新才会被接受。这个比较是逐个字符的字符串比较，而不是数值比较。
+
+### 版本控制逻辑
+
+- **未指定版本**：如果新旧模式都没有 `version` 字段，更新将直接进行。此行为与原始未版本化模式的逻辑一致。
+- **已设置版本**：如果新旧模式中有一个包含 `version` 字段，系统将始终执行版本比较。任何版本字符串的存在都会触发新的比较逻辑。
+- **词典比较**：更新基于词典（字符串）比较。为了使更新成功，新模式的 `version` 必须在词典顺序上大于当前版本。
+- **最小版本**：不带 `version` 字段的模式被视为具有“最小可能”版本。这意味着，向一个现有的、未版本化的模式添加 `version`
+  字段总能成功更新，因为任何新的版本字符串在词典顺序上都会大于不存在的版本。
+
+为了避免混淆并确保正确的顺序，强烈建议使用**时间戳**作为版本字符串。例如，Unix 纪元时间戳可以提供一个全球唯一且单调递增的值，这天然满足了词典比较规则。
+
+以下是一个带有版本字段的模式请求示例：
+
+```json
+{
+  "name": "schema2",
+  "file": "file:///tmp/ekuiper/internal/schema/test/test2.proto",
+  "version": "1756436910"
+}
+```