From 830632a54af3aed39d063422549eb4b7c21ef356 Mon Sep 17 00:00:00 2001
From: Casey Clements <casey.clements@mongodb.com>
Date: Fri, 20 Sep 2024 10:27:14 -0400
Subject: [PATCH] Added README.md for Binary Vector tests

---
 source/bson-binary-vector/tests/README.md | 40 +++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/source/bson-binary-vector/tests/README.md b/source/bson-binary-vector/tests/README.md
index e69de29bb2..b217705ee8 100644
--- a/source/bson-binary-vector/tests/README.md
+++ b/source/bson-binary-vector/tests/README.md
@@ -0,0 +1,40 @@
+# Testing Binary subtype 9: Vector
+
+The JSON files in this directory tree are platform-independent tests that drivers can use to prove their conformance to
+the specification.
+
+These tests focus on the roundtrip of the list numbers as input/output, along with their data type and byte padding.
+
+Additional tests exist in `bson_corpus/tests/binary.json` but do not sufficiently test the end-to-end process of Vector
+to BSON. For this reason, drivers must create a bespoke test runner for the vector subtype.
+
+Each test case here pertains to a single vector. The inputs required to create the Binary BSON object are defined, and
+when valid, the Canonical BSON and Extended JSON representations are included for comparison.
+
+## Version
+
+Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version.
+
+## Format
+
+#### Top level keys
+
+Each JSON file contains three top-level keys.
+
+- `description`: human-readable description of what is in the file
+- `test_key`: Field name used when decoding/encoding a BSON document containing the single BSON Binary for the test
+  case. Applies to *every* case.
+- `tests`: array of test case objects, each of which have the following keys. Valid cases will also contain additional
+  binary and json encoding values.
+
+#### Keys of tests objects
+
+- `description`: string describing the test.
+- `valid`: boolean indicating if the vector, dtype, and padding should be considered a valid input.
+- `vector`: list of numbers
+- `dtype_hex`: string defining the data type in hex (e.g. "0x10", "0x27")
+- `dtype_alias`: (optional) string defining the data dtype, perhaps as Enum.
+- `padding`: (optional) integer for byte padding. Defaults to 0.
+- `canonical_bson`: (required if valid is true) an (uppercase) big-endian hex representation of a BSON byte string.
+- `canonical_extjson`: (required if valid is true) string containing a Canonical Extended JSON document. Because this is
+  itself embedded as a *string* inside a JSON document, characters like quote and backslash are escaped.