From 01853ed6bcf9ebe88ec2e248ea757b86417b1487 Mon Sep 17 00:00:00 2001
From: whn <142425816+Whning0513@users.noreply.github.com>
Date: Tue, 25 Aug 2026 14:18:50 +0800
Subject: [PATCH] docs: document lenient BSON input handling (#5333)

Signed-off-by: whn <142425816+Whning0513@users.noreply.github.com>
---
 docs/mkdocs/docs/features/binary_formats/bson.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/mkdocs/docs/features/binary_formats/bson.md b/docs/mkdocs/docs/features/binary_formats/bson.md
index 8c1112e84..95c82e873 100644
--- a/docs/mkdocs/docs/features/binary_formats/bson.md
+++ b/docs/mkdocs/docs/features/binary_formats/bson.md
@@ -98,6 +98,17 @@ The library maps BSON record types to JSON value types as follows:
     This library deserializes BSON type `0x11` (Timestamp) as a `number_unsigned` value. The 64-bit value is preserved,
     but the Timestamp type information is not.
 
+!!! warning "Lenient BSON input handling"
+
+    The BSON reader is lenient in a few areas where the BSON specification is more restrictive:
+
+    - array element keys are not checked against the required decimal sequence (`0`, `1`, `2`, ...),
+    - any non-zero byte is accepted as `true` for the boolean type, and
+    - the payload for binary subtype `0x02` is returned as-is, including its inner length prefix.
+
+    If BSON input must be validated for strict specification compliance, validate it separately before passing it to
+    `from_bson()`.
+
 ??? example
 
     ```cpp