You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/10/12 08:13:34 UTC
(fory-site) 01/01: docs: publish Apache Fory 1.7.7
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch release-1.7.7
in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit a2ce381a994ceb8609fde7aff7a6b52afee7150a
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Mon Oct 12 16:13:25 2026 +0800
docs: publish Apache Fory 1.7.7
---
blog/2026-10-12-fory_1_7_7_released.md | 70 ++++++++++++++++++++++
docs/compiler/build-integration.md | 2 +-
docs/compiler/cli.md | 2 +-
docs/grpc/csharp.md | 4 +-
docs/grpc/dart.md | 2 +-
docs/grpc/rust.md | 2 +-
docs/json/getting-started.md | 6 +-
docs/json/kotlin.md | 4 +-
docs/json/scala.md | 2 +-
docs/object-serialization/cpp/index.md | 8 +--
docs/object-serialization/csharp/index.md | 2 +-
docs/object-serialization/dart/index.md | 2 +-
docs/object-serialization/java/index.md | 4 +-
docs/object-serialization/kotlin/index.md | 4 +-
.../rust/basic-serialization.md | 2 +-
docs/object-serialization/rust/index.md | 8 +--
docs/object-serialization/scala/index.md | 2 +-
docs/row-format/java.md | 4 +-
docs/start/cpp.md | 2 +-
docs/start/csharp.md | 2 +-
docs/start/dart.md | 2 +-
docs/start/go.md | 2 +-
docs/start/java.md | 6 +-
docs/start/javascript.md | 4 +-
docs/start/kotlin.md | 4 +-
docs/start/python.md | 2 +-
docs/start/rust.md | 2 +-
docs/start/scala.md | 2 +-
docs/start/swift.md | 2 +-
.../2026-10-12-fory_1_7_7_released.md | 62 +++++++++++++++++++
.../current/compiler/build-integration.md | 2 +-
.../current/compiler/cli.md | 2 +-
.../current/compiler/generated-code/csharp.md | 3 +-
.../current/compiler/generated-code/index.md | 7 +++
.../current/compiler/generated-code/kotlin.md | 5 +-
.../current/compiler/generated-code/python.md | 8 +++
.../current/compiler/generated-code/rust.md | 5 +-
.../current/compiler/generated-code/scala.md | 3 +-
.../current/compiler/generated-code/swift.md | 8 +--
.../current/grpc/csharp.md | 4 +-
.../current/grpc/dart.md | 2 +-
.../current/grpc/rust.md | 2 +-
.../current/json/annotations.md | 57 ++++++++++++++++--
.../current/json/custom-codecs.md | 12 +++-
.../current/json/getting-started.md | 6 +-
.../current/json/kotlin.md | 14 +++--
.../current/json/object-mapping.md | 35 +++++++++--
.../current/json/scala.md | 11 +++-
.../current/object-serialization/cpp/index.md | 8 +--
.../current/object-serialization/csharp/index.md | 2 +-
.../object-serialization/csharp/schema-metadata.md | 2 +-
.../current/object-serialization/dart/index.md | 2 +-
.../current/object-serialization/java/index.md | 4 +-
.../current/object-serialization/kotlin/index.md | 4 +-
.../kotlin/static-generated-serializers.md | 3 +-
.../rust/basic-serialization.md | 2 +-
.../current/object-serialization/rust/index.md | 8 +--
.../scala/basic-serialization.md | 4 +-
.../current/object-serialization/scala/index.md | 2 +-
.../object-serialization/scala/schema-metadata.md | 4 +-
.../object-serialization/swift/schema-metadata.md | 4 +-
.../current/row-format/java.md | 4 +-
.../current/start/cpp.md | 2 +-
.../current/start/csharp.md | 2 +-
.../current/start/dart.md | 2 +-
.../current/start/go.md | 2 +-
.../current/start/java.md | 6 +-
.../current/start/javascript.md | 4 +-
.../current/start/kotlin.md | 4 +-
.../current/start/python.md | 2 +-
.../current/start/rust.md | 2 +-
.../current/start/scala.md | 2 +-
.../current/start/swift.md | 2 +-
.../version-1.7.0/compiler/build-integration.md | 2 +-
.../version-1.7.0/compiler/cli.md | 2 +-
.../compiler/generated-code/csharp.md | 3 +-
.../version-1.7.0/compiler/generated-code/index.md | 7 +++
.../compiler/generated-code/kotlin.md | 5 +-
.../compiler/generated-code/python.md | 8 +++
.../version-1.7.0/compiler/generated-code/rust.md | 5 +-
.../version-1.7.0/compiler/generated-code/scala.md | 3 +-
.../version-1.7.0/compiler/generated-code/swift.md | 8 +--
.../version-1.7.0/grpc/csharp.md | 4 +-
.../version-1.7.0/grpc/dart.md | 2 +-
.../version-1.7.0/grpc/rust.md | 2 +-
.../version-1.7.0/json/annotations.md | 57 ++++++++++++++++--
.../version-1.7.0/json/custom-codecs.md | 12 +++-
.../version-1.7.0/json/getting-started.md | 6 +-
.../version-1.7.0/json/kotlin.md | 14 +++--
.../version-1.7.0/json/object-mapping.md | 35 +++++++++--
.../version-1.7.0/json/scala.md | 11 +++-
.../object-serialization/cpp/index.md | 8 +--
.../object-serialization/csharp/index.md | 2 +-
.../object-serialization/csharp/schema-metadata.md | 2 +-
.../object-serialization/dart/index.md | 2 +-
.../object-serialization/java/index.md | 4 +-
.../object-serialization/kotlin/index.md | 4 +-
.../kotlin/static-generated-serializers.md | 3 +-
.../rust/basic-serialization.md | 2 +-
.../object-serialization/rust/index.md | 8 +--
.../scala/basic-serialization.md | 4 +-
.../object-serialization/scala/index.md | 2 +-
.../object-serialization/scala/schema-metadata.md | 4 +-
.../object-serialization/swift/schema-metadata.md | 4 +-
.../version-1.7.0/row-format/java.md | 4 +-
.../version-1.7.0/start/cpp.md | 2 +-
.../version-1.7.0/start/csharp.md | 2 +-
.../version-1.7.0/start/dart.md | 2 +-
.../version-1.7.0/start/go.md | 2 +-
.../version-1.7.0/start/java.md | 6 +-
.../version-1.7.0/start/javascript.md | 4 +-
.../version-1.7.0/start/kotlin.md | 4 +-
.../version-1.7.0/start/python.md | 2 +-
.../version-1.7.0/start/rust.md | 2 +-
.../version-1.7.0/start/scala.md | 2 +-
.../version-1.7.0/start/swift.md | 2 +-
.../download/index.md | 10 ++--
src/components/home/HomepageLanding.tsx | 24 ++++----
src/pages/download/index.md | 10 ++--
.../version-1.7.0/compiler/build-integration.md | 2 +-
versioned_docs/version-1.7.0/compiler/cli.md | 2 +-
.../compiler/generated-code/csharp.md | 3 +-
.../version-1.7.0/compiler/generated-code/index.md | 9 +++
.../compiler/generated-code/kotlin.md | 5 +-
.../compiler/generated-code/python.md | 9 +++
.../version-1.7.0/compiler/generated-code/rust.md | 6 +-
.../version-1.7.0/compiler/generated-code/scala.md | 3 +-
.../version-1.7.0/compiler/generated-code/swift.md | 8 ++-
versioned_docs/version-1.7.0/grpc/csharp.md | 4 +-
versioned_docs/version-1.7.0/grpc/dart.md | 2 +-
versioned_docs/version-1.7.0/grpc/rust.md | 2 +-
versioned_docs/version-1.7.0/json/annotations.md | 63 +++++++++++++++++--
versioned_docs/version-1.7.0/json/custom-codecs.md | 16 ++++-
.../version-1.7.0/json/getting-started.md | 13 ++--
versioned_docs/version-1.7.0/json/kotlin.md | 16 +++--
.../version-1.7.0/json/object-mapping.md | 42 +++++++++++--
versioned_docs/version-1.7.0/json/scala.md | 12 +++-
.../object-serialization/cpp/index.md | 8 +--
.../object-serialization/csharp/index.md | 2 +-
.../object-serialization/csharp/schema-metadata.md | 6 +-
.../object-serialization/dart/index.md | 2 +-
.../object-serialization/java/index.md | 4 +-
.../object-serialization/kotlin/index.md | 4 +-
.../kotlin/static-generated-serializers.md | 3 +-
.../rust/basic-serialization.md | 2 +-
.../object-serialization/rust/index.md | 8 +--
.../scala/basic-serialization.md | 6 +-
.../object-serialization/scala/index.md | 2 +-
.../object-serialization/scala/schema-metadata.md | 4 +-
.../object-serialization/swift/schema-metadata.md | 5 +-
versioned_docs/version-1.7.0/row-format/java.md | 4 +-
versioned_docs/version-1.7.0/start/cpp.md | 2 +-
versioned_docs/version-1.7.0/start/csharp.md | 2 +-
versioned_docs/version-1.7.0/start/dart.md | 2 +-
versioned_docs/version-1.7.0/start/go.md | 2 +-
versioned_docs/version-1.7.0/start/java.md | 6 +-
versioned_docs/version-1.7.0/start/javascript.md | 4 +-
versioned_docs/version-1.7.0/start/kotlin.md | 4 +-
versioned_docs/version-1.7.0/start/python.md | 2 +-
versioned_docs/version-1.7.0/start/rust.md | 2 +-
versioned_docs/version-1.7.0/start/scala.md | 2 +-
versioned_docs/version-1.7.0/start/swift.md | 2 +-
162 files changed, 806 insertions(+), 305 deletions(-)
diff --git a/blog/2026-10-12-fory_1_7_7_released.md b/blog/2026-10-12-fory_1_7_7_released.md
new file mode 100644
index 00000000000..239e4615aa0
--- /dev/null
+++ b/blog/2026-10-12-fory_1_7_7_released.md
@@ -0,0 +1,70 @@
+---
+slug: fory_1_7_7_release
+title: Fory v1.7.7 Released
+description: "Fory 1.7.7 adds configurable JSON null handling and fixes object mapping, schema compiler output, and release archive reproducibility."
+authors: [chaokunyang]
+tags: [fory, java, json, kotlin, scala]
+---
+
+Apache Fory 1.7.7 is now available. This release adds read-side JSON null handling and improves
+serialization performance, object mapping, and generated code. See [Getting Started](/docs/start/)
+for installation instructions.
+
+## Highlights
+
+- Configure how JSON readers handle null properties, collection elements, and map values.
+- Reduce JSON codec generation cost, improve string writing, and reduce C++ serialization overhead.
+- Fix JSON object field semantics, compatible field-type validation, and schema compiler output.
+- Make Java and Kotlin release archives reproducible and improve license and notice packaging.
+
+## JSON Null Handling
+
+Use `onNullRead` to control explicit null property values and `onContentNullRead` to control null
+array or collection elements and map values. Both default to `SET`, which retains the existing
+decoding behavior. `SKIP` omits that input occurrence; `FAIL` rejects it.
+
+```java
+import org.apache.fory.json.ForyJson;
+import org.apache.fory.json.annotation.JsonProperty;
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+public final class Response {
+ @JsonProperty(onNullRead = NullHandling.SKIP, onContentNullRead = NullHandling.SKIP)
+ public java.util.List<String> seats = java.util.List.of("default");
+}
+
+ForyJson json = ForyJson.builder().build();
+Response first = json.fromJson("{\"seats\":null}", Response.class);
+Response second = json.fromJson("{\"seats\":[null,\"a\"]}", Response.class);
+// first.seats is ["default"]; second.seats is ["a"].
+```
+
+The same settings are available on the builder. Property annotations override the corresponding
+global setting. Content overrides apply to immediate elements or values; nested containers use
+their applicable settings. These options affect explicit JSON nulls and do not change writing
+or a root value's null behavior.
+
+Kotlin and Scala support these settings through their JSON builders. Skipping a null property
+can retain constructor defaults; required-property checks still apply. See
+[read-side null handling](/docs/json/annotations#read-side-null-handling),
+[Kotlin](/docs/json/kotlin/), and [Scala](/docs/json/scala/) for details.
+
+## Correctness and Performance
+
+JSON object mapping now restores eligible ordinary final fields and consistently selects a
+subclass field when it hides a superclass field. Writing a subclass through a concrete base type
+includes the subclass's mapped properties; restoring the subtype still requires declared subtype
+mapping or a custom codec. See [object mapping](/docs/json/object-mapping/).
+
+Schema compiler fixes cover Java, Kotlin, Scala, Python, and TypeScript output. Generated union
+carriers use an alternate name when a schema case is named `Unknown` or Swift's `unknown`,
+preserving the schema case name. See [generated code](/docs/compiler/generated-code/).
+
+Performance work reduces JSON codec generation cost, avoids unnecessary `NON_EMPTY` checks for
+final property types, improves escaped-string writing, and avoids a temporary vector when
+serializing C++ `std::forward_list`.
+
+The complete release notes are available on
+[GitHub](https://github.com/apache/fory/releases/tag/v1.7.7).
+
+**Full Changelog**: [v1.7.6...v1.7.7](https://github.com/apache/fory/compare/v1.7.6...v1.7.7)
diff --git a/docs/compiler/build-integration.md b/docs/compiler/build-integration.md
index f0dca646633..56dbdd39e05 100644
--- a/docs/compiler/build-integration.md
+++ b/docs/compiler/build-integration.md
@@ -211,7 +211,7 @@ Add the Fory dependency to `pubspec.yaml`:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/docs/compiler/cli.md b/docs/compiler/cli.md
index f4171a8d968..70c135f1300 100644
--- a/docs/compiler/cli.md
+++ b/docs/compiler/cli.md
@@ -689,5 +689,5 @@ fory = "x.y.z"
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
```
diff --git a/docs/grpc/csharp.md b/docs/grpc/csharp.md
index b45b057c3a6..00121bce109 100644
--- a/docs/grpc/csharp.md
+++ b/docs/grpc/csharp.md
@@ -39,7 +39,7 @@ Server project:
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.AspNetCore" Version="2.71.0" />
</ItemGroup>
```
@@ -48,7 +48,7 @@ Client project:
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.Core.Api" Version="2.71.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.71.0" />
</ItemGroup>
diff --git a/docs/grpc/dart.md b/docs/grpc/dart.md
index 0c62882a28c..8a94a64980e 100644
--- a/docs/grpc/dart.md
+++ b/docs/grpc/dart.md
@@ -38,7 +38,7 @@ application that compiles or runs generated service companions:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
grpc: ^4.0.0
dev_dependencies:
diff --git a/docs/grpc/rust.md b/docs/grpc/rust.md
index e6da7b5b1fc..7f67b7ca53d 100644
--- a/docs/grpc/rust.md
+++ b/docs/grpc/rust.md
@@ -37,7 +37,7 @@ to build streaming responses or request streams.
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
bytes = "1"
tonic = { version = "0.14", features = ["transport"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
diff --git a/docs/json/getting-started.md b/docs/json/getting-started.md
index ac679ceedb7..72b2dc4cd40 100644
--- a/docs/json/getting-started.md
+++ b/docs/json/getting-started.md
@@ -43,7 +43,7 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-json</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -57,7 +57,7 @@ repositories {
mavenCentral()
}
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
### Kotlin
@@ -66,7 +66,7 @@ Kotlin/JVM applications add the optional Kotlin JSON runtime and use its single
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/docs/json/kotlin.md b/docs/json/kotlin.md
index 53a3362b8e8..efabbc4d7da 100644
--- a/docs/json/kotlin.md
+++ b/docs/json/kotlin.md
@@ -41,7 +41,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
@@ -54,7 +54,7 @@ plugins {
}
dependencies {
- ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.6")
+ ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.7")
}
```
diff --git a/docs/json/scala.md b/docs/json/scala.md
index 6649b9c65e3..2fc1509cb99 100644
--- a/docs/json/scala.md
+++ b/docs/json/scala.md
@@ -25,7 +25,7 @@ module works on the ordinary JVM and GraalVM Native Image. Android is not suppor
## Setup
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.7"
```
`ForyJsonScala.builder()` installs the Scala module and returns the standard Fory JSON builder:
diff --git a/docs/object-serialization/cpp/index.md b/docs/object-serialization/cpp/index.md
index 4112b645055..4a3a8d08c2e 100644
--- a/docs/object-serialization/cpp/index.md
+++ b/docs/object-serialization/cpp/index.md
@@ -62,7 +62,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -92,11 +92,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v1.7.6", # Or use a specific commit hash for reproducibility
+ commit = "v1.7.7", # Or use a specific commit hash for reproducibility
)
```
@@ -128,7 +128,7 @@ bazel run //:my_app
For local development, you can use `local_path_override` instead:
```bazel
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
diff --git a/docs/object-serialization/csharp/index.md b/docs/object-serialization/csharp/index.md
index 6d6b76c337e..cae69403350 100644
--- a/docs/object-serialization/csharp/index.md
+++ b/docs/object-serialization/csharp/index.md
@@ -46,7 +46,7 @@ Reference the single `Apache.Fory` package. It includes the Fory library and the
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
</ItemGroup>
```
diff --git a/docs/object-serialization/dart/index.md b/docs/object-serialization/dart/index.md
index 2e737dafc2a..072ac42620d 100644
--- a/docs/object-serialization/dart/index.md
+++ b/docs/object-serialization/dart/index.md
@@ -47,7 +47,7 @@ Add the dependency to your `pubspec.yaml`:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/docs/object-serialization/java/index.md b/docs/object-serialization/java/index.md
index 200391d3095..41a0134364e 100644
--- a/docs/object-serialization/java/index.md
+++ b/docs/object-serialization/java/index.md
@@ -63,7 +63,7 @@ or later.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -71,7 +71,7 @@ or later.
```kotlin
// Binary object serialization
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
#### JDK 25 and Later
diff --git a/docs/object-serialization/kotlin/index.md b/docs/object-serialization/kotlin/index.md
index 6e9f7c3b8bd..894ae92503e 100644
--- a/docs/object-serialization/kotlin/index.md
+++ b/docs/object-serialization/kotlin/index.md
@@ -53,14 +53,14 @@ See [Java Features](../java/index.md#features) for complete feature list.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:1.7.6")
+implementation("org.apache.fory:fory-kotlin:1.7.7")
```
### JDK25+
diff --git a/docs/object-serialization/rust/basic-serialization.md b/docs/object-serialization/rust/basic-serialization.md
index e25539885c5..c2e2fe1f3dd 100644
--- a/docs/object-serialization/rust/basic-serialization.md
+++ b/docs/object-serialization/rust/basic-serialization.md
@@ -147,7 +147,7 @@ let later = timestamp.checked_add_duration(duration)?;
```toml
[dependencies]
-fory = { version = "1.7.6", features = ["chrono"] }
+fory = { version = "1.7.7", features = ["chrono"] }
```
### Custom Types
diff --git a/docs/object-serialization/rust/index.md b/docs/object-serialization/rust/index.md
index 4c1cf50092b..37632e35117 100644
--- a/docs/object-serialization/rust/index.md
+++ b/docs/object-serialization/rust/index.md
@@ -37,9 +37,9 @@ The Rust implementation provides versatile and high-performance serialization wi
| Crate | Description | Version |
| --------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------- |
-| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, public Fory types, and derive macros | [1.7.6](https://crates.io/crates/fory) |
-| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level core crate for advanced integrations | [1.7.6](https://crates.io/crates/fory-core) |
-| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macro crate for direct derive-macro use | [1.7.6](https://crates.io/crates/fory-derive) |
+| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, public Fory types, and derive macros | [1.7.7](https://crates.io/crates/fory) |
+| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level core crate for advanced integrations | [1.7.7](https://crates.io/crates/fory-core) |
+| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macro crate for direct derive-macro use | [1.7.7](https://crates.io/crates/fory-derive) |
Most applications should depend on `fory` only. It re-exports the derive
macros and the public Fory types needed by generated code. Use `fory-core`
@@ -52,7 +52,7 @@ Add Apache Fory™ to your `Cargo.toml`:
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
### Basic Example
diff --git a/docs/object-serialization/scala/index.md b/docs/object-serialization/scala/index.md
index fdf64a96c20..2aecbbf8e9f 100644
--- a/docs/object-serialization/scala/index.md
+++ b/docs/object-serialization/scala/index.md
@@ -49,7 +49,7 @@ See [Java Features](../java/index.md#features) for complete feature list.
Add the dependency with sbt:
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
### JDK25+
diff --git a/docs/row-format/java.md b/docs/row-format/java.md
index 835f352e3be..cb9f57560db 100644
--- a/docs/row-format/java.md
+++ b/docs/row-format/java.md
@@ -43,14 +43,14 @@ For Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
For Gradle:
```kotlin
-implementation("org.apache.fory:fory-format:1.7.6")
+implementation("org.apache.fory:fory-format:1.7.7")
```
## Basic Usage
diff --git a/docs/start/cpp.md b/docs/start/cpp.md
index 93a1c3fff17..4dc8d7c3d33 100644
--- a/docs/start/cpp.md
+++ b/docs/start/cpp.md
@@ -45,7 +45,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
diff --git a/docs/start/csharp.md b/docs/start/csharp.md
index a47d9b8c248..b0b37344345 100644
--- a/docs/start/csharp.md
+++ b/docs/start/csharp.md
@@ -36,7 +36,7 @@ Create a console project and add the released package:
```bash
dotnet new console -n ForyExample
cd ForyExample
-dotnet add package Apache.Fory --version 1.7.6
+dotnet add package Apache.Fory --version 1.7.7
```
Replace `Program.cs` with:
diff --git a/docs/start/dart.md b/docs/start/dart.md
index dc4c3afbc4f..34a5ae1febe 100644
--- a/docs/start/dart.md
+++ b/docs/start/dart.md
@@ -36,7 +36,7 @@ Add Fory and the generator to `pubspec.yaml`:
```yaml
dependencies:
- fory: 1.7.6
+ fory: 1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/docs/start/go.md b/docs/start/go.md
index efa03140b03..d9deb503b62 100644
--- a/docs/start/go.md
+++ b/docs/start/go.md
@@ -38,7 +38,7 @@ Create a module and install the released Fory module:
mkdir fory-example
cd fory-example
go mod init example.com/fory-example
-go get github.com/apache/fory/go/fory@v1.7.6
+go get github.com/apache/fory/go/fory@v1.7.7
```
If a Go proxy has not picked up a new submodule tag yet, retry later or use
diff --git a/docs/start/java.md b/docs/start/java.md
index 9bd5f221652..8912b9d0643 100644
--- a/docs/start/java.md
+++ b/docs/start/java.md
@@ -44,14 +44,14 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle:
```kotlin
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
Run this complete xlang round trip:
@@ -97,7 +97,7 @@ Fory JSON maps Java objects to standard JSON text and UTF-8 bytes. Add
`fory-json` instead of `fory-core` when the application only needs JSON:
```kotlin
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
Add the import to `ForyExample.java`:
diff --git a/docs/start/javascript.md b/docs/start/javascript.md
index 3dd7e711e2b..b1b926d8def 100644
--- a/docs/start/javascript.md
+++ b/docs/start/javascript.md
@@ -36,7 +36,7 @@ npm --version
Install the core package:
```bash
-npm install @apache-fory/core@1.7.6
+npm install @apache-fory/core@1.7.7
```
Define a schema and run an xlang round trip:
@@ -72,7 +72,7 @@ JavaScript uses xlang mode. Continue with
For the optional Node.js string fast path, install the matching package version:
```bash
-npm install @apache-fory/core@1.7.6 @apache-fory/hps@1.7.6
+npm install @apache-fory/core@1.7.7 @apache-fory/hps@1.7.7
```
## Other Capabilities
diff --git a/docs/start/kotlin.md b/docs/start/kotlin.md
index faa65bd945c..1ad5c966b53 100644
--- a/docs/start/kotlin.md
+++ b/docs/start/kotlin.md
@@ -44,7 +44,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-kotlin:1.7.7")
}
```
@@ -88,7 +88,7 @@ module when interoperating with ordinary JSON APIs, browsers, logs, or other JSO
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/docs/start/python.md b/docs/start/python.md
index e3a6e9aeae6..3c78c88275b 100644
--- a/docs/start/python.md
+++ b/docs/start/python.md
@@ -35,7 +35,7 @@ python -m pip --version
Install the released package:
```bash
-python -m pip install pyfory==1.7.6
+python -m pip install pyfory==1.7.7
```
Run an xlang round trip:
diff --git a/docs/start/rust.md b/docs/start/rust.md
index 4792e80b6e0..85c2ff62ebc 100644
--- a/docs/start/rust.md
+++ b/docs/start/rust.md
@@ -36,7 +36,7 @@ Add the public crate:
```toml title="Cargo.toml"
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
```rust
diff --git a/docs/start/scala.md b/docs/start/scala.md
index 2048de39a8d..5e785a0f501 100644
--- a/docs/start/scala.md
+++ b/docs/start/scala.md
@@ -37,7 +37,7 @@ Add the Fory Scala library to `build.sbt`:
```sbt
ThisBuild / scalaVersion := "3.3.1"
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
Create `src/main/scala/ScalaExample.scala`:
diff --git a/docs/start/swift.md b/docs/start/swift.md
index b72a56862a5..97885c8868a 100644
--- a/docs/start/swift.md
+++ b/docs/start/swift.md
@@ -42,7 +42,7 @@ Add the released package and depend on its `Fory` library in the generated `Pack
```swift title="Package.swift"
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "1.7.6")
+ .package(url: "https://github.com/apache/fory.git", exact: "1.7.7")
],
targets: [
.executableTarget(
diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2026-10-12-fory_1_7_7_released.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-10-12-fory_1_7_7_released.md
new file mode 100644
index 00000000000..c04440ef93b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2026-10-12-fory_1_7_7_released.md
@@ -0,0 +1,62 @@
+---
+slug: fory_1_7_7_release
+title: Fory v1.7.7 发布
+description: "Fory 1.7.7 新增可配置的 JSON null 处理，并修复对象映射、Schema 编译器输出和发布归档的可复现性。"
+authors: [chaokunyang]
+tags: [fory, java, json, kotlin, scala]
+---
+
+Apache Fory 1.7.7 已发布。本次发布新增读取端 JSON null 处理，改进序列化性能、对象映射和生成代码。
+安装方式请参阅[快速开始](/zh-CN/docs/start/)。
+
+## 主要更新
+
+- 配置 JSON 读取器对 null 属性、集合元素和 Map 值的处理方式。
+- 降低 JSON 编解码器的生成成本，改进字符串写入，减少 C++ 序列化开销。
+- 修复 JSON 对象字段语义、兼容模式下的字段类型校验和 Schema 编译器输出。
+- 使 Java 和 Kotlin 发布归档可复现，并改进许可证和 NOTICE 打包。
+
+## JSON null 处理
+
+`onNullRead` 控制显式 null 属性值，`onContentNullRead` 控制数组或集合中的 null 元素以及 Map 中的
+null 值。两者默认均为 `SET`，保留既有解码行为。`SKIP` 跳过该次输入；`FAIL` 拒绝它。
+
+```java
+import org.apache.fory.json.ForyJson;
+import org.apache.fory.json.annotation.JsonProperty;
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+public final class Response {
+ @JsonProperty(onNullRead = NullHandling.SKIP, onContentNullRead = NullHandling.SKIP)
+ public java.util.List<String> seats = java.util.List.of("default");
+}
+
+ForyJson json = ForyJson.builder().build();
+Response first = json.fromJson("{\"seats\":null}", Response.class);
+Response second = json.fromJson("{\"seats\":[null,\"a\"]}", Response.class);
+// first.seats is ["default"]; second.seats is ["a"].
+```
+
+也可以在 builder 上配置这些选项。属性注解覆盖对应的全局设置。内容覆盖仅影响直接元素或值；
+嵌套容器遵循适用于自身的设置。这些选项只处理显式 JSON null，不改变写入或根值的 null 行为。
+
+Kotlin 和 Scala 的 JSON builder 同样支持这些设置。跳过 null 属性可以保留构造函数默认值，
+但必需属性校验仍然生效。详细规则见[读取端 null 处理](/zh-CN/docs/json/annotations#read-side-null-handling)、
+[Kotlin](/zh-CN/docs/json/kotlin/) 和 [Scala](/zh-CN/docs/json/scala/)。
+
+## 正确性与性能
+
+JSON 对象映射现在会恢复符合条件的普通 final 字段；子类字段隐藏父类同名字段时，读写均选择子类字段。
+通过具体基类类型写入子类实例时，会包含子类的映射属性；读取时若要恢复子类型，仍需声明子类型映射或
+提供自定义编解码器。详见[对象映射](/zh-CN/docs/json/object-mapping/)。
+
+Schema 编译器修复覆盖 Java、Kotlin、Scala、Python 和 TypeScript 输出。当 Schema case 名为
+`Unknown` 或 Swift 的 `unknown` 时，生成的未知 case 载体会采用备用名称，保留 Schema case 名称。
+详见[生成代码](/zh-CN/docs/compiler/generated-code/)。
+
+性能改进降低了 JSON 编解码器生成成本，避免对 final 属性类型进行不必要的 `NON_EMPTY` 检查，
+改进含转义字符的字符串写入，并在序列化 C++ `std::forward_list` 时避免创建临时 vector。
+
+完整发布说明见 [GitHub](https://github.com/apache/fory/releases/tag/v1.7.7)。
+
+**完整变更记录**：[v1.7.6...v1.7.7](https://github.com/apache/fory/compare/v1.7.6...v1.7.7)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/build-integration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/build-integration.md
index 2783e7ab30f..48daf968b6d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/build-integration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/build-integration.md
@@ -211,7 +211,7 @@ cc_library(
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/cli.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/cli.md
index 9dc3def02ba..b4d2d9a2208 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/cli.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/cli.md
@@ -659,5 +659,5 @@ fory = "x.y.z"
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/csharp.md
index 6a80683fc31..9da227ff2c1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/csharp.md
@@ -51,7 +51,8 @@ public sealed partial class Person
`[ForyUnknownCase]` 标记。该标记只选择载体，不会向 Schema case 表添加条目。Schema
定义的 case 使用非负 `[ForyCase]` ID。如果 case 需要非默认 Schema 编码，生成的
`[ForyCase]` 会携带 `Type`。已知 case record 名称采用 PascalCase FDL case 名称；需要
-避免名称冲突时，载荷类型生成为限定引用。类型化联合必须至少包含一个非 `Unknown` case。
+避免名称冲突时，载荷类型生成为限定引用。类型化联合必须至少包含一个 Schema 定义的 case。
+名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
```csharp
[ForyUnion]
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/index.md
index 1af56c7e1b0..4e1374e20f8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/index.md
@@ -28,6 +28,13 @@ Fory IDL 生成的类型遵循宿主语言习惯，可以直接用作领域对
`ComplexPbForyModule` 等名称允许多个 IDL 文件指向同一个包或命名空间，而不会生成
冲突的 `ForyModule` 类型。
+## 未知联合 case 的名称 {#unknown-union-case-names}
+
+C#、Kotlin、Scala 和 Rust 生成 `Unknown` case 来保留未知联合值；Swift 使用 `unknown`。
+Schema 定义的 case 保持各语言的常规名称形式。如果生成的载体名称冲突，编译器使用
+`Unknown_`，Swift 则使用 `unknown_`。如果备用名称也已被占用，生成会失败。
+未知 case 注解或属性用于标识载体，不要求载体必须名为 `Unknown` 或 `unknown`。
+
## 参考 Schema
以下示例使用两个真实 Schema：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/kotlin.md
index dfba66192e6..eaefda1ba5b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/kotlin.md
@@ -61,6 +61,8 @@ public data class Person(
}
```
+空消息生成具有无参构造函数的普通类。
+
参与编译器检测到的构造环的消息会生成普通可变类，使生成的序列化器能够在读取反向引用前
发布实例：
@@ -82,7 +84,8 @@ public class Node() {
枚举生成具有稳定 Fory 枚举 ID 的 Kotlin 枚举类。联合生成带 `@ForyUnion` 的密封类；Fory
提供的 `Unknown(UnknownCase)` 载体使用 `@ForyUnknownCase` 标记。该标记只选择载体，不会
向 Schema case 表添加条目。Schema 定义的 case 可以使用 case ID `0..N`，并保存一个
-`value` 属性。类型化联合必须至少包含一个非 `Unknown` case。
+`value` 属性。类型化联合必须至少包含一个 Schema 定义的 case。名称冲突时，生成的载体名为
+`Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
```kotlin
package addressbook
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/python.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/python.md
index 441e2dbdbdd..f8110f159b4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/python.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/python.md
@@ -70,6 +70,14 @@ class Person:
def from_bytes(cls, data: bytes) -> "Person": ...
```
+## 字段名称 {#field-names}
+
+生成的 Python 属性使用 `snake_case`，Python 关键字会增加尾部下划线。
+`field`、`pyfory`、`decimal`、`list` 和 `dict` 也会增加尾部下划线。
+由这五个名称之一加下划线组成的名称会再增加一个下划线，确保字段彼此不同：
+`field`、`field_` 和 `field__` 分别变为 `field_`、`field__` 和 `field___`。
+字段 tag ID 保持不变。
+
## 注册
生成的注册函数：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/rust.md
index 19087a1982e..e8c8a93171e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/rust.md
@@ -35,8 +35,9 @@ Rust 输出为每个 Schema 生成一个模块文件，例如：
联合映射到带 `#[fory(id = ...)]` Schema case 属性的 Rust 枚举。
`#[fory(unknown)] Unknown(::fory::UnknownCase)` 标记 Fory 提供的向前兼容载体。该标记
只选择载体，不会向 Schema case 表添加条目；Schema case 仍使用完整的 `0..N` ID 范围。
-生成的类型化联合必须至少包含一个非 `Unknown` case。编译器将第一个声明的非 `Unknown`
-case 标记为 `#[fory(default)]`。当该 case 的载荷实现 Rust 标准 `Default` trait 时，编译器
+名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
+生成的类型化联合必须至少包含一个 Schema 定义的 case。编译器将第一个声明的 Schema case
+标记为 `#[fory(default)]`。当该 case 的载荷实现 Rust 标准 `Default` trait 时，编译器
还会从该 case 生成标准 `Default` 实现：
```rust
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/scala.md
index e1370859175..f055a9facdf 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/scala.md
@@ -96,7 +96,8 @@ enum PhoneType {
联合生成 Scala 3 ADT 枚举。`Unknown(UnknownCase)` 是 Fory 提供的向前兼容载体，使用
`@ForyUnknownCase` 标记。它不会出现在 Schema case 表中，因为该标记只选择载体，不会
添加 Schema 条目。Schema 定义的 case 使用非负 `@ForyCase` ID。类型化联合必须至少
-包含一个非 `Unknown` case。
+包含一个 Schema 定义的 case。名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，
+则会报错。Schema case 名称保持不变。
```scala
package addressbook
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/swift.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/swift.md
index 673083d0889..1df881d500a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/swift.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/compiler/generated-code/swift.md
@@ -27,10 +27,10 @@ Swift 输出为每个 Schema 生成一个 `.swift` 文件，例如：
## 类型生成
-生成器使用拆分模型宏和稳定字段/case ID 创建 Swift 模型。类型化联合必须包含
-`@ForyUnknownCase case unknown(UnknownCase)` 和至少一个非 `unknown` case；
-`unknown(UnknownCase)` 只是 Fory 提供的向前兼容载体。该标记只选择载体，不会向 Schema
-case 表添加条目。
+生成器使用拆分模型宏和稳定字段/case ID 创建 Swift 模型。类型化联合必须包含一个带
+`@ForyUnknownCase` 标记的 case 和至少一个 Schema 定义的 case；`unknown(UnknownCase)`
+是 Fory 提供的向前兼容载体的默认名称。该标记只选择载体，不会向 Schema case 表添加条目。
+名称冲突时，生成的载体名为 `unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
当包/命名空间非空时，命名空间形状由 `swift_namespace_style` 控制：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/csharp.md
index 9a4a24a4706..ca6c3a34748 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/csharp.md
@@ -36,7 +36,7 @@ gRPC 客户端、服务基类、方法描述符、元数据、截止时间、取
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.AspNetCore" Version="2.71.0" />
</ItemGroup>
```
@@ -45,7 +45,7 @@ gRPC 客户端、服务基类、方法描述符、元数据、截止时间、取
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.Core.Api" Version="2.71.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.71.0" />
</ItemGroup>
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/dart.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/dart.md
index dce964090b5..b89506e2b36 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/dart.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/dart.md
@@ -29,7 +29,7 @@ license: |
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
grpc: ^4.0.0
dev_dependencies:
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/rust.md
index 628db9b23ab..6573496f887 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/rust.md
@@ -29,7 +29,7 @@ license: |
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
bytes = "1"
tonic = { version = "0.14", features = ["transport"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/annotations.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/annotations.md
index fd19052e19f..1f146198fc3 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/annotations.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/annotations.md
@@ -96,7 +96,7 @@ Mixin 提供的 `JsonCodec` 会成为目标的有效注解。精确的 `register
## `JsonProperty`
-`JsonProperty` 配置一个完整逻辑属性的规范名称、序列化索引和值包含策略。字段、getter 或 setter
+`JsonProperty` 配置一个完整逻辑属性的规范名称、序列化索引、写入包含策略和读取端 null 处理。字段、getter 或 setter
上的注解会应用于合并后的字段/getter/setter 属性组。
```java
@@ -166,6 +166,51 @@ Scala 的字段缺失行为见 [case class 与注解](scala.md#case-classes-and-
不支持别名以及相互独立的读写名称。`JsonProperty` 不能与 Any 逻辑属性组合，
也不能声明在 `JsonAnySetter` 上。
+### 读取端 null 处理 {#read-side-null-handling}
+
+`onNullRead` 控制赋给属性的显式 JSON null。`onContentNullRead` 控制属性的数组或集合中的
+null 元素，以及 Map 中的 null 值。两者均使用 `JsonProperty.NullHandling`：
+
+| 值 | 行为 |
+| --------- | ---------------------------------------------------------------- |
+| `DEFAULT` | 继承对应的 builder 设置。这是注解默认值。 |
+| `SET` | 按常规规则解码和赋值，包括声明的可空性规则。 |
+| `SKIP` | 消费 null，并省略此次赋值、元素或 Map 插入。 |
+| `FAIL` | 遇到显式 null 时抛出 `ForyJsonException`。此设置仍允许属性缺失。 |
+
+两个 builder 设置均默认为 `SET`。显式注解值仅覆盖对应的默认设置：
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+public final class Response {
+ @JsonProperty(onNullRead = NullHandling.SKIP, onContentNullRead = NullHandling.SKIP)
+ public java.util.List<String> seats = java.util.List.of("default");
+}
+```
+
+读取 `{"seats":null}` 会保留初始化的列表。读取 `{"seats":[null,"a"]}` 会赋值为只含 `"a"` 的列表；
+`[null]` 会赋值为空列表。跳过属性不会调用其 setter。构造函数参数遵循原有的缺失属性默认值和
+必需属性校验。跳过重复成员不会清除较早的值：`{"seats":["a"],"seats":null}` 会保留 `"a"`。
+绕过构造函数创建的对象没有可保留的初始化值。
+
+`SET` 保留编解码器行为：null 可能变为 `Optional.empty()`，也可能因基本类型或 Kotlin 非空值而失败。
+`SKIP` 和 `FAIL` 在这种解码之前生效。仅处理字面量 JSON null；字符串 `"null"` 以及自定义编解码器
+处理其他 token 后返回的 Java null 不会被过滤。这些选项不影响写入，也不改变根值的 null 行为。
+
+内容覆盖仅作用于一层。对于 `List<List<String>>`，属性覆盖会跳过 null 内层列表；保留下来的列表内部
+元素遵循全局设置。Map 键不受影响，跳过重复键的 null 值会保留较早的条目。
+数字形式的字节数组支持内容处理，Base64 和 Base16 字符串不支持。在标量、声明为 `Object` 的值、
+透明包装或编码后的二进制字符串上显式指定内容设置是无效的。
+
+全局内容设置也适用于根容器、动态 JSON 数组或对象以及 Any 条目。不能在展开的父属性上显式指定
+null 设置；展开后的子属性保留各自的设置。仅遇到被跳过的子属性不会创建该组或将该组标记为已提供。
+
+匹配的字段、getter、setter 和创建器声明按每个设置独立合并。相互冲突的显式值会被拒绝，
+读取端设置要求属性可读或存在创建器参数。Mixin 替换和移除在合并之前执行。
+完整的自定义容器编解码器支持显式 `SET`；显式内容 `SKIP` 或 `FAIL` 要求容器表示由 Fory 负责。
+见[自定义编解码器](custom-codecs.md)。
+
## `JsonInclude` 与默认值省略 {#jsoninclude-and-default-omission}
默认值可能依赖构造函数参数、时间、随机数或外部状态。能够求值并不意味着省略后能恢复相同的值。
@@ -220,7 +265,7 @@ Fory 不证明纯度或分析默认值表达式。Scala 依赖式默认值方法
基本类型按值比较。浮点数区分正零和负零，非有限值保留并按常规方式输出。数组比较精确的数组类型与内容，
嵌套数组递归比较；其他引用使用 `equals`。不支持循环结构的深度比较。
-读取行为独立：显式 null 不等于缺失，可变参考默认值不会与解码对象共享。
+读取行为独立：在 `onNullRead(SET)` 下，显式 null 不等于缺失，可变参考默认值不会与解码对象共享。
可以通过已有 Mixin 机制授权默认值，而不修改模型：
@@ -551,7 +596,7 @@ public final class Name {
会应用于每个子属性经 `JsonProperty` 和已配置命名策略处理后的最终 JSON 名称。嵌套展开属性会从内向外
组合这些转换。
-null 子对象不会写入任何成员。读取时，Fory 只有在遇到至少一个展开成员后才会创建并赋值该子对象。
+null 子对象不会写入任何成员。读取时，Fory 只有在遇到至少一个值未被跳过的展开成员后才会创建并赋值该子对象。
因此，完全缺失的属性组会保留可变父对象的初始化值；Record 或创建器参数则保持常规的缺失属性默认值。
对于部分输入，子对象的其他属性使用普通默认值完成构造。
@@ -600,7 +645,7 @@ import org.apache.fory.json.annotation.JsonIgnore;
public Map<String, Object> outputOnly;
```
-读取时会复用现有 Map。非 final 的 null 字段会在遇到第一个未知成员时初始化。普通可变对象上的可读 final
+读取时会复用现有 Map。非 final 的 null 字段会在遇到第一个值未被跳过的未知成员时初始化。普通可变对象上的可读 final
字段必须已经包含可变 Map。Record 和属性列表形式的 `JsonCreator` 类型则通过构造参数接收累计得到的 Map。
如果不存在未知成员，Fory 不会初始化 null 字段。
@@ -700,8 +745,8 @@ public static User create(
创建器必须至少有一个参数，且不能使用可变参数或泛型。构造函数必须是 public。工厂方法必须是 public
且 static，其精确返回类型必须声明为目标类，并返回非 null 值，且该值的运行时类必须恰好是目标类。
-缺失的引用参数使用 null，缺失的基本类型参数使用 Java 零值，重复成员采用最后一个值；基本类型参数若
-显式接收 null 则会被拒绝。Record 不能声明基于属性的 `JsonCreator`；带有 `JsonValue` 的 Record 可以在
+缺失的引用参数使用 null，缺失的基本类型参数使用 Java 零值。重复成员采用最后一个未被跳过的值；
+在 `onNullRead(SET)` 下，基本类型参数显式接收 null 会被拒绝。Record 不能声明基于属性的 `JsonCreator`；带有 `JsonValue` 的 Record 可以在
其单 String 参数的规范构造函数上标注值形式。
## `JsonValidator`
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/custom-codecs.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/custom-codecs.md
index 620dc6445dd..808ed521061 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/custom-codecs.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/custom-codecs.md
@@ -101,6 +101,9 @@ ForyJson json =
.build();
```
+声明的数组、集合和 Map 中的 `Object` 元素或值也会查询工厂。工厂接管 `Object` 时，会替换这些位置
+默认的自然 JSON 值映射。
+
可配置工厂必须重写 `factoryKey()`，返回一个确定性值，覆盖所有可能改变生成编解码器类、对象模型或生成操作的选项。默认的工厂类名仅适用于无配置工厂。
仅当工厂在动态写入期间为值的实际类选择编解码器时，`runtimeType` 才为 `true`；声明的根类型和复合子类型收到的是 `false`。复合编解码器如果在构造后仍需此区分，必须保留该标志供后续 `resolveTypes` 调用使用，不能从 resolver 状态推断。
@@ -109,7 +112,14 @@ ForyJson json =
就不会调用编解码器的写入操作。`NON_EMPTY` 直接检查 Java 空值类型，
其他类型使用编解码器的 `isEmpty` 方法；见[自定义空值](#custom-empty-values)。
如果属性会被输出，或者该值是数组元素、集合元素、Map 值、Optional 值或原子引用值，
-编解码器就会接收并负责处理 null。注册的实例会在并发操作之间共享，因此必须是线程安全的。
+写入时编解码器会接收并负责处理 null。读取时，适用设置为 `SET` 时由编解码器负责 null。
+属性的 `onNullRead` 和 Fory 容器的 `onContentNullRead` 配置为 `SKIP` 或 `FAIL` 时，
+会在调用选定的子编解码器之前处理字面量 null。编解码器消费非 null token 后返回的 Java null 不会被过滤。
+注册的实例会在并发操作之间共享，因此必须是线程安全的。
+
+完整的自定义容器编解码器负责其内部表示，全局内容设置不会改变它。对于这样的声明容器属性，
+显式内容 `SET` 委托给编解码器；显式 `SKIP` 或 `FAIL` 会被拒绝。完整的自定义对象编解码器
+同样负责其内部属性处理。普通外围属性设置仍在调用这两种完整编解码器之前生效。
会物化复合对象图所有者的自定义编解码器，在创建每个所有者之前，必须使用应用定义的字节估算值
调用 `JsonReader.reserveGraphMemory`。这适用于复合应用对象、集合、Map 和引用数组。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/getting-started.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/getting-started.md
index fb10ce0f387..90b744b41dc 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/getting-started.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/getting-started.md
@@ -41,7 +41,7 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-json</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -55,7 +55,7 @@ repositories {
mavenCentral()
}
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
### Kotlin
@@ -64,7 +64,7 @@ Kotlin/JVM 应用添加可选的 Kotlin JSON 运行时，并使用其统一 buil
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/kotlin.md
index 7d07777f0c5..b9a958d102c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/kotlin.md
@@ -38,7 +38,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
@@ -50,7 +50,7 @@ plugins {
}
dependencies {
- ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.6")
+ ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.7")
}
```
@@ -134,12 +134,18 @@ data class Request(
主构造函数会被自动选择。公共次构造函数或目标类型自身的公共静态工厂，只有经 `JsonCreator` 显式选择后才会使用；伴生对象工厂必须通过外层类中实际存在的 `@JvmStatic` 桥接方法才符合条件。`@JvmOverloads` 生成的方法不是独立 creator 候选，选定的静态工厂也不能含编译器默认参数。私有/受保护、可变参数、方法泛型、上下文参数、局部类、匿名类、`inner` 类或合成构造路径需要精确的应用编解码器。
-对于这个模型：
+使用默认的 `onNullRead(SET)` 时，这个模型的行为如下：
- `{"id":1}` 会调用两个编译器默认值。
- `{"id":1,"label":null}` 会传入显式 null，不调用 `label` 的默认值。
- 缺少 `id` 使用 `0`。
-- `{"id":1,"retries":null}` 会失败；null 不会要求 Kotlin 使用默认值。
+- `{"id":1,"retries":null}` 会失败。
+
+使用 `ForyJsonKotlin.builder().onNullRead(JsonProperty.NullHandling.SKIP)` 可将一次 null 输入视为缺失，
+保留构造函数默认值和类体属性初始化值。没有默认值的非空引用仍是必需属性。
+使用 `@get:JsonProperty(onNullRead = JsonProperty.NullHandling.SET)` 可让单个属性保留常规 null 解码。
+`onContentNullRead` 处理直接的集合或数组元素以及 Map 值，包括无符号数组。
+属性覆盖仅作用于一层，跳过 null 发生在元素可空性检查之前。见[读取端 null 处理](annotations.md#read-side-null-handling)。
启用 `ForyJsonKotlin.builder().failOnMissingRequiredProperties(true).build()` 后，未声明默认值的普通
构造函数属性必须出现在输入中，包括可空属性、数值属性和 Boolean 属性。已声明的编译器默认值仍然生效。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/object-mapping.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/object-mapping.md
index 7e61f960a30..963619d8fee 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/object-mapping.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/object-mapping.md
@@ -54,8 +54,12 @@ ForyJson json =
static、transient、synthetic 和 `Class<?>` 字段会被排除。`getClass()` 以及值类型为 `Class<?>`
的访问器也会被排除。在不符合条件的成员上放置注解会直接报错，而不是被静默忽略。
-普通 final 字段可以写出，但不会作为反序列化时的可变写入目标。不可变对象应使用 record、
-`JsonCreator` 或自定义编解码器来构造。
+读取 JSON 时会恢复符合条件的实例字段，包括普通 `final` 字段。子类字段隐藏父类同名字段时，
+读写两个方向均以子类字段作为 JSON 属性。忽略该字段不会暴露被隐藏的父类字段。
+
+普通对象属性在读取时使用声明类型。通过具体的声明基类类型写入子类实例时，Fory 会写出子类的
+映射属性。通过基类类型读取相同 JSON 时，会创建基类实例并忽略子类独有的属性。
+读取器需要恢复子类型时，应使用 `@JsonSubTypes` 或自定义编解码器。
### 字段模式
@@ -104,7 +108,8 @@ ForyJson json = ForyJson.builder()
未声明默认值的普通属性必须出现在输入中，不再自动填充零、false 或 null。此选项不会引入新的容器默认值：
没有默认值的 Kotlin 非空集合仍为必需属性，而 Scala 集合保留现有的空集合默认值。
-显式 JSON null 视为已提供的属性值，继续遵循属性的类型和可空性规则。被忽略的属性、普通无参 Java Bean
+使用默认的 `onNullRead(SET)` 时，显式 JSON null 视为已提供的属性值，并遵循属性的类型和可空性规则。
+使用 `SKIP` 时，该次输入被省略，不能满足必需参数要求。被忽略的属性、普通无参 Java Bean
以及构造后赋值的属性保持原有行为。完整的自定义对象编解码器自行负责缺失字段规则。
此选项不改变写入。如果包含策略省略了必需属性，生成的 JSON 可能被严格读取器拒绝。应在输出中保留该属性，
@@ -112,10 +117,30 @@ ForyJson json = ForyJson.builder()
## Kotlin 对象映射 {#kotlin-object-mapping}
-为 Kotlin/JVM 类安装 `fory-json-kotlin` 并使用 `ForyJsonKotlin.builder()`。Kotlin 普通类和 data class 使用选定的构造函数、精确属性类型、编译器默认值和声明的可空性，不使用 Java 绕过构造函数的回退路径。默认值仅在成员缺失时生效。显式 JSON null 仍是已提供的值，非空参数会拒绝它。
+为 Kotlin/JVM 类安装 `fory-json-kotlin` 并使用 `ForyJsonKotlin.builder()`。Kotlin 普通类和 data class 使用选定的构造函数、精确属性类型、编译器默认值和声明的可空性，不使用 Java 绕过构造函数的回退路径。成员缺失或其 null 输入被跳过时使用默认值。默认情况下，显式 JSON null 是已提供的值，非空参数会拒绝它。
泛型、可空、无符号和值类根类型应使用 `jsonTypeRef<T>()`。标准数组、集合和 Map 继续使用常规 Fory JSON 表示。完整语言类型表、单例/值类行为和省略规则见 [Kotlin 指南](kotlin.md)。
+## 读取端 null 处理 {#read-side-null-handling}
+
+使用独立的 builder 设置可保留已有属性值，并省略 null 容器项：
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+ForyJson json = ForyJson.builder()
+ .onNullRead(NullHandling.SKIP)
+ .onContentNullRead(NullHandling.SKIP)
+ .build();
+```
+
+两者均默认为 `SET`。`FAIL` 拒绝显式 null；`SKIP` 省略该次输入。
+builder 只接受具体模式，不接受 `DEFAULT` 或 Java null。每个构建的实例保留自己的配置。
+使用 `@JsonProperty(onNullRead = SET)` 或 `onContentNullRead = SET` 可让单个属性不受对应全局规则影响。
+内容设置覆盖直接的集合或数组元素以及 Map 值，包括根容器和动态 JSON 树。
+属性设置作用于带类型的对象属性，包括嵌套对象，但不改变根 `null` 值。
+见[注解语义与示例](annotations.md#read-side-null-handling)。
+
## 支持的 Java 类型 {#supported-java-types}
下列类型组具有内置映射。具体编码表示形式都是稳定的 JSON 值，但在精度或构造方式很重要时，应用
@@ -231,6 +256,8 @@ builder 接受 `ALWAYS`、`NON_NULL` 和 `NON_EMPTY`，拒绝 `DEFAULT` 和 `NON
| `byteArrayFormat(JsonByteArray.Format)` | `BASE64` | 字节数组读写的默认表示方式 |
| `withCodegen(boolean)` | `true` | 启用生成的对象编解码器 |
| `withAsyncCompilation(boolean)` | `true` | 异步编译生成的编解码器 |
+| `onNullRead(NullHandling)` | `SET` | 处理显式 null 属性值 |
+| `onContentNullRead(NullHandling)` | `SET` | 处理数组或集合中的 null 元素以及 Map 中的 null 值 |
| `withFieldMode(boolean)` | `false` | 为 true 时，仅发现字段而不使用 getter/setter |
| `withPropertyNamingStrategy(strategy)` | `LOWER_CAMEL_CASE` | 为未显式指定 `JsonProperty` 名称的属性命名 |
| `withMaxCachedFieldNames(int)` | `DEFAULT_MAX_CACHED_FIELD_NAMES` (`8192`) | 每个 reader 的字段名缓存条目数；零表示禁用缓存 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/scala.md
index 9bc86c5aeb3..480290534a1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/json/scala.md
@@ -24,7 +24,7 @@ Fory JSON 通过可选的 `fory-json-scala` 制品支持 Scala 2.13 和 Scala 3
## 设置 {#setup}
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.7"
```
`ForyJsonScala.builder()` 安装 Scala 模块并返回标准 Fory JSON builder：
@@ -93,9 +93,14 @@ json.fromJson("{}", classOf[Profile]) // Profile(0, false, List(), null)
`case class Request(id: Int = 7)` 仍将它读取为 `Request(7)`。Option、集合、Map 和数组属性保留现有的
缺失值默认规则。此选项默认关闭，不改变写入或显式 null 的处理。
-显式构造函数默认值优先用于缺失的属性。显式 JSON `null` 对 `Option[A]` 解码为 `None`，
+显式构造函数默认值优先用于缺失的属性。使用默认的 `onNullRead(SET)` 时，JSON `null` 对 `Option[A]` 解码为 `None`，
即使其构造函数默认值为 `Some(...)` 也是如此。
+使用 `ForyJsonScala.builder().onNullRead(JsonProperty.NullHandling.SKIP)` 可跳过 null 属性输入，
+保留构造函数默认值或类体属性初始化值。`onContentNullRead` 适用于受支持的严格求值 Scala 集合
+中的直接元素和 Map 值，包括基本类型集合。逐属性的 `JsonProperty` 设置覆盖对应的全局默认值，
+不会传播到嵌套容器。见[读取端 null 处理](annotations.md#read-side-null-handling)。
+
case class 可以声明在顶层，也可以嵌套在任意层数的 `object` 内，但每一层外部作用域都必须是 `object`。如果外层是 `class`、trait 或方法，读写都会被拒绝，因为 Fory 无法访问重建值所需的外部实例或伴生对象。
构造要求具有公共 JVM 构造函数以及匹配的公共伴生对象 `apply`；不支持的私有构造形式会被拒绝。
@@ -115,7 +120,7 @@ case class Media(
`JsonIgnore` 适用于字段、属性方法、setter 参数和选定的构造函数参数。`JsonCodec` 子槽位绑定直接集合元素、`Option` 内容，以及 Map 键或值。其他 Fory JSON 注解保持[注解](annotations.md)中描述的行为。
属性包含策略控制写出的值。省略的属性在读取时使用构造函数或类型默认值，因此省略空字符串可能恢复为 `null`。
-如果需要保留区别，使用 `ALWAYS`。显式 JSON `null` 保持声明类型的常规 null 行为，不会请求构造函数默认值。
+如果需要保留区别，使用 `ALWAYS`。在 `onNullRead(SET)` 下，JSON `null` 保持声明类型的常规 null 行为，不会请求构造函数默认值。
`NON_EMPTY` 识别 `None` 和受支持的空严格求值 Scala 序列、集合、Map，包括可变集合和 range。
过滤不递归：`Some("")`、`Some(Nil)`、`Some(null)` 和非空容器都会保留。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/cpp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/cpp/index.md
index 027a2eaf121..696e77b98d4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/cpp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/cpp/index.md
@@ -60,7 +60,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -90,11 +90,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v1.7.6", # Or use a specific commit hash for reproducibility
+ commit = "v1.7.7", # Or use a specific commit hash for reproducibility
)
```
@@ -125,7 +125,7 @@ bazel run //:my_app
本地开发时，可以改用 `local_path_override`：
```bazel
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/index.md
index 94cbfa1d5c3..a7b101ebb80 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/index.md
@@ -44,7 +44,7 @@ Apache Fory™ C# 是面向 .NET 的高性能跨语言序列化库。它支持
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
</ItemGroup>
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/schema-metadata.md
index 366019499be..9db0d9bf4e2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/csharp/schema-metadata.md
@@ -105,7 +105,7 @@ Schema 描述符位于 `Apache.Fory.Schema.Types` 下，仅作为元数据使用
## `[ForyUnion]` 和 `[ForyCase]`
-生成的 union case 使用 `[ForyCase]` 同时指定稳定 case ID 和可选的 case 载荷 Schema 类型。不要在 union case 载荷成员上添加 `[ForyField]`。已知 case 的 record 名称使用 PascalCase FDL case 名称；需要避免名称冲突时，载荷类型使用限定引用。类型化 union 必须声明至少一个非 `Unknown` case；`Unknown(UnknownCase)` 只是 Fory 提供的向前兼容载体。该标记只选择载体，不会在 Schema case 表中增加条目。
+生成的 union case 使用 `[ForyCase]` 同时指定稳定 case ID 和可选的 case 载荷 Schema 类型。不要在 union case 载荷成员上添加 `[ForyField]`。已知 case 的 record 名称使用 PascalCase FDL case 名称；需要避免名称冲突时，载荷类型使用限定引用。类型化 union 必须声明至少一个 Schema 定义的 case，以及恰好一个暴露 `Value: UnknownCase` 的 `[ForyUnknownCase]` case。载体名称不受限制。该标记只选择载体，不会在 Schema case 表中增加条目。
```csharp
using Apache.Fory;
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/dart/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/dart/index.md
index 5666763a43f..a790cbc1d4d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/dart/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/dart/index.md
@@ -44,7 +44,7 @@ Apache Fory™ Dart 可以将 Dart 对象序列化为字节并反序列化，也
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md
index 368686e637a..8e6ddae8c78 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md
@@ -51,7 +51,7 @@ Fory core 支持 Java 8 及更高版本。Java Record 序列化需要 Java 17
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -59,7 +59,7 @@ Fory core 支持 Java 8 及更高版本。Java Record 序列化需要 Java 17
```kotlin
// Binary object serialization
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
#### JDK 25 及更高版本
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/index.md
index aa2a007acce..b6e6583aa1e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/index.md
@@ -53,14 +53,14 @@ Fory Kotlin 继承了 Fory Java 的全部功能，并增加了 Kotlin 特有优
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:1.7.6")
+implementation("org.apache.fory:fory-kotlin:1.7.7")
```
### JDK25+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/static-generated-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/static-generated-serializers.md
index 99235d11bb5..d201040d0e0 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/static-generated-serializers.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/kotlin/static-generated-serializers.md
@@ -198,7 +198,8 @@ KSP 会为带 `@ForyUnion` 注解的顶层密封类生成序列化器。每个 S
`@ForyCase` 注解的嵌套类，并包含一个名为 `value` 的构造函数属性。
`Unknown(UnknownCase)` 使用 `@ForyUnknownCase` 标记，作为 Fory 管理的向前兼容载体。
它不会出现在 Schema case 表中，因为该标记只选择载体，不会添加 Schema 条目。类型化
-联合必须声明至少一个非 `Unknown` case：
+联合必须声明至少一个 Schema 定义的 case。恰好一个 case 必须带有 `@ForyUnknownCase`，
+其名称不受限制：
```kotlin
package example
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/basic-serialization.md
index 78484d7bd94..a2b8921b67f 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/basic-serialization.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/basic-serialization.md
@@ -145,7 +145,7 @@ Rust 启用 `chrono::NaiveDate`、`chrono::NaiveDateTime` 和 `chrono::Duration`
```toml
[dependencies]
-fory = { version = "1.7.6", features = ["chrono"] }
+fory = { version = "1.7.7", features = ["chrono"] }
```
### 自定义类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/index.md
index f567af4ffae..6cfbd1f1b8a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/rust/index.md
@@ -36,9 +36,9 @@ Rust 实现通过自动内存管理和编译期类型安全提供灵活的高性
| Crate | 说明 | 版本 |
| --------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------- |
-| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 面向用户的 API、运行时类型和派生宏 | [1.7.6](https://crates.io/crates/fory) |
-| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 用于高级集成的底层运行时 crate | [1.7.6](https://crates.io/crates/fory-core) |
-| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 供直接使用运行时的底层过程宏 crate | [1.7.6](https://crates.io/crates/fory-derive) |
+| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 面向用户的 API、运行时类型和派生宏 | [1.7.7](https://crates.io/crates/fory) |
+| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 用于高级集成的底层运行时 crate | [1.7.7](https://crates.io/crates/fory-core) |
+| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 供直接使用运行时的底层过程宏 crate | [1.7.7](https://crates.io/crates/fory-derive) |
大多数应用程序只需依赖 `fory`。它重新导出生成代码所需的派生宏和公共运行时类型。只有明确要基于底层运行时 crate 构建时，才直接使用 `fory-core` 或 `fory-derive`。
@@ -48,7 +48,7 @@ Rust 实现通过自动内存管理和编译期类型安全提供灵活的高性
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
### 基本示例
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/basic-serialization.md
index 649012fd038..a13a65137be 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/basic-serialization.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/basic-serialization.md
@@ -151,8 +151,8 @@ enum SearchTarget derives ForySerializer {
名称，并使用限定名表示载荷类型。如果目标输出模式无法为冲突表达合法限定名，IDL
编译器会在生成的 case 名称后追加 `Case`。
-Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个非 `Unknown` case。
-Scala 未知 case 载体由 `@ForyUnknownCase` 选择，而不是由 Schema case ID 选择。其载荷
+Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个 Schema 定义的 case。
+Scala 未知 case 载体由 `@ForyUnknownCase` 选择，与其名称无关，且没有 Schema case ID。其载荷
存储原始 case ID 和反序列化后的值。当读取端遇到较新的 case ID 时，会返回
`Unknown(UnknownCase)`，而不会仅仅因为本地不知道该 case ID 就失败。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/index.md
index 9e09acdb161..44fdada1980 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/index.md
@@ -49,7 +49,7 @@ Fory Scala 继承了 Fory Java 的全部功能，并增加了 Scala 特有优化
使用 sbt 添加依赖：
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
### JDK25+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/schema-metadata.md
index b804c1f009f..6410c34281e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/scala/schema-metadata.md
@@ -103,8 +103,8 @@ enum SearchTarget derives ForySerializer {
}
```
-Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个非 `Unknown` case。
-未知 case 载体由 `@ForyUnknownCase` 选择，而不是由 Schema case ID 选择。当生成的 Scala
+Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个 Schema 定义的 case。
+未知 case 载体由 `@ForyUnknownCase` 选择，与其名称无关，且没有 Schema case ID。当生成的 Scala
联合 case 名称与载荷类型的简单名称相同时，带软件包的输出会保留 case 名称，并使用
限定名表示载荷类型。如果目标输出模式无法为冲突表达合法限定名，IDL 编译器会在生成的
case 名称后追加 `Case`。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/swift/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/swift/schema-metadata.md
index eb4cbd4fef9..d7b1d77effb 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/swift/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/swift/schema-metadata.md
@@ -191,8 +191,8 @@ enum Event {
case user(ThirdParty.User)
```
-每个 `@ForyUnion` 都必须声明 `@ForyUnknownCase case unknown(UnknownCase)`，并至少包含一个非
-`unknown` case。unknown case 只是 Fory 提供的前向兼容载体，不能作为默认值来源。它不会
+每个 `@ForyUnion` 都必须声明恰好一个带有 `@ForyUnknownCase` 且只有一个 `UnknownCase` 关联值的
+case，并至少包含一个 Schema 定义的 case。标记的 case 名称不受限制。未知 case 只是 Fory 提供的前向兼容载体，不能作为默认值来源。它不会
出现在 Schema case 表中，因为该标记只选择载体，不会添加 Schema 条目。Schema case 使用
非负 ID。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/row-format/java.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/row-format/java.md
index 7676d7ac787..c055ea90f81 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/row-format/java.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/row-format/java.md
@@ -41,14 +41,14 @@ Maven：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle：
```kotlin
-implementation("org.apache.fory:fory-format:1.7.6")
+implementation("org.apache.fory:fory-format:1.7.7")
```
## 基本用法
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/cpp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/cpp.md
index 58e2bccffbf..cae22353856 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/cpp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/cpp.md
@@ -42,7 +42,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/csharp.md
index 48c97c3ee51..b94a3de1bac 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/csharp.md
@@ -34,7 +34,7 @@ dotnet --version
```bash
dotnet new console -n ForyExample
cd ForyExample
-dotnet add package Apache.Fory --version 1.7.6
+dotnet add package Apache.Fory --version 1.7.7
```
将 `Program.cs` 替换为：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/dart.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/dart.md
index ef5ccc8e1ec..a12e8ee2ab5 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/dart.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/dart.md
@@ -34,7 +34,7 @@ dart pub --help
```yaml
dependencies:
- fory: 1.7.6
+ fory: 1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/go.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/go.md
index 80973c120b2..0d11890879c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/go.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/go.md
@@ -36,7 +36,7 @@ go env GOPROXY
mkdir fory-example
cd fory-example
go mod init example.com/fory-example
-go get github.com/apache/fory/go/fory@v1.7.6
+go get github.com/apache/fory/go/fory@v1.7.7
```
如果 Go proxy 尚未收录新的 submodule tag，请稍后重试，或者暂时使用 `GOPROXY=direct`。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/java.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/java.md
index 73186eb1850..905a8fd1918 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/java.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/java.md
@@ -39,14 +39,14 @@ Maven：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle：
```kotlin
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
运行下面完整的 xlang 往返示例：
@@ -85,7 +85,7 @@ public final class ForyExample {
Fory JSON 将 Java 对象映射为标准 JSON 文本和 UTF-8 字节。如果应用只需要 JSON，请添加 `fory-json`，无需添加 `fory-core`：
```kotlin
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
在 `ForyExample.java` 中添加 import：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/javascript.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/javascript.md
index d9aa1b2db43..5d674d094f7 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/javascript.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/javascript.md
@@ -33,7 +33,7 @@ npm --version
安装 core 软件包：
```bash
-npm install @apache-fory/core@1.7.6
+npm install @apache-fory/core@1.7.7
```
定义 Schema 并运行 xlang 往返示例：
@@ -65,7 +65,7 @@ JavaScript 使用 xlang 模式。接下来可阅读 [JavaScript/TypeScript 对
若要使用可选的 Node.js 字符串快速路径，请安装版本匹配的软件包：
```bash
-npm install @apache-fory/core@1.7.6 @apache-fory/hps@1.7.6
+npm install @apache-fory/core@1.7.7 @apache-fory/hps@1.7.7
```
## 其他能力
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/kotlin.md
index 929f3113a74..d8d7d65d8fc 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/kotlin.md
@@ -42,7 +42,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-kotlin:1.7.7")
}
```
@@ -81,7 +81,7 @@ Fory JSON 是独立于二进制对象序列化的文本格式。与普通 JSON A
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/python.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/python.md
index 5e09627ead0..d72426c78c5 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/python.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/python.md
@@ -33,7 +33,7 @@ python -m pip --version
安装已发布的软件包：
```bash
-python -m pip install pyfory==1.7.6
+python -m pip install pyfory==1.7.7
```
运行 xlang 往返示例：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/rust.md
index 721f85fcd9f..0595381fbe8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/rust.md
@@ -34,7 +34,7 @@ cargo --version
```toml title="Cargo.toml"
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
```rust
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/scala.md
index bb81113847d..c3e870cb756 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/scala.md
@@ -35,7 +35,7 @@ sbt --version
```sbt
ThisBuild / scalaVersion := "3.3.1"
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
创建 `src/main/scala/ScalaExample.scala`：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md
index fcff6aa3a6b..e9fab6911a6 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md
@@ -39,7 +39,7 @@ swift package init --type executable --name ForyExample
```swift title="Package.swift"
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "1.7.6")
+ .package(url: "https://github.com/apache/fory.git", exact: "1.7.7")
],
targets: [
.executableTarget(
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/build-integration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/build-integration.md
index 2783e7ab30f..48daf968b6d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/build-integration.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/build-integration.md
@@ -211,7 +211,7 @@ cc_library(
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/cli.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/cli.md
index 9dc3def02ba..b4d2d9a2208 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/cli.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/cli.md
@@ -659,5 +659,5 @@ fory = "x.y.z"
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/csharp.md
index 6a80683fc31..9da227ff2c1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/csharp.md
@@ -51,7 +51,8 @@ public sealed partial class Person
`[ForyUnknownCase]` 标记。该标记只选择载体，不会向 Schema case 表添加条目。Schema
定义的 case 使用非负 `[ForyCase]` ID。如果 case 需要非默认 Schema 编码，生成的
`[ForyCase]` 会携带 `Type`。已知 case record 名称采用 PascalCase FDL case 名称；需要
-避免名称冲突时，载荷类型生成为限定引用。类型化联合必须至少包含一个非 `Unknown` case。
+避免名称冲突时，载荷类型生成为限定引用。类型化联合必须至少包含一个 Schema 定义的 case。
+名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
```csharp
[ForyUnion]
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/index.md
index 1af56c7e1b0..4e1374e20f8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/index.md
@@ -28,6 +28,13 @@ Fory IDL 生成的类型遵循宿主语言习惯，可以直接用作领域对
`ComplexPbForyModule` 等名称允许多个 IDL 文件指向同一个包或命名空间，而不会生成
冲突的 `ForyModule` 类型。
+## 未知联合 case 的名称 {#unknown-union-case-names}
+
+C#、Kotlin、Scala 和 Rust 生成 `Unknown` case 来保留未知联合值；Swift 使用 `unknown`。
+Schema 定义的 case 保持各语言的常规名称形式。如果生成的载体名称冲突，编译器使用
+`Unknown_`，Swift 则使用 `unknown_`。如果备用名称也已被占用，生成会失败。
+未知 case 注解或属性用于标识载体，不要求载体必须名为 `Unknown` 或 `unknown`。
+
## 参考 Schema
以下示例使用两个真实 Schema：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/kotlin.md
index dfba66192e6..eaefda1ba5b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/kotlin.md
@@ -61,6 +61,8 @@ public data class Person(
}
```
+空消息生成具有无参构造函数的普通类。
+
参与编译器检测到的构造环的消息会生成普通可变类，使生成的序列化器能够在读取反向引用前
发布实例：
@@ -82,7 +84,8 @@ public class Node() {
枚举生成具有稳定 Fory 枚举 ID 的 Kotlin 枚举类。联合生成带 `@ForyUnion` 的密封类；Fory
提供的 `Unknown(UnknownCase)` 载体使用 `@ForyUnknownCase` 标记。该标记只选择载体，不会
向 Schema case 表添加条目。Schema 定义的 case 可以使用 case ID `0..N`，并保存一个
-`value` 属性。类型化联合必须至少包含一个非 `Unknown` case。
+`value` 属性。类型化联合必须至少包含一个 Schema 定义的 case。名称冲突时，生成的载体名为
+`Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
```kotlin
package addressbook
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/python.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/python.md
index 441e2dbdbdd..f8110f159b4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/python.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/python.md
@@ -70,6 +70,14 @@ class Person:
def from_bytes(cls, data: bytes) -> "Person": ...
```
+## 字段名称 {#field-names}
+
+生成的 Python 属性使用 `snake_case`，Python 关键字会增加尾部下划线。
+`field`、`pyfory`、`decimal`、`list` 和 `dict` 也会增加尾部下划线。
+由这五个名称之一加下划线组成的名称会再增加一个下划线，确保字段彼此不同：
+`field`、`field_` 和 `field__` 分别变为 `field_`、`field__` 和 `field___`。
+字段 tag ID 保持不变。
+
## 注册
生成的注册函数：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/rust.md
index 19087a1982e..e8c8a93171e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/rust.md
@@ -35,8 +35,9 @@ Rust 输出为每个 Schema 生成一个模块文件，例如：
联合映射到带 `#[fory(id = ...)]` Schema case 属性的 Rust 枚举。
`#[fory(unknown)] Unknown(::fory::UnknownCase)` 标记 Fory 提供的向前兼容载体。该标记
只选择载体，不会向 Schema case 表添加条目；Schema case 仍使用完整的 `0..N` ID 范围。
-生成的类型化联合必须至少包含一个非 `Unknown` case。编译器将第一个声明的非 `Unknown`
-case 标记为 `#[fory(default)]`。当该 case 的载荷实现 Rust 标准 `Default` trait 时，编译器
+名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
+生成的类型化联合必须至少包含一个 Schema 定义的 case。编译器将第一个声明的 Schema case
+标记为 `#[fory(default)]`。当该 case 的载荷实现 Rust 标准 `Default` trait 时，编译器
还会从该 case 生成标准 `Default` 实现：
```rust
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/scala.md
index e1370859175..f055a9facdf 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/scala.md
@@ -96,7 +96,8 @@ enum PhoneType {
联合生成 Scala 3 ADT 枚举。`Unknown(UnknownCase)` 是 Fory 提供的向前兼容载体，使用
`@ForyUnknownCase` 标记。它不会出现在 Schema case 表中，因为该标记只选择载体，不会
添加 Schema 条目。Schema 定义的 case 使用非负 `@ForyCase` ID。类型化联合必须至少
-包含一个非 `Unknown` case。
+包含一个 Schema 定义的 case。名称冲突时，生成的载体名为 `Unknown_`；如果该名称也冲突，
+则会报错。Schema case 名称保持不变。
```scala
package addressbook
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/swift.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/swift.md
index 673083d0889..1df881d500a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/swift.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/compiler/generated-code/swift.md
@@ -27,10 +27,10 @@ Swift 输出为每个 Schema 生成一个 `.swift` 文件，例如：
## 类型生成
-生成器使用拆分模型宏和稳定字段/case ID 创建 Swift 模型。类型化联合必须包含
-`@ForyUnknownCase case unknown(UnknownCase)` 和至少一个非 `unknown` case；
-`unknown(UnknownCase)` 只是 Fory 提供的向前兼容载体。该标记只选择载体，不会向 Schema
-case 表添加条目。
+生成器使用拆分模型宏和稳定字段/case ID 创建 Swift 模型。类型化联合必须包含一个带
+`@ForyUnknownCase` 标记的 case 和至少一个 Schema 定义的 case；`unknown(UnknownCase)`
+是 Fory 提供的向前兼容载体的默认名称。该标记只选择载体，不会向 Schema case 表添加条目。
+名称冲突时，生成的载体名为 `unknown_`；如果该名称也冲突，则会报错。Schema case 名称保持不变。
当包/命名空间非空时，命名空间形状由 `swift_namespace_style` 控制：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/csharp.md
index 9a4a24a4706..ca6c3a34748 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/csharp.md
@@ -36,7 +36,7 @@ gRPC 客户端、服务基类、方法描述符、元数据、截止时间、取
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.AspNetCore" Version="2.71.0" />
</ItemGroup>
```
@@ -45,7 +45,7 @@ gRPC 客户端、服务基类、方法描述符、元数据、截止时间、取
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.Core.Api" Version="2.71.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.71.0" />
</ItemGroup>
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/dart.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/dart.md
index dce964090b5..b89506e2b36 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/dart.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/dart.md
@@ -29,7 +29,7 @@ license: |
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
grpc: ^4.0.0
dev_dependencies:
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/rust.md
index 628db9b23ab..6573496f887 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/grpc/rust.md
@@ -29,7 +29,7 @@ license: |
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
bytes = "1"
tonic = { version = "0.14", features = ["transport"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/annotations.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/annotations.md
index fd19052e19f..1f146198fc3 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/annotations.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/annotations.md
@@ -96,7 +96,7 @@ Mixin 提供的 `JsonCodec` 会成为目标的有效注解。精确的 `register
## `JsonProperty`
-`JsonProperty` 配置一个完整逻辑属性的规范名称、序列化索引和值包含策略。字段、getter 或 setter
+`JsonProperty` 配置一个完整逻辑属性的规范名称、序列化索引、写入包含策略和读取端 null 处理。字段、getter 或 setter
上的注解会应用于合并后的字段/getter/setter 属性组。
```java
@@ -166,6 +166,51 @@ Scala 的字段缺失行为见 [case class 与注解](scala.md#case-classes-and-
不支持别名以及相互独立的读写名称。`JsonProperty` 不能与 Any 逻辑属性组合，
也不能声明在 `JsonAnySetter` 上。
+### 读取端 null 处理 {#read-side-null-handling}
+
+`onNullRead` 控制赋给属性的显式 JSON null。`onContentNullRead` 控制属性的数组或集合中的
+null 元素，以及 Map 中的 null 值。两者均使用 `JsonProperty.NullHandling`：
+
+| 值 | 行为 |
+| --------- | ---------------------------------------------------------------- |
+| `DEFAULT` | 继承对应的 builder 设置。这是注解默认值。 |
+| `SET` | 按常规规则解码和赋值，包括声明的可空性规则。 |
+| `SKIP` | 消费 null，并省略此次赋值、元素或 Map 插入。 |
+| `FAIL` | 遇到显式 null 时抛出 `ForyJsonException`。此设置仍允许属性缺失。 |
+
+两个 builder 设置均默认为 `SET`。显式注解值仅覆盖对应的默认设置：
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+public final class Response {
+ @JsonProperty(onNullRead = NullHandling.SKIP, onContentNullRead = NullHandling.SKIP)
+ public java.util.List<String> seats = java.util.List.of("default");
+}
+```
+
+读取 `{"seats":null}` 会保留初始化的列表。读取 `{"seats":[null,"a"]}` 会赋值为只含 `"a"` 的列表；
+`[null]` 会赋值为空列表。跳过属性不会调用其 setter。构造函数参数遵循原有的缺失属性默认值和
+必需属性校验。跳过重复成员不会清除较早的值：`{"seats":["a"],"seats":null}` 会保留 `"a"`。
+绕过构造函数创建的对象没有可保留的初始化值。
+
+`SET` 保留编解码器行为：null 可能变为 `Optional.empty()`，也可能因基本类型或 Kotlin 非空值而失败。
+`SKIP` 和 `FAIL` 在这种解码之前生效。仅处理字面量 JSON null；字符串 `"null"` 以及自定义编解码器
+处理其他 token 后返回的 Java null 不会被过滤。这些选项不影响写入，也不改变根值的 null 行为。
+
+内容覆盖仅作用于一层。对于 `List<List<String>>`，属性覆盖会跳过 null 内层列表；保留下来的列表内部
+元素遵循全局设置。Map 键不受影响，跳过重复键的 null 值会保留较早的条目。
+数字形式的字节数组支持内容处理，Base64 和 Base16 字符串不支持。在标量、声明为 `Object` 的值、
+透明包装或编码后的二进制字符串上显式指定内容设置是无效的。
+
+全局内容设置也适用于根容器、动态 JSON 数组或对象以及 Any 条目。不能在展开的父属性上显式指定
+null 设置；展开后的子属性保留各自的设置。仅遇到被跳过的子属性不会创建该组或将该组标记为已提供。
+
+匹配的字段、getter、setter 和创建器声明按每个设置独立合并。相互冲突的显式值会被拒绝，
+读取端设置要求属性可读或存在创建器参数。Mixin 替换和移除在合并之前执行。
+完整的自定义容器编解码器支持显式 `SET`；显式内容 `SKIP` 或 `FAIL` 要求容器表示由 Fory 负责。
+见[自定义编解码器](custom-codecs.md)。
+
## `JsonInclude` 与默认值省略 {#jsoninclude-and-default-omission}
默认值可能依赖构造函数参数、时间、随机数或外部状态。能够求值并不意味着省略后能恢复相同的值。
@@ -220,7 +265,7 @@ Fory 不证明纯度或分析默认值表达式。Scala 依赖式默认值方法
基本类型按值比较。浮点数区分正零和负零，非有限值保留并按常规方式输出。数组比较精确的数组类型与内容，
嵌套数组递归比较；其他引用使用 `equals`。不支持循环结构的深度比较。
-读取行为独立：显式 null 不等于缺失，可变参考默认值不会与解码对象共享。
+读取行为独立：在 `onNullRead(SET)` 下，显式 null 不等于缺失，可变参考默认值不会与解码对象共享。
可以通过已有 Mixin 机制授权默认值，而不修改模型：
@@ -551,7 +596,7 @@ public final class Name {
会应用于每个子属性经 `JsonProperty` 和已配置命名策略处理后的最终 JSON 名称。嵌套展开属性会从内向外
组合这些转换。
-null 子对象不会写入任何成员。读取时，Fory 只有在遇到至少一个展开成员后才会创建并赋值该子对象。
+null 子对象不会写入任何成员。读取时，Fory 只有在遇到至少一个值未被跳过的展开成员后才会创建并赋值该子对象。
因此，完全缺失的属性组会保留可变父对象的初始化值；Record 或创建器参数则保持常规的缺失属性默认值。
对于部分输入，子对象的其他属性使用普通默认值完成构造。
@@ -600,7 +645,7 @@ import org.apache.fory.json.annotation.JsonIgnore;
public Map<String, Object> outputOnly;
```
-读取时会复用现有 Map。非 final 的 null 字段会在遇到第一个未知成员时初始化。普通可变对象上的可读 final
+读取时会复用现有 Map。非 final 的 null 字段会在遇到第一个值未被跳过的未知成员时初始化。普通可变对象上的可读 final
字段必须已经包含可变 Map。Record 和属性列表形式的 `JsonCreator` 类型则通过构造参数接收累计得到的 Map。
如果不存在未知成员，Fory 不会初始化 null 字段。
@@ -700,8 +745,8 @@ public static User create(
创建器必须至少有一个参数，且不能使用可变参数或泛型。构造函数必须是 public。工厂方法必须是 public
且 static，其精确返回类型必须声明为目标类，并返回非 null 值，且该值的运行时类必须恰好是目标类。
-缺失的引用参数使用 null，缺失的基本类型参数使用 Java 零值，重复成员采用最后一个值；基本类型参数若
-显式接收 null 则会被拒绝。Record 不能声明基于属性的 `JsonCreator`；带有 `JsonValue` 的 Record 可以在
+缺失的引用参数使用 null，缺失的基本类型参数使用 Java 零值。重复成员采用最后一个未被跳过的值；
+在 `onNullRead(SET)` 下，基本类型参数显式接收 null 会被拒绝。Record 不能声明基于属性的 `JsonCreator`；带有 `JsonValue` 的 Record 可以在
其单 String 参数的规范构造函数上标注值形式。
## `JsonValidator`
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/custom-codecs.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/custom-codecs.md
index 620dc6445dd..808ed521061 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/custom-codecs.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/custom-codecs.md
@@ -101,6 +101,9 @@ ForyJson json =
.build();
```
+声明的数组、集合和 Map 中的 `Object` 元素或值也会查询工厂。工厂接管 `Object` 时，会替换这些位置
+默认的自然 JSON 值映射。
+
可配置工厂必须重写 `factoryKey()`，返回一个确定性值，覆盖所有可能改变生成编解码器类、对象模型或生成操作的选项。默认的工厂类名仅适用于无配置工厂。
仅当工厂在动态写入期间为值的实际类选择编解码器时，`runtimeType` 才为 `true`；声明的根类型和复合子类型收到的是 `false`。复合编解码器如果在构造后仍需此区分，必须保留该标志供后续 `resolveTypes` 调用使用，不能从 resolver 状态推断。
@@ -109,7 +112,14 @@ ForyJson json =
就不会调用编解码器的写入操作。`NON_EMPTY` 直接检查 Java 空值类型，
其他类型使用编解码器的 `isEmpty` 方法；见[自定义空值](#custom-empty-values)。
如果属性会被输出，或者该值是数组元素、集合元素、Map 值、Optional 值或原子引用值，
-编解码器就会接收并负责处理 null。注册的实例会在并发操作之间共享，因此必须是线程安全的。
+写入时编解码器会接收并负责处理 null。读取时，适用设置为 `SET` 时由编解码器负责 null。
+属性的 `onNullRead` 和 Fory 容器的 `onContentNullRead` 配置为 `SKIP` 或 `FAIL` 时，
+会在调用选定的子编解码器之前处理字面量 null。编解码器消费非 null token 后返回的 Java null 不会被过滤。
+注册的实例会在并发操作之间共享，因此必须是线程安全的。
+
+完整的自定义容器编解码器负责其内部表示，全局内容设置不会改变它。对于这样的声明容器属性，
+显式内容 `SET` 委托给编解码器；显式 `SKIP` 或 `FAIL` 会被拒绝。完整的自定义对象编解码器
+同样负责其内部属性处理。普通外围属性设置仍在调用这两种完整编解码器之前生效。
会物化复合对象图所有者的自定义编解码器，在创建每个所有者之前，必须使用应用定义的字节估算值
调用 `JsonReader.reserveGraphMemory`。这适用于复合应用对象、集合、Map 和引用数组。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/getting-started.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/getting-started.md
index fb10ce0f387..90b744b41dc 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/getting-started.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/getting-started.md
@@ -41,7 +41,7 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-json</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -55,7 +55,7 @@ repositories {
mavenCentral()
}
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
### Kotlin
@@ -64,7 +64,7 @@ Kotlin/JVM 应用添加可选的 Kotlin JSON 运行时，并使用其统一 buil
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/kotlin.md
index 7d07777f0c5..b9a958d102c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/kotlin.md
@@ -38,7 +38,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
@@ -50,7 +50,7 @@ plugins {
}
dependencies {
- ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.6")
+ ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.7")
}
```
@@ -134,12 +134,18 @@ data class Request(
主构造函数会被自动选择。公共次构造函数或目标类型自身的公共静态工厂，只有经 `JsonCreator` 显式选择后才会使用；伴生对象工厂必须通过外层类中实际存在的 `@JvmStatic` 桥接方法才符合条件。`@JvmOverloads` 生成的方法不是独立 creator 候选，选定的静态工厂也不能含编译器默认参数。私有/受保护、可变参数、方法泛型、上下文参数、局部类、匿名类、`inner` 类或合成构造路径需要精确的应用编解码器。
-对于这个模型：
+使用默认的 `onNullRead(SET)` 时，这个模型的行为如下：
- `{"id":1}` 会调用两个编译器默认值。
- `{"id":1,"label":null}` 会传入显式 null，不调用 `label` 的默认值。
- 缺少 `id` 使用 `0`。
-- `{"id":1,"retries":null}` 会失败；null 不会要求 Kotlin 使用默认值。
+- `{"id":1,"retries":null}` 会失败。
+
+使用 `ForyJsonKotlin.builder().onNullRead(JsonProperty.NullHandling.SKIP)` 可将一次 null 输入视为缺失，
+保留构造函数默认值和类体属性初始化值。没有默认值的非空引用仍是必需属性。
+使用 `@get:JsonProperty(onNullRead = JsonProperty.NullHandling.SET)` 可让单个属性保留常规 null 解码。
+`onContentNullRead` 处理直接的集合或数组元素以及 Map 值，包括无符号数组。
+属性覆盖仅作用于一层，跳过 null 发生在元素可空性检查之前。见[读取端 null 处理](annotations.md#read-side-null-handling)。
启用 `ForyJsonKotlin.builder().failOnMissingRequiredProperties(true).build()` 后，未声明默认值的普通
构造函数属性必须出现在输入中，包括可空属性、数值属性和 Boolean 属性。已声明的编译器默认值仍然生效。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/object-mapping.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/object-mapping.md
index 7e61f960a30..963619d8fee 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/object-mapping.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/object-mapping.md
@@ -54,8 +54,12 @@ ForyJson json =
static、transient、synthetic 和 `Class<?>` 字段会被排除。`getClass()` 以及值类型为 `Class<?>`
的访问器也会被排除。在不符合条件的成员上放置注解会直接报错，而不是被静默忽略。
-普通 final 字段可以写出，但不会作为反序列化时的可变写入目标。不可变对象应使用 record、
-`JsonCreator` 或自定义编解码器来构造。
+读取 JSON 时会恢复符合条件的实例字段，包括普通 `final` 字段。子类字段隐藏父类同名字段时，
+读写两个方向均以子类字段作为 JSON 属性。忽略该字段不会暴露被隐藏的父类字段。
+
+普通对象属性在读取时使用声明类型。通过具体的声明基类类型写入子类实例时，Fory 会写出子类的
+映射属性。通过基类类型读取相同 JSON 时，会创建基类实例并忽略子类独有的属性。
+读取器需要恢复子类型时，应使用 `@JsonSubTypes` 或自定义编解码器。
### 字段模式
@@ -104,7 +108,8 @@ ForyJson json = ForyJson.builder()
未声明默认值的普通属性必须出现在输入中，不再自动填充零、false 或 null。此选项不会引入新的容器默认值：
没有默认值的 Kotlin 非空集合仍为必需属性，而 Scala 集合保留现有的空集合默认值。
-显式 JSON null 视为已提供的属性值，继续遵循属性的类型和可空性规则。被忽略的属性、普通无参 Java Bean
+使用默认的 `onNullRead(SET)` 时，显式 JSON null 视为已提供的属性值，并遵循属性的类型和可空性规则。
+使用 `SKIP` 时，该次输入被省略，不能满足必需参数要求。被忽略的属性、普通无参 Java Bean
以及构造后赋值的属性保持原有行为。完整的自定义对象编解码器自行负责缺失字段规则。
此选项不改变写入。如果包含策略省略了必需属性，生成的 JSON 可能被严格读取器拒绝。应在输出中保留该属性，
@@ -112,10 +117,30 @@ ForyJson json = ForyJson.builder()
## Kotlin 对象映射 {#kotlin-object-mapping}
-为 Kotlin/JVM 类安装 `fory-json-kotlin` 并使用 `ForyJsonKotlin.builder()`。Kotlin 普通类和 data class 使用选定的构造函数、精确属性类型、编译器默认值和声明的可空性，不使用 Java 绕过构造函数的回退路径。默认值仅在成员缺失时生效。显式 JSON null 仍是已提供的值，非空参数会拒绝它。
+为 Kotlin/JVM 类安装 `fory-json-kotlin` 并使用 `ForyJsonKotlin.builder()`。Kotlin 普通类和 data class 使用选定的构造函数、精确属性类型、编译器默认值和声明的可空性，不使用 Java 绕过构造函数的回退路径。成员缺失或其 null 输入被跳过时使用默认值。默认情况下，显式 JSON null 是已提供的值，非空参数会拒绝它。
泛型、可空、无符号和值类根类型应使用 `jsonTypeRef<T>()`。标准数组、集合和 Map 继续使用常规 Fory JSON 表示。完整语言类型表、单例/值类行为和省略规则见 [Kotlin 指南](kotlin.md)。
+## 读取端 null 处理 {#read-side-null-handling}
+
+使用独立的 builder 设置可保留已有属性值，并省略 null 容器项：
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+ForyJson json = ForyJson.builder()
+ .onNullRead(NullHandling.SKIP)
+ .onContentNullRead(NullHandling.SKIP)
+ .build();
+```
+
+两者均默认为 `SET`。`FAIL` 拒绝显式 null；`SKIP` 省略该次输入。
+builder 只接受具体模式，不接受 `DEFAULT` 或 Java null。每个构建的实例保留自己的配置。
+使用 `@JsonProperty(onNullRead = SET)` 或 `onContentNullRead = SET` 可让单个属性不受对应全局规则影响。
+内容设置覆盖直接的集合或数组元素以及 Map 值，包括根容器和动态 JSON 树。
+属性设置作用于带类型的对象属性，包括嵌套对象，但不改变根 `null` 值。
+见[注解语义与示例](annotations.md#read-side-null-handling)。
+
## 支持的 Java 类型 {#supported-java-types}
下列类型组具有内置映射。具体编码表示形式都是稳定的 JSON 值，但在精度或构造方式很重要时，应用
@@ -231,6 +256,8 @@ builder 接受 `ALWAYS`、`NON_NULL` 和 `NON_EMPTY`，拒绝 `DEFAULT` 和 `NON
| `byteArrayFormat(JsonByteArray.Format)` | `BASE64` | 字节数组读写的默认表示方式 |
| `withCodegen(boolean)` | `true` | 启用生成的对象编解码器 |
| `withAsyncCompilation(boolean)` | `true` | 异步编译生成的编解码器 |
+| `onNullRead(NullHandling)` | `SET` | 处理显式 null 属性值 |
+| `onContentNullRead(NullHandling)` | `SET` | 处理数组或集合中的 null 元素以及 Map 中的 null 值 |
| `withFieldMode(boolean)` | `false` | 为 true 时，仅发现字段而不使用 getter/setter |
| `withPropertyNamingStrategy(strategy)` | `LOWER_CAMEL_CASE` | 为未显式指定 `JsonProperty` 名称的属性命名 |
| `withMaxCachedFieldNames(int)` | `DEFAULT_MAX_CACHED_FIELD_NAMES` (`8192`) | 每个 reader 的字段名缓存条目数；零表示禁用缓存 |
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/scala.md
index 9bc86c5aeb3..480290534a1 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/json/scala.md
@@ -24,7 +24,7 @@ Fory JSON 通过可选的 `fory-json-scala` 制品支持 Scala 2.13 和 Scala 3
## 设置 {#setup}
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.7"
```
`ForyJsonScala.builder()` 安装 Scala 模块并返回标准 Fory JSON builder：
@@ -93,9 +93,14 @@ json.fromJson("{}", classOf[Profile]) // Profile(0, false, List(), null)
`case class Request(id: Int = 7)` 仍将它读取为 `Request(7)`。Option、集合、Map 和数组属性保留现有的
缺失值默认规则。此选项默认关闭，不改变写入或显式 null 的处理。
-显式构造函数默认值优先用于缺失的属性。显式 JSON `null` 对 `Option[A]` 解码为 `None`，
+显式构造函数默认值优先用于缺失的属性。使用默认的 `onNullRead(SET)` 时，JSON `null` 对 `Option[A]` 解码为 `None`，
即使其构造函数默认值为 `Some(...)` 也是如此。
+使用 `ForyJsonScala.builder().onNullRead(JsonProperty.NullHandling.SKIP)` 可跳过 null 属性输入，
+保留构造函数默认值或类体属性初始化值。`onContentNullRead` 适用于受支持的严格求值 Scala 集合
+中的直接元素和 Map 值，包括基本类型集合。逐属性的 `JsonProperty` 设置覆盖对应的全局默认值，
+不会传播到嵌套容器。见[读取端 null 处理](annotations.md#read-side-null-handling)。
+
case class 可以声明在顶层，也可以嵌套在任意层数的 `object` 内，但每一层外部作用域都必须是 `object`。如果外层是 `class`、trait 或方法，读写都会被拒绝，因为 Fory 无法访问重建值所需的外部实例或伴生对象。
构造要求具有公共 JVM 构造函数以及匹配的公共伴生对象 `apply`；不支持的私有构造形式会被拒绝。
@@ -115,7 +120,7 @@ case class Media(
`JsonIgnore` 适用于字段、属性方法、setter 参数和选定的构造函数参数。`JsonCodec` 子槽位绑定直接集合元素、`Option` 内容，以及 Map 键或值。其他 Fory JSON 注解保持[注解](annotations.md)中描述的行为。
属性包含策略控制写出的值。省略的属性在读取时使用构造函数或类型默认值，因此省略空字符串可能恢复为 `null`。
-如果需要保留区别，使用 `ALWAYS`。显式 JSON `null` 保持声明类型的常规 null 行为，不会请求构造函数默认值。
+如果需要保留区别，使用 `ALWAYS`。在 `onNullRead(SET)` 下，JSON `null` 保持声明类型的常规 null 行为，不会请求构造函数默认值。
`NON_EMPTY` 识别 `None` 和受支持的空严格求值 Scala 序列、集合、Map，包括可变集合和 range。
过滤不递归：`Some("")`、`Some(Nil)`、`Some(null)` 和非空容器都会保留。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/cpp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/cpp/index.md
index 027a2eaf121..696e77b98d4 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/cpp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/cpp/index.md
@@ -60,7 +60,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -90,11 +90,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v1.7.6", # Or use a specific commit hash for reproducibility
+ commit = "v1.7.7", # Or use a specific commit hash for reproducibility
)
```
@@ -125,7 +125,7 @@ bazel run //:my_app
本地开发时，可以改用 `local_path_override`：
```bazel
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/index.md
index 94cbfa1d5c3..a7b101ebb80 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/index.md
@@ -44,7 +44,7 @@ Apache Fory™ C# 是面向 .NET 的高性能跨语言序列化库。它支持
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
</ItemGroup>
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
index 366019499be..9db0d9bf4e2 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
@@ -105,7 +105,7 @@ Schema 描述符位于 `Apache.Fory.Schema.Types` 下，仅作为元数据使用
## `[ForyUnion]` 和 `[ForyCase]`
-生成的 union case 使用 `[ForyCase]` 同时指定稳定 case ID 和可选的 case 载荷 Schema 类型。不要在 union case 载荷成员上添加 `[ForyField]`。已知 case 的 record 名称使用 PascalCase FDL case 名称；需要避免名称冲突时，载荷类型使用限定引用。类型化 union 必须声明至少一个非 `Unknown` case；`Unknown(UnknownCase)` 只是 Fory 提供的向前兼容载体。该标记只选择载体，不会在 Schema case 表中增加条目。
+生成的 union case 使用 `[ForyCase]` 同时指定稳定 case ID 和可选的 case 载荷 Schema 类型。不要在 union case 载荷成员上添加 `[ForyField]`。已知 case 的 record 名称使用 PascalCase FDL case 名称；需要避免名称冲突时，载荷类型使用限定引用。类型化 union 必须声明至少一个 Schema 定义的 case，以及恰好一个暴露 `Value: UnknownCase` 的 `[ForyUnknownCase]` case。载体名称不受限制。该标记只选择载体，不会在 Schema case 表中增加条目。
```csharp
using Apache.Fory;
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/dart/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/dart/index.md
index 5666763a43f..a790cbc1d4d 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/dart/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/dart/index.md
@@ -44,7 +44,7 @@ Apache Fory™ Dart 可以将 Dart 对象序列化为字节并反序列化，也
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/java/index.md
index 368686e637a..8e6ddae8c78 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/java/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/java/index.md
@@ -51,7 +51,7 @@ Fory core 支持 Java 8 及更高版本。Java Record 序列化需要 Java 17
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -59,7 +59,7 @@ Fory core 支持 Java 8 及更高版本。Java Record 序列化需要 Java 17
```kotlin
// Binary object serialization
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
#### JDK 25 及更高版本
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/index.md
index aa2a007acce..b6e6583aa1e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/index.md
@@ -53,14 +53,14 @@ Fory Kotlin 继承了 Fory Java 的全部功能，并增加了 Kotlin 特有优
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:1.7.6")
+implementation("org.apache.fory:fory-kotlin:1.7.7")
```
### JDK25+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
index 99235d11bb5..d201040d0e0 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
@@ -198,7 +198,8 @@ KSP 会为带 `@ForyUnion` 注解的顶层密封类生成序列化器。每个 S
`@ForyCase` 注解的嵌套类，并包含一个名为 `value` 的构造函数属性。
`Unknown(UnknownCase)` 使用 `@ForyUnknownCase` 标记，作为 Fory 管理的向前兼容载体。
它不会出现在 Schema case 表中，因为该标记只选择载体，不会添加 Schema 条目。类型化
-联合必须声明至少一个非 `Unknown` case：
+联合必须声明至少一个 Schema 定义的 case。恰好一个 case 必须带有 `@ForyUnknownCase`，
+其名称不受限制：
```kotlin
package example
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/basic-serialization.md
index 78484d7bd94..a2b8921b67f 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/basic-serialization.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/basic-serialization.md
@@ -145,7 +145,7 @@ Rust 启用 `chrono::NaiveDate`、`chrono::NaiveDateTime` 和 `chrono::Duration`
```toml
[dependencies]
-fory = { version = "1.7.6", features = ["chrono"] }
+fory = { version = "1.7.7", features = ["chrono"] }
```
### 自定义类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/index.md
index f567af4ffae..6cfbd1f1b8a 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/rust/index.md
@@ -36,9 +36,9 @@ Rust 实现通过自动内存管理和编译期类型安全提供灵活的高性
| Crate | 说明 | 版本 |
| --------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------- |
-| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 面向用户的 API、运行时类型和派生宏 | [1.7.6](https://crates.io/crates/fory) |
-| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 用于高级集成的底层运行时 crate | [1.7.6](https://crates.io/crates/fory-core) |
-| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 供直接使用运行时的底层过程宏 crate | [1.7.6](https://crates.io/crates/fory-derive) |
+| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | 面向用户的 API、运行时类型和派生宏 | [1.7.7](https://crates.io/crates/fory) |
+| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | 用于高级集成的底层运行时 crate | [1.7.7](https://crates.io/crates/fory-core) |
+| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | 供直接使用运行时的底层过程宏 crate | [1.7.7](https://crates.io/crates/fory-derive) |
大多数应用程序只需依赖 `fory`。它重新导出生成代码所需的派生宏和公共运行时类型。只有明确要基于底层运行时 crate 构建时，才直接使用 `fory-core` 或 `fory-derive`。
@@ -48,7 +48,7 @@ Rust 实现通过自动内存管理和编译期类型安全提供灵活的高性
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
### 基本示例
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/basic-serialization.md
index 649012fd038..a13a65137be 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/basic-serialization.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/basic-serialization.md
@@ -151,8 +151,8 @@ enum SearchTarget derives ForySerializer {
名称，并使用限定名表示载荷类型。如果目标输出模式无法为冲突表达合法限定名，IDL
编译器会在生成的 case 名称后追加 `Case`。
-Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个非 `Unknown` case。
-Scala 未知 case 载体由 `@ForyUnknownCase` 选择，而不是由 Schema case ID 选择。其载荷
+Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个 Schema 定义的 case。
+Scala 未知 case 载体由 `@ForyUnknownCase` 选择，与其名称无关，且没有 Schema case ID。其载荷
存储原始 case ID 和反序列化后的值。当读取端遇到较新的 case ID 时，会返回
`Unknown(UnknownCase)`，而不会仅仅因为本地不知道该 case ID 就失败。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/index.md
index 9e09acdb161..44fdada1980 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/index.md
@@ -49,7 +49,7 @@ Fory Scala 继承了 Fory Java 的全部功能，并增加了 Scala 特有优化
使用 sbt 添加依赖：
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
### JDK25+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/schema-metadata.md
index b804c1f009f..6410c34281e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/scala/schema-metadata.md
@@ -103,8 +103,8 @@ enum SearchTarget derives ForySerializer {
}
```
-Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个非 `Unknown` case。
-未知 case 载体由 `@ForyUnknownCase` 选择，而不是由 Schema case ID 选择。当生成的 Scala
+Schema 定义的联合 case 使用非负 ID，类型化联合必须声明至少一个 Schema 定义的 case。
+未知 case 载体由 `@ForyUnknownCase` 选择，与其名称无关，且没有 Schema case ID。当生成的 Scala
联合 case 名称与载荷类型的简单名称相同时，带软件包的输出会保留 case 名称，并使用
限定名表示载荷类型。如果目标输出模式无法为冲突表达合法限定名，IDL 编译器会在生成的
case 名称后追加 `Case`。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/swift/schema-metadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/swift/schema-metadata.md
index eb4cbd4fef9..d7b1d77effb 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/swift/schema-metadata.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/object-serialization/swift/schema-metadata.md
@@ -191,8 +191,8 @@ enum Event {
case user(ThirdParty.User)
```
-每个 `@ForyUnion` 都必须声明 `@ForyUnknownCase case unknown(UnknownCase)`，并至少包含一个非
-`unknown` case。unknown case 只是 Fory 提供的前向兼容载体，不能作为默认值来源。它不会
+每个 `@ForyUnion` 都必须声明恰好一个带有 `@ForyUnknownCase` 且只有一个 `UnknownCase` 关联值的
+case，并至少包含一个 Schema 定义的 case。标记的 case 名称不受限制。未知 case 只是 Fory 提供的前向兼容载体，不能作为默认值来源。它不会
出现在 Schema case 表中，因为该标记只选择载体，不会添加 Schema 条目。Schema case 使用
非负 ID。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/row-format/java.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/row-format/java.md
index 7676d7ac787..c055ea90f81 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/row-format/java.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/row-format/java.md
@@ -41,14 +41,14 @@ Maven：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle：
```kotlin
-implementation("org.apache.fory:fory-format:1.7.6")
+implementation("org.apache.fory:fory-format:1.7.7")
```
## 基本用法
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/cpp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/cpp.md
index 58e2bccffbf..cae22353856 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/cpp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/cpp.md
@@ -42,7 +42,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/csharp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/csharp.md
index 48c97c3ee51..b94a3de1bac 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/csharp.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/csharp.md
@@ -34,7 +34,7 @@ dotnet --version
```bash
dotnet new console -n ForyExample
cd ForyExample
-dotnet add package Apache.Fory --version 1.7.6
+dotnet add package Apache.Fory --version 1.7.7
```
将 `Program.cs` 替换为：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/dart.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/dart.md
index ef5ccc8e1ec..a12e8ee2ab5 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/dart.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/dart.md
@@ -34,7 +34,7 @@ dart pub --help
```yaml
dependencies:
- fory: 1.7.6
+ fory: 1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/go.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/go.md
index 80973c120b2..0d11890879c 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/go.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/go.md
@@ -36,7 +36,7 @@ go env GOPROXY
mkdir fory-example
cd fory-example
go mod init example.com/fory-example
-go get github.com/apache/fory/go/fory@v1.7.6
+go get github.com/apache/fory/go/fory@v1.7.7
```
如果 Go proxy 尚未收录新的 submodule tag，请稍后重试，或者暂时使用 `GOPROXY=direct`。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/java.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/java.md
index 73186eb1850..905a8fd1918 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/java.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/java.md
@@ -39,14 +39,14 @@ Maven：
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle：
```kotlin
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
运行下面完整的 xlang 往返示例：
@@ -85,7 +85,7 @@ public final class ForyExample {
Fory JSON 将 Java 对象映射为标准 JSON 文本和 UTF-8 字节。如果应用只需要 JSON，请添加 `fory-json`，无需添加 `fory-core`：
```kotlin
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
在 `ForyExample.java` 中添加 import：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/javascript.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/javascript.md
index d9aa1b2db43..5d674d094f7 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/javascript.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/javascript.md
@@ -33,7 +33,7 @@ npm --version
安装 core 软件包：
```bash
-npm install @apache-fory/core@1.7.6
+npm install @apache-fory/core@1.7.7
```
定义 Schema 并运行 xlang 往返示例：
@@ -65,7 +65,7 @@ JavaScript 使用 xlang 模式。接下来可阅读 [JavaScript/TypeScript 对
若要使用可选的 Node.js 字符串快速路径，请安装版本匹配的软件包：
```bash
-npm install @apache-fory/core@1.7.6 @apache-fory/hps@1.7.6
+npm install @apache-fory/core@1.7.7 @apache-fory/hps@1.7.7
```
## 其他能力
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/kotlin.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/kotlin.md
index 929f3113a74..d8d7d65d8fc 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/kotlin.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/kotlin.md
@@ -42,7 +42,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-kotlin:1.7.7")
}
```
@@ -81,7 +81,7 @@ Fory JSON 是独立于二进制对象序列化的文本格式。与普通 JSON A
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/python.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/python.md
index 5e09627ead0..d72426c78c5 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/python.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/python.md
@@ -33,7 +33,7 @@ python -m pip --version
安装已发布的软件包：
```bash
-python -m pip install pyfory==1.7.6
+python -m pip install pyfory==1.7.7
```
运行 xlang 往返示例：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/rust.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/rust.md
index 721f85fcd9f..0595381fbe8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/rust.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/rust.md
@@ -34,7 +34,7 @@ cargo --version
```toml title="Cargo.toml"
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
```rust
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/scala.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/scala.md
index bb81113847d..c3e870cb756 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/scala.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/scala.md
@@ -35,7 +35,7 @@ sbt --version
```sbt
ThisBuild / scalaVersion := "3.3.1"
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
创建 `src/main/scala/ScalaExample.scala`：
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/swift.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/swift.md
index fcff6aa3a6b..e9fab6911a6 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/swift.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.7.0/start/swift.md
@@ -39,7 +39,7 @@ swift package init --type executable --name ForyExample
```swift title="Package.swift"
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "1.7.6")
+ .package(url: "https://github.com/apache/fory.git", exact: "1.7.7")
],
targets: [
.executableTarget(
diff --git a/i18n/zh-CN/docusaurus-plugin-content-pages/download/index.md b/i18n/zh-CN/docusaurus-plugin-content-pages/download/index.md
index 2335cbe951b..08891f62bc8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-pages/download/index.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-pages/download/index.md
@@ -9,11 +9,11 @@ Apache Fory™ 的官方发布以源码制品形式提供。
## 最新版本
-当前最新源码版本为 1.7.6：
+当前最新源码版本为 1.7.7：
| 版本 | 日期 | 源码 | 发布说明 |
| ----- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| 1.7.6 | 2026-09-30 | [source](https://www.apache.org/dyn/closer.lua/fory/1.7.6/apache-fory-1.7.6-src.tar.gz?action=download) [asc](https://downloads.apache.org/fory/1.7.6/apache-fory-1.7.6-src.tar.gz.asc) [sha512](https://downloads.apache.org/fory/1.7.6/apache-fory-1.7.6-src.tar.gz.sha512) | [release notes](https://github.com/apache/fory/releases/tag/v1.7.6) |
+| 1.7.7 | 2026-10-12 | [source](https://www.apache.org/dyn/closer.lua/fory/1.7.7/apache-fory-1.7.7-src.tar.gz?action=download) [asc](https://downloads.apache.org/fory/1.7.7/apache-fory-1.7.7-src.tar.gz.asc) [sha512](https://downloads.apache.org/fory/1.7.7/apache-fory-1.7.7-src.tar.gz.sha512) | [release notes](https://github.com/apache/fory/releases/tag/v1.7.7) |
## 所有归档版本
@@ -31,13 +31,13 @@ Fory 为下载站点上的所有文件提供 SHA 摘要和 PGP 签名文件。
要验证 SHA 摘要，你需要 `.tar.gz` 文件及其对应的 `.tar.gz.sha512` 文件。示例命令如下：
```bash
-sha512sum --check apache-fory-1.7.6-src.tar.gz.sha512
+sha512sum --check apache-fory-1.7.7-src.tar.gz.sha512
```
输出类似下面这样即表示校验通过：
```bash
-apache-fory-1.7.6-src.tar.gz: OK
+apache-fory-1.7.7-src.tar.gz: OK
```
### 校验签名
@@ -53,7 +53,7 @@ gpg --import KEYS
之后可以校验签名：
```bash
-gpg --verify apache-fory-1.7.6-src.tar.gz.asc apache-fory-1.7.6-src.tar.gz
+gpg --verify apache-fory-1.7.7-src.tar.gz.asc apache-fory-1.7.7-src.tar.gz
```
如果出现如下输出，即表示签名正确：
diff --git a/src/components/home/HomepageLanding.tsx b/src/components/home/HomepageLanding.tsx
index bbfeef3b360..02243ba9801 100644
--- a/src/components/home/HomepageLanding.tsx
+++ b/src/components/home/HomepageLanding.tsx
@@ -138,7 +138,7 @@ const runtimeExamples: RuntimeExample[] = [
install: `<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>`,
codeLanguage: "java",
guide: "/docs/object-serialization/java/",
@@ -160,7 +160,7 @@ Person out = (Person) fory.deserialize(bytes);`,
id: "python",
label: "Python",
installLanguage: "bash",
- install: `pip install pyfory==1.7.6`,
+ install: `pip install pyfory==1.7.7`,
codeLanguage: "python",
guide: "/docs/object-serialization/python/",
summary:
@@ -183,7 +183,7 @@ out = fory.deserialize(data)`,
id: "rust",
label: "Rust",
installLanguage: "bash",
- install: `cargo add fory@1.7.6`,
+ install: `cargo add fory@1.7.7`,
codeLanguage: "rust",
guide: "/docs/object-serialization/rust/",
summary:
@@ -209,7 +209,7 @@ fn main() -> Result<(), Error> {
id: "go",
label: "Go",
installLanguage: "bash",
- install: `go get github.com/apache/fory/go/fory@v1.7.6`,
+ install: `go get github.com/apache/fory/go/fory@v1.7.7`,
codeLanguage: "go",
guide: "/docs/object-serialization/go/",
summary:
@@ -234,7 +234,7 @@ _ = f.Deserialize(payload, &out)`,
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)`,
@@ -262,7 +262,7 @@ auto out = fory.deserialize<Person>(bytes).value();`,
id: "javascript",
label: "JavaScript",
installLanguage: "bash",
- install: `npm install @apache-fory/core@1.7.6 @apache-fory/hps@1.7.6`,
+ install: `npm install @apache-fory/core@1.7.7 @apache-fory/hps@1.7.7`,
codeLanguage: "typescript",
guide: "/docs/object-serialization/javascript/",
summary:
@@ -284,7 +284,7 @@ const out = deserialize(payload);`,
id: "csharp",
label: "C#",
installLanguage: "bash",
- install: `dotnet add package Apache.Fory --version 1.7.6`,
+ install: `dotnet add package Apache.Fory --version 1.7.7`,
codeLanguage: "csharp",
guide: "/docs/object-serialization/csharp/",
summary:
@@ -308,7 +308,7 @@ Person out = fory.Deserialize<Person>(payload);`,
id: "swift",
label: "Swift",
installLanguage: "swift",
- install: `.package(url: "https://github.com/apache/fory.git", exact: "1.7.6")`,
+ install: `.package(url: "https://github.com/apache/fory.git", exact: "1.7.7")`,
codeLanguage: "swift",
guide: "/docs/object-serialization/swift/",
summary:
@@ -332,7 +332,7 @@ let out: Person = try fory.deserialize(payload)`,
label: "Dart",
installLanguage: "yaml",
install: `dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.13`,
@@ -368,7 +368,7 @@ final out = fory.deserialize<Person>(payload);`,
id: "scala",
label: "Scala",
installLanguage: "sbt",
- install: `libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"`,
+ install: `libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"`,
codeLanguage: "scala",
guide: "/docs/object-serialization/scala/",
summary:
@@ -389,8 +389,8 @@ val out = fory.deserialize(payload).asInstanceOf[Person]`,
id: "kotlin",
label: "Kotlin",
installLanguage: "kotlin",
- install: `implementation("org.apache.fory:fory-kotlin:1.7.6")
-ksp("org.apache.fory:fory-kotlin-ksp:1.7.6")`,
+ install: `implementation("org.apache.fory:fory-kotlin:1.7.7")
+ksp("org.apache.fory:fory-kotlin-ksp:1.7.7")`,
codeLanguage: "kotlin",
guide: "/docs/object-serialization/kotlin/",
summary:
diff --git a/src/pages/download/index.md b/src/pages/download/index.md
index 8ad57e33583..441b6537af5 100644
--- a/src/pages/download/index.md
+++ b/src/pages/download/index.md
@@ -9,11 +9,11 @@ For binary install, please see the Apache Fory™ [getting started](/docs/start/
## The latest release
-The latest source release is 1.7.6:
+The latest source release is 1.7.7:
| Version | Date | Source | Release Notes |
| ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| 1.7.6 | 2026-09-30 | [source](https://www.apache.org/dyn/closer.lua/fory/1.7.6/apache-fory-1.7.6-src.tar.gz?action=download) [asc](https://downloads.apache.org/fory/1.7.6/apache-fory-1.7.6-src.tar.gz.asc) [sha512](https://downloads.apache.org/fory/1.7.6/apache-fory-1.7.6-src.tar.gz.sha512) | [release notes](https://github.com/apache/fory/releases/tag/v1.7.6) |
+| 1.7.7 | 2026-10-12 | [source](https://www.apache.org/dyn/closer.lua/fory/1.7.7/apache-fory-1.7.7-src.tar.gz?action=download) [asc](https://downloads.apache.org/fory/1.7.7/apache-fory-1.7.7-src.tar.gz.asc) [sha512](https://downloads.apache.org/fory/1.7.7/apache-fory-1.7.7-src.tar.gz.sha512) | [release notes](https://github.com/apache/fory/releases/tag/v1.7.7) |
## All archived releases
@@ -31,13 +31,13 @@ These files are named after the files they relate to but have `.sha512/.asc` ext
To verify the SHA digests, you need the `.tar.gz` file and its associated `.tar.gz.sha512` file. An example command:
```bash
-sha512sum --check apache-fory-1.7.6-src.tar.gz.sha512
+sha512sum --check apache-fory-1.7.7-src.tar.gz.sha512
```
It should output something like:
```bash
-apache-fory-1.7.6-src.tar.gz: OK
+apache-fory-1.7.7-src.tar.gz: OK
```
### Verifying Signatures
@@ -54,7 +54,7 @@ gpg --import KEYS
Then you can verify signature:
```bash
-gpg --verify apache-fory-1.7.6-src.tar.gz.asc apache-fory-1.7.6-src.tar.gz
+gpg --verify apache-fory-1.7.7-src.tar.gz.asc apache-fory-1.7.7-src.tar.gz
```
If something like the following appears, it means the signature is correct:
diff --git a/versioned_docs/version-1.7.0/compiler/build-integration.md b/versioned_docs/version-1.7.0/compiler/build-integration.md
index f0dca646633..56dbdd39e05 100644
--- a/versioned_docs/version-1.7.0/compiler/build-integration.md
+++ b/versioned_docs/version-1.7.0/compiler/build-integration.md
@@ -211,7 +211,7 @@ Add the Fory dependency to `pubspec.yaml`:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/versioned_docs/version-1.7.0/compiler/cli.md b/versioned_docs/version-1.7.0/compiler/cli.md
index f4171a8d968..70c135f1300 100644
--- a/versioned_docs/version-1.7.0/compiler/cli.md
+++ b/versioned_docs/version-1.7.0/compiler/cli.md
@@ -689,5 +689,5 @@ fory = "x.y.z"
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
```
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/csharp.md b/versioned_docs/version-1.7.0/compiler/generated-code/csharp.md
index 431c8b08ce3..f0204327ce3 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/csharp.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/csharp.md
@@ -54,7 +54,8 @@ table. Schema-defined cases use non-negative `[ForyCase]` IDs. If a case needs
non-default schema encoding, the generated `[ForyCase]` carries `Type`. Known
case record names are PascalCase FDL case names; payload types are emitted as
qualified references when needed to avoid name conflicts. A typed union must
-have at least one non-`Unknown` case.
+have at least one schema-defined case. On a name collision, the generated carrier
+is named `Unknown_`; a second collision is an error. Schema case names are preserved.
```csharp
[ForyUnion]
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/index.md b/versioned_docs/version-1.7.0/compiler/generated-code/index.md
index a8a872d8729..2d38d808465 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/index.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/index.md
@@ -29,6 +29,15 @@ package or namespace, names such as `AddressbookForyModule` or
`ComplexPbForyModule` let multiple IDL files target the same package or
namespace without producing colliding `ForyModule` types.
+## Unknown Union Case Names
+
+C#, Kotlin, Scala, and Rust generate an `Unknown` case to preserve unknown union
+values; Swift uses `unknown`. Schema-defined case names keep their normal
+language-specific spelling. If the generated carrier name conflicts, the compiler
+uses `Unknown_` or Swift's `unknown_`. If that alternate name is also occupied,
+generation fails. The unknown-case annotation or attribute identifies the carrier;
+its name is not required to be `Unknown` or `unknown`.
+
## Reference Schemas
The examples below use two real schemas:
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/kotlin.md b/versioned_docs/version-1.7.0/compiler/generated-code/kotlin.md
index 910ddbf007c..68cae8d8b32 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/kotlin.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/kotlin.md
@@ -66,6 +66,8 @@ public data class Person(
}
```
+Empty messages generate ordinary classes with no-argument constructors.
+
Messages that participate in compiler-detected construction cycles generate
normal mutable classes so the generated serializer can publish the instance
before reading back-references:
@@ -91,7 +93,8 @@ sealed classes with `@ForyUnion`; the Fory-provided `Unknown(UnknownCase)`
carrier is marked with `@ForyUnknownCase`. The marker only selects the carrier
and does not add an entry to the schema case table. Schema-defined cases may use
case IDs `0..N` and hold a single `value` property. A typed union must have at
-least one non-`Unknown` case.
+least one schema-defined case. On a name collision, the generated carrier is named
+`Unknown_`; a second collision is an error. Schema case names are preserved.
```kotlin
package addressbook
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/python.md b/versioned_docs/version-1.7.0/compiler/generated-code/python.md
index c27120e4398..d35a456b6fd 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/python.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/python.md
@@ -70,6 +70,15 @@ class Person:
def from_bytes(cls, data: bytes) -> "Person": ...
```
+## Field Names
+
+Generated Python attributes use `snake_case`, with a trailing underscore for
+Python keywords. The names `field`, `pyfory`, `decimal`, `list`, and `dict` also
+receive a trailing underscore. Names consisting of one of these five names
+followed by underscores receive one additional underscore so fields remain
+distinct: `field`, `field_`, and `field__` become `field_`, `field__`, and
+`field___`. Field tag IDs remain unchanged.
+
## Registration
Generated registration function:
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/rust.md b/versioned_docs/version-1.7.0/compiler/generated-code/rust.md
index f150a5c9854..b546a9bc2e8 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/rust.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/rust.md
@@ -36,8 +36,10 @@ Unions map to Rust enums with `#[fory(id = ...)]` schema case attributes.
`#[fory(unknown)] Unknown(::fory::UnknownCase)` marks the Fory-provided
forward-compatibility carrier. The marker only selects the carrier and does not
add an entry to the schema case table; schema cases still use the full `0..N`
-ID range. A generated typed union must have at least one non-`Unknown` case. The
-compiler marks the first declared non-`Unknown` case as `#[fory(default)]`.
+ID range. On a name collision, the generated carrier is named `Unknown_`; a second
+collision is an error. Schema case names are preserved. A generated typed union
+must have at least one schema-defined case. The compiler marks the first declared
+schema-defined case as `#[fory(default)]`.
When that case's payload implements Rust's standard `Default` trait, the
compiler also emits a standard `Default` implementation from that case:
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/scala.md b/versioned_docs/version-1.7.0/compiler/generated-code/scala.md
index aca455deaf8..98c2301667f 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/scala.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/scala.md
@@ -101,7 +101,8 @@ forward-compatibility carrier marked with `@ForyUnknownCase`. It is omitted
from the schema case table because the marker only selects the carrier and does
not add a schema entry. Schema-defined cases use non-negative `@ForyCase` IDs.
A typed union must have at least one
-non-`Unknown` case.
+schema-defined case. On a name collision, the generated carrier is named
+`Unknown_`; a second collision is an error. Schema case names are preserved.
```scala
package addressbook
diff --git a/versioned_docs/version-1.7.0/compiler/generated-code/swift.md b/versioned_docs/version-1.7.0/compiler/generated-code/swift.md
index 7b3598f7715..1be9040ae83 100644
--- a/versioned_docs/version-1.7.0/compiler/generated-code/swift.md
+++ b/versioned_docs/version-1.7.0/compiler/generated-code/swift.md
@@ -28,10 +28,12 @@ Swift output is one `.swift` file per schema, for example:
## Type Generation
The generator creates Swift models with split model macros and stable field/case IDs.
-A typed union must include `@ForyUnknownCase case unknown(UnknownCase)` and at
-least one non-`unknown` case; `unknown(UnknownCase)` is only the
+A typed union must include a case marked `@ForyUnknownCase` and at
+least one schema-defined case; `unknown(UnknownCase)` is the default name of the
Fory-provided forward-compatibility carrier. The marker only selects the carrier
-and does not add an entry to the schema case table.
+and does not add an entry to the schema case table. On a name collision, the
+generated carrier is named `unknown_`; a second collision is an error. Schema
+case names are preserved.
When package/namespace is non-empty, namespace shaping is controlled by `swift_namespace_style`:
diff --git a/versioned_docs/version-1.7.0/grpc/csharp.md b/versioned_docs/version-1.7.0/grpc/csharp.md
index b45b057c3a6..00121bce109 100644
--- a/versioned_docs/version-1.7.0/grpc/csharp.md
+++ b/versioned_docs/version-1.7.0/grpc/csharp.md
@@ -39,7 +39,7 @@ Server project:
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.AspNetCore" Version="2.71.0" />
</ItemGroup>
```
@@ -48,7 +48,7 @@ Client project:
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
<PackageReference Include="Grpc.Core.Api" Version="2.71.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.71.0" />
</ItemGroup>
diff --git a/versioned_docs/version-1.7.0/grpc/dart.md b/versioned_docs/version-1.7.0/grpc/dart.md
index 0c62882a28c..8a94a64980e 100644
--- a/versioned_docs/version-1.7.0/grpc/dart.md
+++ b/versioned_docs/version-1.7.0/grpc/dart.md
@@ -38,7 +38,7 @@ application that compiles or runs generated service companions:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
grpc: ^4.0.0
dev_dependencies:
diff --git a/versioned_docs/version-1.7.0/grpc/rust.md b/versioned_docs/version-1.7.0/grpc/rust.md
index e6da7b5b1fc..7f67b7ca53d 100644
--- a/versioned_docs/version-1.7.0/grpc/rust.md
+++ b/versioned_docs/version-1.7.0/grpc/rust.md
@@ -37,7 +37,7 @@ to build streaming responses or request streams.
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
bytes = "1"
tonic = { version = "0.14", features = ["transport"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
diff --git a/versioned_docs/version-1.7.0/json/annotations.md b/versioned_docs/version-1.7.0/json/annotations.md
index 916ccc875c4..702407935ae 100644
--- a/versioned_docs/version-1.7.0/json/annotations.md
+++ b/versioned_docs/version-1.7.0/json/annotations.md
@@ -125,7 +125,7 @@ above.
## `JsonProperty`
-`JsonProperty` configures the canonical name, serialization index, and value inclusion of one
+`JsonProperty` configures the canonical name, serialization index, write inclusion, and read-side null handling of one
complete logical property. An annotation on a field, getter, or setter applies to the merged
field/getter/setter group.
@@ -204,6 +204,57 @@ setter-only, creator-only, or write-ignored property is invalid.
Aliases and independent read/write names are not supported.
`JsonProperty` cannot be combined with an Any logical property or declared on a `JsonAnySetter`.
+### Read-side null handling
+
+`onNullRead` controls an explicit JSON null assigned to the property. `onContentNullRead` controls
+null elements of its array or collection, or null values of its map. Both use
+`JsonProperty.NullHandling`:
+
+| Value | Behavior |
+| --------- | ---------------------------------------------------------------------------------------------------- |
+| `DEFAULT` | Inherit the corresponding builder setting. This is the annotation default. |
+| `SET` | Use normal decoding and assignment, including the declared nullability rules. |
+| `SKIP` | Consume the null and omit the assignment, element, or map insertion. |
+| `FAIL` | Reject an explicit null with `ForyJsonException`. Missing properties remain allowed by this setting. |
+
+Both builder defaults are `SET`. An explicit annotation value overrides only the matching default:
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+public final class Response {
+ @JsonProperty(onNullRead = NullHandling.SKIP, onContentNullRead = NullHandling.SKIP)
+ public java.util.List<String> seats = java.util.List.of("default");
+}
+```
+
+Reading `{"seats":null}` keeps the initialized list. Reading `{"seats":[null,"a"]}` assigns a
+list containing `"a"`; `[null]` assigns an empty list. Skipping a property does not call its setter.
+Constructor parameters follow their existing missing-property defaults and required-property
+checks. A skipped duplicate does not erase an earlier value: `{"seats":["a"],"seats":null}`
+keeps `"a"`. Constructor-bypassed objects have no initializer to preserve.
+
+`SET` preserves codec behavior: null may become `Optional.empty()`, or fail for a primitive or
+non-null Kotlin value. `SKIP` and `FAIL` act before that decoding. Only the literal JSON null is
+affected; the string `"null"` and a custom codec returning Java null for another token are not
+filtered. These options do not affect writing or change the root value's null behavior.
+
+Content overrides are shallow. For `List<List<String>>`, a property override skips null inner
+lists; elements inside retained lists follow the global setting. Map keys are unaffected, and a
+skipped duplicate map value preserves the earlier entry. Numeric byte-array representations
+support content handling; Base64 and Base16 strings do not. An explicit content setting on a
+scalar, declared `Object`, transparent wrapper, or encoded binary string is invalid.
+
+The global content setting also applies to root containers, dynamic JSON arrays/objects, and Any
+entries. Explicit null settings on an unwrapped parent are invalid; its flattened child properties
+keep their own settings. A skipped child alone does not create or mark the group present.
+
+Matching field, getter, setter, and creator declarations merge independently for each setting.
+Conflicting explicit values are rejected, and a read-side setting requires a readable property or
+creator parameter. Mixin replacement and removal happen before this merge. Complete custom
+container codecs support explicit `SET`; explicit content `SKIP` or `FAIL` requires a Fory-owned
+container representation. See [Custom codecs](custom-codecs.md).
+
## `JsonInclude` and default omission
Defaults may depend on constructor arguments, time, randomness, or external state. Being able to
@@ -268,7 +319,7 @@ object with `low=5` would restore `high=6`. Retain `high` with `ALWAYS` in that
Primitive comparisons use their values. Floating-point comparisons distinguish positive and
negative zero and retain non-finite values for normal output. Arrays compare exact array types and
contents, recursively for nested arrays; other references use `equals`. Cyclic deep comparison is
-unsupported. Reading is independent: explicit null is not missing, and mutable reference defaults
+unsupported. Reading is independent: under `onNullRead(SET)`, explicit null is not missing, and mutable reference defaults
are never shared with decoded objects.
Existing Mixins can authorize defaults without modifying a model:
@@ -637,7 +688,7 @@ configured naming strategy. Nested unwrapped properties compose their transforma
inside out.
A null child writes no members. On input, Fory creates and assigns the child only after seeing one
-of its flattened members. A completely missing group therefore preserves a mutable parent's
+of its flattened members whose value is not skipped. A completely missing group therefore preserves a mutable parent's
initializer value and leaves a record or creator argument at its normal missing-property default.
Partial input constructs the child with the ordinary defaults for its other properties.
@@ -692,7 +743,7 @@ public Map<String, Object> outputOnly;
```
During reading, an existing Map is reused. A null non-final field is initialized when the first
-unknown member is encountered. A readable final field on an ordinary mutable object must already
+unknown member whose value is not skipped is encountered. A readable final field on an ordinary mutable object must already
contain a mutable Map. Records and property-list `JsonCreator` types instead receive the accumulated
Map through their construction argument. If no unknown member is present, Fory does not initialize
a null field.
@@ -808,8 +859,8 @@ from both property-based forms and is inferred only because the target has `Json
A creator must have at least one parameter and cannot be varargs or generic. A constructor must be
public. A factory must be public and static, declare the target class as its exact return type, and
return a non-null value whose runtime class is exactly the target. Missing reference parameters use
-null, missing primitives use Java zero values, duplicate members use the last value, and explicit
-null for a primitive parameter is rejected. Records cannot declare a property-based `JsonCreator`;
+null and missing primitives use Java zero values. Duplicate members use the last value that is not
+skipped. Under `onNullRead(SET)`, explicit null for a primitive parameter is rejected. Records cannot declare a property-based `JsonCreator`;
a record with `JsonValue` may annotate its one-String canonical constructor for the value form.
## `JsonValidator`
diff --git a/versioned_docs/version-1.7.0/json/custom-codecs.md b/versioned_docs/version-1.7.0/json/custom-codecs.md
index 8e19f744dd6..efa517df0fe 100644
--- a/versioned_docs/version-1.7.0/json/custom-codecs.md
+++ b/versioned_docs/version-1.7.0/json/custom-codecs.md
@@ -109,6 +109,10 @@ ForyJson json =
.build();
```
+Factories are also consulted for `Object` elements and values of declared arrays, collections,
+and maps. A factory that claims `Object` replaces the default natural JSON value mapping for those
+occurrences.
+
A configurable factory must override `factoryKey()` with a deterministic value covering every
option that can change the created codec class, object model, or generated operations. The default
factory class name is sufficient only for a configuration-free factory.
@@ -123,9 +127,19 @@ property is omitted by `NON_NULL` or `NON_EMPTY`, the codec's write operation is
`NON_EMPTY` checks Java empty-value types directly and otherwise uses the codec's `isEmpty` method;
see [Custom empty values](#custom-empty-values). If the property is emitted, or the value
is an array element, collection element, map value, Optional value, or atomic-reference value, the
-codec receives and owns null. The registered instance is shared across concurrent operations and
+codec receives and owns null during writing. During reading, the codec owns null when the
+applicable read setting is `SET`. Property `onNullRead`
+and Fory container `onContentNullRead` settings intercept literal null before invoking a selected
+child codec when configured as `SKIP` or `FAIL`. A codec returning Java null after consuming a
+non-null token is not filtered. The registered instance is shared across concurrent operations and
must be thread-safe.
+A complete custom container codec owns its internal representation, so the global content setting
+does not alter it. For such a declared container property, explicit content `SET` delegates to the
+codec; explicit `SKIP` or `FAIL` is rejected. A complete custom object codec likewise owns the
+handling of its internal properties. Ordinary containing-property settings still apply before
+either complete codec is invoked.
+
A custom codec that materializes composite graph owners must call `JsonReader.reserveGraphMemory`
with its application-defined byte estimate before creating each owner. This applies to composite
application objects, collections, maps, and reference arrays. Reserve collection and map reference
diff --git a/versioned_docs/version-1.7.0/json/getting-started.md b/versioned_docs/version-1.7.0/json/getting-started.md
index 34d68f0460c..72b2dc4cd40 100644
--- a/versioned_docs/version-1.7.0/json/getting-started.md
+++ b/versioned_docs/version-1.7.0/json/getting-started.md
@@ -43,7 +43,7 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-json</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -57,7 +57,7 @@ repositories {
mavenCentral()
}
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
### Kotlin
@@ -66,7 +66,7 @@ Kotlin/JVM applications add the optional Kotlin JSON runtime and use its single
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
@@ -246,9 +246,10 @@ String encoded = json.toJson(users, usersType);
Declared writes require a fully bound type. Wildcards and type variables are rejected. A non-null
value must be assignable to the declared raw type.
-The declared schema controls serialization. For example, a property declared as a concrete parent
-class uses the parent's mapped properties rather than automatically adding subclass-only fields. A
-declared `Object` value uses runtime dispatch when writing and natural JSON mapping when reading.
+The declared type selects the codec. An ordinary property declared as a concrete parent class
+writes subclass-only fields when its value is a subclass; reading that JSON as the parent creates a
+parent instance and ignores those fields. A declared `Object` value uses runtime dispatch when
+writing and natural JSON mapping when reading.
### Declared types and polymorphism
diff --git a/versioned_docs/version-1.7.0/json/kotlin.md b/versioned_docs/version-1.7.0/json/kotlin.md
index 522274b0f03..efabbc4d7da 100644
--- a/versioned_docs/version-1.7.0/json/kotlin.md
+++ b/versioned_docs/version-1.7.0/json/kotlin.md
@@ -41,7 +41,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
@@ -54,7 +54,7 @@ plugins {
}
dependencies {
- ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.6")
+ ksp("org.apache.fory:fory-json-kotlin-ksp:1.7.7")
}
```
@@ -155,12 +155,20 @@ creator candidates, and a selected static factory cannot have compiler-default p
Private/protected, vararg, executable-generic, context-parameter, local,
anonymous, `inner`, or synthetic construction requires an exact application codec.
-For this model:
+With the default `onNullRead(SET)`, this model behaves as follows:
- `{"id":1}` invokes both compiler defaults.
- `{"id":1,"label":null}` passes an explicit null and does not invoke the `label` default.
- a missing `id` uses `0`.
-- `{"id":1,"retries":null}` fails; null never asks Kotlin to use a default.
+- `{"id":1,"retries":null}` fails.
+
+Use `ForyJsonKotlin.builder().onNullRead(JsonProperty.NullHandling.SKIP)` to treat a null occurrence
+as absent, preserving constructor defaults and body-property initializers. A non-null reference
+without a default remains required. Override one property with
+`@get:JsonProperty(onNullRead = JsonProperty.NullHandling.SET)` to retain ordinary null decoding.
+`onContentNullRead` handles immediate collection/array elements and map values, including unsigned
+arrays. Property overrides are shallow and skipped nulls are handled before element nullability
+checks. See [Read-side null handling](annotations.md#read-side-null-handling).
Enable `ForyJsonKotlin.builder().failOnMissingRequiredProperties(true).build()` to require ordinary
constructor properties without declared defaults, including nullable properties and numeric or
diff --git a/versioned_docs/version-1.7.0/json/object-mapping.md b/versioned_docs/version-1.7.0/json/object-mapping.md
index 717f5c85232..e11a9203f05 100644
--- a/versioned_docs/version-1.7.0/json/object-mapping.md
+++ b/versioned_docs/version-1.7.0/json/object-mapping.md
@@ -58,8 +58,14 @@ Static, transient, synthetic, and `Class<?>` fields are excluded. `getClass()` a
value type is `Class<?>` are also excluded. An annotation placed on an ineligible member is rejected
instead of being silently ignored.
-An ordinary final field can be written but is not used as a mutable read sink. Use a record,
-`JsonCreator`, or a custom codec for immutable construction.
+Eligible instance fields, including ordinary `final` fields, are restored when reading JSON.
+When a subclass hides a superclass field with the same name, the subclass field is the JSON
+property in both directions. Ignoring that field does not expose the hidden superclass field.
+
+An ordinary object property uses its declared type when reading. When writing a subclass instance
+through a concrete declared base type, Fory writes the subclass's mapped properties. Reading the
+same JSON through the base type creates a base instance and ignores subclass-only properties.
+Use `@JsonSubTypes` or a custom codec when the reader must restore the subtype.
### Field mode
@@ -118,8 +124,9 @@ without declared defaults must appear instead of receiving zero, false, or null.
defaults are introduced: a Kotlin non-null collection without a default remains required, while
a Scala collection retains its empty default.
-An explicit JSON null counts as present and continues to follow the property's type and nullability
-rules. Ignored properties, ordinary no-argument beans, and properties assigned after construction
+With the default `onNullRead(SET)`, an explicit JSON null counts as present and follows the property's
+type and nullability rules. With `SKIP`, that occurrence is omitted and cannot satisfy a required
+parameter. Ignored properties, ordinary no-argument beans, and properties assigned after construction
keep their existing behavior. Complete custom object codecs own their own missing-field rules.
This option does not change writing. If an inclusion policy omits a required property, the resulting
@@ -131,14 +138,35 @@ the option disabled.
Install `fory-json-kotlin` and use `ForyJsonKotlin.builder()` for Kotlin/JVM classes. Kotlin
ordinary and data classes use their selected constructor, exact property types, compiler defaults,
and declared nullability; they do not use Java's constructor-bypassing fallback. A default applies
-only when the member is missing. An explicit JSON null remains a present value and is rejected for
-a non-null parameter.
+when the member is missing or its null occurrence is skipped. By default, explicit JSON null is a
+present value and is rejected for a non-null parameter.
Use `jsonTypeRef<T>()` for generic, nullable, unsigned, and value-class roots. Standard arrays,
collections, and maps continue to use their normal Fory JSON representation. The complete language
type table, singleton/value-class behavior, and omission rules are in the
[Kotlin guide](kotlin.md).
+## Read-side null handling
+
+Use independent builder settings to retain existing property values and omit null container items:
+
+```java
+import org.apache.fory.json.annotation.JsonProperty.NullHandling;
+
+ForyJson json = ForyJson.builder()
+ .onNullRead(NullHandling.SKIP)
+ .onContentNullRead(NullHandling.SKIP)
+ .build();
+```
+
+Both settings default to `SET`. `FAIL` rejects an explicit null; `SKIP` omits that input occurrence.
+The builder accepts concrete modes only, not `DEFAULT` or Java null. Each built instance retains
+its own configuration. Use `@JsonProperty(onNullRead = SET)` or `onContentNullRead = SET` to opt a
+property out of the matching global rule. Content settings cover immediate collection/array elements
+and map values, including root containers and dynamic JSON trees. Property settings apply to typed
+object properties, including nested objects, and do not alter a root `null` value.
+See [annotation semantics and examples](annotations.md#read-side-null-handling).
+
## Supported Java types
The following groups have built-in mappings. Exact wire representations are stable JSON values, but
@@ -265,6 +293,8 @@ overrides `JsonInclude` on the class, which overrides the builder default. See
| `byteArrayFormat(JsonByteArray.Format)` | `BASE64` | Default byte-array representation for reading and writing |
| `withCodegen(boolean)` | `true` | Enable generated object codecs |
| `withAsyncCompilation(boolean)` | `true` | Compile generated codecs asynchronously |
+| `onNullRead(NullHandling)` | `SET` | Handle explicit null property values |
+| `onContentNullRead(NullHandling)` | `SET` | Handle null array/collection elements and map values |
| `withFieldMode(boolean)` | `false` | When true, discover fields without getters/setters |
| `withPropertyNamingStrategy(strategy)` | `LOWER_CAMEL_CASE` | Name properties without an explicit `JsonProperty` name |
| `withMaxCachedFieldNames(int)` | `DEFAULT_MAX_CACHED_FIELD_NAMES` (`8192`) | Field-name cache entries per reader; zero disables caching |
diff --git a/versioned_docs/version-1.7.0/json/scala.md b/versioned_docs/version-1.7.0/json/scala.md
index ee9dab49bdd..2fc1509cb99 100644
--- a/versioned_docs/version-1.7.0/json/scala.md
+++ b/versioned_docs/version-1.7.0/json/scala.md
@@ -25,7 +25,7 @@ module works on the ordinary JVM and GraalVM Native Image. Android is not suppor
## Setup
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-json-scala" % "1.7.7"
```
`ForyJsonScala.builder()` installs the Scala module and returns the standard Fory JSON builder:
@@ -101,9 +101,15 @@ rejects `{}`, while `case class Request(id: Int = 7)` still reads it as `Request
collection, map, and array properties retain their existing missing-value defaults. The option is
disabled by default and does not change writing or explicit null handling.
-Explicit constructor defaults take precedence for omitted properties. An explicit JSON `null`
+Explicit constructor defaults take precedence for omitted properties. With the default `onNullRead(SET)`, JSON `null`
decodes as `None` for `Option[A]`, even when its constructor default is `Some(...)`.
+Use `ForyJsonScala.builder().onNullRead(JsonProperty.NullHandling.SKIP)` to skip null property
+occurrences and retain constructor defaults or body-property initializers. `onContentNullRead`
+applies to immediate elements and map values of supported strict Scala collections, including
+primitive collections. Per-property `JsonProperty` settings override the matching global default
+and do not propagate into nested containers. See [Read-side null handling](annotations.md#read-side-null-handling).
+
A case class may be declared at the top level, or inside an `object` at any nesting depth, as long
as every enclosing scope is itself an `object`. A case class enclosed by a `class`, a trait, or a
method is rejected for both reading and writing, because Fory cannot reach the enclosing instance
@@ -130,7 +136,7 @@ or values. All other Fory JSON annotations retain the behavior described in
Property inclusion controls which values are written. Omitted properties use constructor or type
defaults when read, so omitting an empty string can restore `null`. Use `ALWAYS` when those values
-must remain distinct. An explicit JSON `null` keeps the declared type's normal null behavior; it
+must remain distinct. Under `onNullRead(SET)`, JSON `null` keeps the declared type's normal null behavior; it
does not request a constructor default.
`NON_EMPTY` recognizes `None` and supported empty strict Scala sequences, sets, and maps, including
diff --git a/versioned_docs/version-1.7.0/object-serialization/cpp/index.md b/versioned_docs/version-1.7.0/object-serialization/cpp/index.md
index 4112b645055..4a3a8d08c2e 100644
--- a/versioned_docs/version-1.7.0/object-serialization/cpp/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/cpp/index.md
@@ -62,7 +62,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
@@ -92,11 +92,11 @@ module(
bazel_dep(name = "rules_cc", version = "0.1.1")
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
git_override(
module_name = "fory",
remote = "https://github.com/apache/fory.git",
- commit = "v1.7.6", # Or use a specific commit hash for reproducibility
+ commit = "v1.7.7", # Or use a specific commit hash for reproducibility
)
```
@@ -128,7 +128,7 @@ bazel run //:my_app
For local development, you can use `local_path_override` instead:
```bazel
-bazel_dep(name = "fory", version = "1.7.6")
+bazel_dep(name = "fory", version = "1.7.7")
local_path_override(
module_name = "fory",
path = "/path/to/fory",
diff --git a/versioned_docs/version-1.7.0/object-serialization/csharp/index.md b/versioned_docs/version-1.7.0/object-serialization/csharp/index.md
index 6d6b76c337e..cae69403350 100644
--- a/versioned_docs/version-1.7.0/object-serialization/csharp/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/csharp/index.md
@@ -46,7 +46,7 @@ Reference the single `Apache.Fory` package. It includes the Fory library and the
```xml
<ItemGroup>
- <PackageReference Include="Apache.Fory" Version="1.7.6" />
+ <PackageReference Include="Apache.Fory" Version="1.7.7" />
</ItemGroup>
```
diff --git a/versioned_docs/version-1.7.0/object-serialization/csharp/schema-metadata.md b/versioned_docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
index c555671441b..fcec22f1a34 100644
--- a/versioned_docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
+++ b/versioned_docs/version-1.7.0/object-serialization/csharp/schema-metadata.md
@@ -122,9 +122,9 @@ Generated union cases use `[ForyCase]` for both the stable case ID and optional
case payload schema type. Do not put `[ForyField]` on union case payload
members. Known case record names use PascalCase FDL case names; payload types
use qualified references when needed to avoid name conflicts. A typed union must
-declare at least one non-`Unknown` case; `Unknown(UnknownCase)` is only the
-Fory-owned forward-compatibility carrier. The marker only selects the carrier and
-does not add an entry to the schema case table.
+declare at least one schema-defined case and exactly one `[ForyUnknownCase]`
+case exposing `Value: UnknownCase`. The carrier name is unrestricted. The marker
+only selects the carrier and does not add an entry to the schema case table.
```csharp
using Apache.Fory;
diff --git a/versioned_docs/version-1.7.0/object-serialization/dart/index.md b/versioned_docs/version-1.7.0/object-serialization/dart/index.md
index 2e737dafc2a..072ac42620d 100644
--- a/versioned_docs/version-1.7.0/object-serialization/dart/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/dart/index.md
@@ -47,7 +47,7 @@ Add the dependency to your `pubspec.yaml`:
```yaml
dependencies:
- fory: ^1.7.6
+ fory: ^1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/versioned_docs/version-1.7.0/object-serialization/java/index.md b/versioned_docs/version-1.7.0/object-serialization/java/index.md
index 200391d3095..41a0134364e 100644
--- a/versioned_docs/version-1.7.0/object-serialization/java/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/java/index.md
@@ -63,7 +63,7 @@ or later.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
@@ -71,7 +71,7 @@ or later.
```kotlin
// Binary object serialization
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
#### JDK 25 and Later
diff --git a/versioned_docs/version-1.7.0/object-serialization/kotlin/index.md b/versioned_docs/version-1.7.0/object-serialization/kotlin/index.md
index 6e9f7c3b8bd..894ae92503e 100644
--- a/versioned_docs/version-1.7.0/object-serialization/kotlin/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/kotlin/index.md
@@ -53,14 +53,14 @@ See [Java Features](../java/index.md#features) for complete feature list.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:1.7.6")
+implementation("org.apache.fory:fory-kotlin:1.7.7")
```
### JDK25+
diff --git a/versioned_docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md b/versioned_docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
index fe42f884b1d..440f7e71c50 100644
--- a/versioned_docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
+++ b/versioned_docs/version-1.7.0/object-serialization/kotlin/static-generated-serializers.md
@@ -224,7 +224,8 @@ one constructor property named `value`. `Unknown(UnknownCase)` is marked with
`@ForyUnknownCase` as the Fory-owned forward-compatibility carrier. It is
omitted from the schema case table because the marker only selects the carrier
and does not add a schema entry. A typed union must declare at least one
-non-`Unknown` case:
+schema-defined case. Exactly one case must carry `@ForyUnknownCase`; its name is
+unrestricted:
```kotlin
package example
diff --git a/versioned_docs/version-1.7.0/object-serialization/rust/basic-serialization.md b/versioned_docs/version-1.7.0/object-serialization/rust/basic-serialization.md
index e25539885c5..c2e2fe1f3dd 100644
--- a/versioned_docs/version-1.7.0/object-serialization/rust/basic-serialization.md
+++ b/versioned_docs/version-1.7.0/object-serialization/rust/basic-serialization.md
@@ -147,7 +147,7 @@ let later = timestamp.checked_add_duration(duration)?;
```toml
[dependencies]
-fory = { version = "1.7.6", features = ["chrono"] }
+fory = { version = "1.7.7", features = ["chrono"] }
```
### Custom Types
diff --git a/versioned_docs/version-1.7.0/object-serialization/rust/index.md b/versioned_docs/version-1.7.0/object-serialization/rust/index.md
index 4c1cf50092b..37632e35117 100644
--- a/versioned_docs/version-1.7.0/object-serialization/rust/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/rust/index.md
@@ -37,9 +37,9 @@ The Rust implementation provides versatile and high-performance serialization wi
| Crate | Description | Version |
| --------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------- |
-| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, public Fory types, and derive macros | [1.7.6](https://crates.io/crates/fory) |
-| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level core crate for advanced integrations | [1.7.6](https://crates.io/crates/fory-core) |
-| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macro crate for direct derive-macro use | [1.7.6](https://crates.io/crates/fory-derive) |
+| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, public Fory types, and derive macros | [1.7.7](https://crates.io/crates/fory) |
+| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level core crate for advanced integrations | [1.7.7](https://crates.io/crates/fory-core) |
+| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macro crate for direct derive-macro use | [1.7.7](https://crates.io/crates/fory-derive) |
Most applications should depend on `fory` only. It re-exports the derive
macros and the public Fory types needed by generated code. Use `fory-core`
@@ -52,7 +52,7 @@ Add Apache Fory™ to your `Cargo.toml`:
```toml
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
### Basic Example
diff --git a/versioned_docs/version-1.7.0/object-serialization/scala/basic-serialization.md b/versioned_docs/version-1.7.0/object-serialization/scala/basic-serialization.md
index c1768d45e56..d4d38ab44fa 100644
--- a/versioned_docs/version-1.7.0/object-serialization/scala/basic-serialization.md
+++ b/versioned_docs/version-1.7.0/object-serialization/scala/basic-serialization.md
@@ -164,9 +164,9 @@ output mode cannot express a legal qualifier for a conflict, the IDL compiler
appends `Case` to the generated case name.
Schema-defined union cases use non-negative IDs, and a typed union must declare
-at least one non-`Unknown` case. The Scala unknown-case carrier is selected by
-`@ForyUnknownCase`, not by a schema case ID. Its payload stores the original case
-ID and the deserialized value. When a reader sees a newer case ID, it returns
+at least one schema-defined case. The Scala unknown-case carrier is selected by
+`@ForyUnknownCase`, independent of its name, and has no schema case ID. Its payload
+stores the original case ID and the deserialized value. When a reader sees a newer case ID, it returns
`Unknown(UnknownCase)` instead of failing solely because the case ID is not known
locally.
diff --git a/versioned_docs/version-1.7.0/object-serialization/scala/index.md b/versioned_docs/version-1.7.0/object-serialization/scala/index.md
index fdf64a96c20..2aecbbf8e9f 100644
--- a/versioned_docs/version-1.7.0/object-serialization/scala/index.md
+++ b/versioned_docs/version-1.7.0/object-serialization/scala/index.md
@@ -49,7 +49,7 @@ See [Java Features](../java/index.md#features) for complete feature list.
Add the dependency with sbt:
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
### JDK25+
diff --git a/versioned_docs/version-1.7.0/object-serialization/scala/schema-metadata.md b/versioned_docs/version-1.7.0/object-serialization/scala/schema-metadata.md
index 151c8cdb616..d360a98acd0 100644
--- a/versioned_docs/version-1.7.0/object-serialization/scala/schema-metadata.md
+++ b/versioned_docs/version-1.7.0/object-serialization/scala/schema-metadata.md
@@ -108,8 +108,8 @@ enum SearchTarget derives ForySerializer {
```
Schema-defined union cases use non-negative IDs, and a typed union must declare
-at least one non-`Unknown` case. The unknown-case carrier is selected by
-`@ForyUnknownCase`, not by a schema case ID.
+at least one schema-defined case. The unknown-case carrier is selected by
+`@ForyUnknownCase`, independent of its name, and has no schema case ID.
When a generated Scala union case name matches the payload type simple name,
packaged output keeps the case name and qualifies the payload type. If a target
output mode cannot express a legal qualifier for a conflict, the IDL compiler
diff --git a/versioned_docs/version-1.7.0/object-serialization/swift/schema-metadata.md b/versioned_docs/version-1.7.0/object-serialization/swift/schema-metadata.md
index 2a216e4f7b6..59d22014312 100644
--- a/versioned_docs/version-1.7.0/object-serialization/swift/schema-metadata.md
+++ b/versioned_docs/version-1.7.0/object-serialization/swift/schema-metadata.md
@@ -200,8 +200,9 @@ External payloads select a serializer with `.with(...)`:
case user(ThirdParty.User)
```
-Every `@ForyUnion` must declare `@ForyUnknownCase case unknown(UnknownCase)` and
-at least one non-`unknown` case. The unknown case is only the Fory-owned
+Every `@ForyUnion` must declare exactly one `@ForyUnknownCase` case with one
+`UnknownCase` associated value and at least one schema-defined case. The marked
+case name is unrestricted. The unknown case is only the Fory-owned
forward-compatibility carrier and cannot be the default value source. It is
omitted from the schema case table because the marker only selects the carrier
and does not add a schema entry. Schema cases use non-negative IDs.
diff --git a/versioned_docs/version-1.7.0/row-format/java.md b/versioned_docs/version-1.7.0/row-format/java.md
index 835f352e3be..cb9f57560db 100644
--- a/versioned_docs/version-1.7.0/row-format/java.md
+++ b/versioned_docs/version-1.7.0/row-format/java.md
@@ -43,14 +43,14 @@ For Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-format</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
For Gradle:
```kotlin
-implementation("org.apache.fory:fory-format:1.7.6")
+implementation("org.apache.fory:fory-format:1.7.7")
```
## Basic Usage
diff --git a/versioned_docs/version-1.7.0/start/cpp.md b/versioned_docs/version-1.7.0/start/cpp.md
index 93a1c3fff17..4dc8d7c3d33 100644
--- a/versioned_docs/version-1.7.0/start/cpp.md
+++ b/versioned_docs/version-1.7.0/start/cpp.md
@@ -45,7 +45,7 @@ include(FetchContent)
FetchContent_Declare(
fory
GIT_REPOSITORY https://github.com/apache/fory.git
- GIT_TAG v1.7.6
+ GIT_TAG v1.7.7
SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(fory)
diff --git a/versioned_docs/version-1.7.0/start/csharp.md b/versioned_docs/version-1.7.0/start/csharp.md
index a47d9b8c248..b0b37344345 100644
--- a/versioned_docs/version-1.7.0/start/csharp.md
+++ b/versioned_docs/version-1.7.0/start/csharp.md
@@ -36,7 +36,7 @@ Create a console project and add the released package:
```bash
dotnet new console -n ForyExample
cd ForyExample
-dotnet add package Apache.Fory --version 1.7.6
+dotnet add package Apache.Fory --version 1.7.7
```
Replace `Program.cs` with:
diff --git a/versioned_docs/version-1.7.0/start/dart.md b/versioned_docs/version-1.7.0/start/dart.md
index dc4c3afbc4f..34a5ae1febe 100644
--- a/versioned_docs/version-1.7.0/start/dart.md
+++ b/versioned_docs/version-1.7.0/start/dart.md
@@ -36,7 +36,7 @@ Add Fory and the generator to `pubspec.yaml`:
```yaml
dependencies:
- fory: 1.7.6
+ fory: 1.7.7
dev_dependencies:
build_runner: ^2.4.0
diff --git a/versioned_docs/version-1.7.0/start/go.md b/versioned_docs/version-1.7.0/start/go.md
index efa03140b03..d9deb503b62 100644
--- a/versioned_docs/version-1.7.0/start/go.md
+++ b/versioned_docs/version-1.7.0/start/go.md
@@ -38,7 +38,7 @@ Create a module and install the released Fory module:
mkdir fory-example
cd fory-example
go mod init example.com/fory-example
-go get github.com/apache/fory/go/fory@v1.7.6
+go get github.com/apache/fory/go/fory@v1.7.7
```
If a Go proxy has not picked up a new submodule tag yet, retry later or use
diff --git a/versioned_docs/version-1.7.0/start/java.md b/versioned_docs/version-1.7.0/start/java.md
index 9bd5f221652..8912b9d0643 100644
--- a/versioned_docs/version-1.7.0/start/java.md
+++ b/versioned_docs/version-1.7.0/start/java.md
@@ -44,14 +44,14 @@ Maven:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>1.7.6</version>
+ <version>1.7.7</version>
</dependency>
```
Gradle:
```kotlin
-implementation("org.apache.fory:fory-core:1.7.6")
+implementation("org.apache.fory:fory-core:1.7.7")
```
Run this complete xlang round trip:
@@ -97,7 +97,7 @@ Fory JSON maps Java objects to standard JSON text and UTF-8 bytes. Add
`fory-json` instead of `fory-core` when the application only needs JSON:
```kotlin
-implementation("org.apache.fory:fory-json:1.7.6")
+implementation("org.apache.fory:fory-json:1.7.7")
```
Add the import to `ForyExample.java`:
diff --git a/versioned_docs/version-1.7.0/start/javascript.md b/versioned_docs/version-1.7.0/start/javascript.md
index 3dd7e711e2b..b1b926d8def 100644
--- a/versioned_docs/version-1.7.0/start/javascript.md
+++ b/versioned_docs/version-1.7.0/start/javascript.md
@@ -36,7 +36,7 @@ npm --version
Install the core package:
```bash
-npm install @apache-fory/core@1.7.6
+npm install @apache-fory/core@1.7.7
```
Define a schema and run an xlang round trip:
@@ -72,7 +72,7 @@ JavaScript uses xlang mode. Continue with
For the optional Node.js string fast path, install the matching package version:
```bash
-npm install @apache-fory/core@1.7.6 @apache-fory/hps@1.7.6
+npm install @apache-fory/core@1.7.7 @apache-fory/hps@1.7.7
```
## Other Capabilities
diff --git a/versioned_docs/version-1.7.0/start/kotlin.md b/versioned_docs/version-1.7.0/start/kotlin.md
index faa65bd945c..1ad5c966b53 100644
--- a/versioned_docs/version-1.7.0/start/kotlin.md
+++ b/versioned_docs/version-1.7.0/start/kotlin.md
@@ -44,7 +44,7 @@ repositories {
}
dependencies {
- implementation("org.apache.fory:fory-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-kotlin:1.7.7")
}
```
@@ -88,7 +88,7 @@ module when interoperating with ordinary JSON APIs, browsers, logs, or other JSO
```kotlin title="build.gradle.kts"
dependencies {
- implementation("org.apache.fory:fory-json-kotlin:1.7.6")
+ implementation("org.apache.fory:fory-json-kotlin:1.7.7")
}
```
diff --git a/versioned_docs/version-1.7.0/start/python.md b/versioned_docs/version-1.7.0/start/python.md
index e3a6e9aeae6..3c78c88275b 100644
--- a/versioned_docs/version-1.7.0/start/python.md
+++ b/versioned_docs/version-1.7.0/start/python.md
@@ -35,7 +35,7 @@ python -m pip --version
Install the released package:
```bash
-python -m pip install pyfory==1.7.6
+python -m pip install pyfory==1.7.7
```
Run an xlang round trip:
diff --git a/versioned_docs/version-1.7.0/start/rust.md b/versioned_docs/version-1.7.0/start/rust.md
index 4792e80b6e0..85c2ff62ebc 100644
--- a/versioned_docs/version-1.7.0/start/rust.md
+++ b/versioned_docs/version-1.7.0/start/rust.md
@@ -36,7 +36,7 @@ Add the public crate:
```toml title="Cargo.toml"
[dependencies]
-fory = "1.7.6"
+fory = "1.7.7"
```
```rust
diff --git a/versioned_docs/version-1.7.0/start/scala.md b/versioned_docs/version-1.7.0/start/scala.md
index 2048de39a8d..5e785a0f501 100644
--- a/versioned_docs/version-1.7.0/start/scala.md
+++ b/versioned_docs/version-1.7.0/start/scala.md
@@ -37,7 +37,7 @@ Add the Fory Scala library to `build.sbt`:
```sbt
ThisBuild / scalaVersion := "3.3.1"
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.6"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.7"
```
Create `src/main/scala/ScalaExample.scala`:
diff --git a/versioned_docs/version-1.7.0/start/swift.md b/versioned_docs/version-1.7.0/start/swift.md
index b72a56862a5..97885c8868a 100644
--- a/versioned_docs/version-1.7.0/start/swift.md
+++ b/versioned_docs/version-1.7.0/start/swift.md
@@ -42,7 +42,7 @@ Add the released package and depend on its `Fory` library in the generated `Pack
```swift title="Package.swift"
dependencies: [
- .package(url: "https://github.com/apache/fory.git", exact: "1.7.6")
+ .package(url: "https://github.com/apache/fory.git", exact: "1.7.7")
],
targets: [
.executableTarget(
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org