DRIVERS-2789 Convert URI Options Spec to Markdown

source/connection-string/connection-string-spec.md

@@ -232,8 +232,7 @@ Unsupported value for "fsync" : "ifPossible"
 ### Repeated Keys
 
 If a key is repeated and the corresponding data type is not a List then the precedence of which key value pair will be
-used is undefined except where defined otherwise by the
-[URI options spec](https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.rst).
+used is undefined except where defined otherwise by the [URI options spec](../uri-options/uri-options.md).
 
 Where possible, a warning SHOULD be raised to inform the user that multiple options were found for the same value.
 

source/index.md

@@ -32,5 +32,6 @@
 - [Server Monitoring](server-discovery-and-monitoring/server-monitoring.md)
 - [Server Selection](server-selection/server-selection.md)
 - [Server Selection Test Plan](server-selection/server-selection-tests.md)
+- [URI Options Specification](uri-options/uri-options.md)
 - [Unified Test Format](unified-test-format/unified-test-format.md)
 - [Wire Compression in Drivers](compression/OP_COMPRESSED.md)

source/initial-dns-seedlist-discovery/tests/README.md

@@ -92,7 +92,7 @@ These YAML and JSON files contain the following fields:
 - `hosts`: the discovered topology's list of hosts once SDAM completes a scan
 - `numHosts`: the expected number of hosts discovered once SDAM completes a scan. This is mainly used to test
  `srvMaxHosts`, since randomly selected hosts cannot be deterministically asserted.
-- `options`: the parsed [URI options](../../uri-options/uri-options.rst) as discovered from the
+- `options`: the parsed [URI options](../../uri-options/uri-options.md) as discovered from the
  [Connection String](../../connection-string/connection-string-spec.md)'s "Connection Options" component and SRV
  resolution (e.g. TXT records, implicit `tls` default).
 - `parsed_options`: additional, parsed options from other

source/ocsp-support/tests/README.rst

@@ -14,7 +14,7 @@ drivers can use to prove their conformance to the OCSP Support
 specification. These tests MUST BE implemented by all drivers.
 
 Additional YAML and JSON tests have also been added to the `URI
-Options Tests <../../uri-options/tests/README.rst>`__. Specifically,
+Options Tests <../../uri-options/tests/README.md>`__. Specifically,
 the `TLS Options Test <../../uri-options/tests/tls-options.yml>`__ has
 been updated with additional tests for the new URI options
 ``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck``.

source/unified-test-format/unified-test-format.md

@@ -409,13 +409,13 @@ The structure of this object is as follows:
  - `uriOptions`: Optional object. Additional URI options to apply to the test suite's connection string that is used to
  create this client. Any keys in this object MUST override conflicting keys in the connection string.
 
- Documentation for supported options may be found in the [URI Options](../uri-options/uri-options.rst) spec, with one
+ Documentation for supported options may be found in the [URI Options](../uri-options/uri-options.md) spec, with one
  notable exception: if `readPreferenceTags` is specified in this object, the key will map to an array of strings,
  each representing a tag set, since it is not feasible to define multiple `readPreferenceTags` keys in the object.
 
  Note also that when specifying `directConnection` as true, the connection string used to instantiate a client MUST
  only have a single seed and MUST NOT specify the `replicaSet` option. See the
- [URI Options spec](../uri-options/uri-options.rst#directconnection-uri-option-with-multiple-seeds-or-srv-uri) for
+ [URI Options spec](../uri-options/uri-options.md#directconnection-uri-option-with-multiple-seeds-or-srv-uri) for
  more information.
 
  Any field in `uriOptions` may be a [$$placeholder](#placeholder) document and the test runner MUST support replacing

source/uri-options/tests/README.md

@@ -0,0 +1,43 @@
+# URI Options Tests
+
+The YAML and JSON files in this directory tree are platform-independent tests that drivers can use to prove their
+conformance to the URI Options spec.
+
+These tests use the same format as the Connection String spec tests.
+
+## Version
+
+Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version.
+
+## Format
+
+Each YAML file contains an object with a single `tests` key. This key is an array of test case objects, each of which
+have the following keys:
+
+- `description`: A string describing the test.
+- `uri`: A string containing the URI to be parsed.
+- `valid`: A boolean indicating if the URI should be considered valid.
+- `warning`: A boolean indicating whether URI parsing should emit a warning.
+- `hosts`: Included for compatibility with the Connection String spec tests. This will always be `~`.
+- `auth`: Included for compatibility with the Connection String spec tests. This will always be `~`.
+- `options`: An object containing key/value pairs for each parsed query string option.
+
+If a test case includes a null value for one of these keys (e.g. `auth: ~`, `hosts: ~`), no assertion is necessary. This
+both simplifies parsing of the test files (keys should always exist) and allows flexibility for drivers that might
+substitute default values *during* parsing (e.g. omitted `hosts` could be parsed as `["localhost"]`).
+
+The `valid` and `warning` fields are boolean in order to keep the tests flexible. We are not concerned with asserting
+the format of specific error or warnings messages strings.
+
+Under normal circumstances, it should not be necessary to specify both `valid: false` and `warning: true`. Typically, a
+URI test case will either yield an error (e.g. options conflict) or a warning (e.g. invalid type or value for an
+option), but not both.
+
+### Use as unit tests
+
+Testing whether a URI is valid or not requires testing whether URI parsing (or MongoClient construction) causes a
+warning due to a URI option being invalid and asserting that the options parsed from the URI match those listed in the
+`options` field.
+
+Note that there are tests for each of the options marked as optional; drivers will need to implement logic to skip over
+the optional tests that they don't implement.