From 1d9d997cf9d026932186f5a71fa0fcb538798c7a Mon Sep 17 00:00:00 2001
From: Devon Powell <Devon.Powell@D2L.com>
Date: Thu, 21 May 2026 17:51:49 -0400
Subject: [PATCH] Add documentation for report configuration schema

---
 README.md                           | 26 ++++++++++++----------
 docs/report-configuration-format.md | 34 +++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 12 deletions(-)
 create mode 100644 docs/report-configuration-format.md

diff --git a/README.md b/README.md
index 00d2181..e76f4a2 100644
--- a/README.md
+++ b/README.md
@@ -201,14 +201,15 @@ If your test framework isn't supported by the built-in reporters, you can build
 
 See the [ReportBuilder Guide](./docs/report-builder-guide.md) for a complete walkthrough of creating a custom reporter for any test framework.
 
-### Configuration
+## Report Configuration
 
 To have the test type, experience and tool mapped to test code, a D2L test
 reporting configuration file is required when using one of the reporters
 provided in this package.
 
 Below are examples of how to create the config file. Note that the `type` field
-will end up as lowercase in the report.
+will end up as lowercase in the report. For details on the schema that the
+report configuration file follows, see [Report Configuration Format].
 
 Please see [Automated Testing Definitions] on Confluence for the list of test
 types that should be used when creating the D2L test reporting configuration
@@ -218,7 +219,7 @@ file.
 {
   "type": "UI Visual Diff",
   "experience": "Experience",
-  "tool": "Tool",
+  "tool": "Tool"
 }
 ```
 
@@ -227,19 +228,19 @@ file.
   "type": "UI E2E",
   "overrides": [
     {
-      "pattern": "tests/account-settings/**/*",
-      "experience": "Administration",
-      "tool": "Account Settings"
+      "pattern": "tests/feature-a/**/*",
+      "experience": "Experience A",
+      "tool": "Feature A"
     },
     {
-      "pattern": "tests/announcements/**/*",
-      "experience": "Teaching & Learning",
-      "tool": "Announcements"
+      "pattern": "tests/feature-b/**/*",
+      "experience": "Experience B",
+      "tool": "Feature B"
     },
     {
-      "pattern": "tests/rubrics.test.js",
-      "experience": "Assessment",
-      "tool": "Rubrics"
+      "pattern": "tests/feature-c.test.js",
+      "experience": "Experience C",
+      "tool": "Feature C"
     }
   ]
 }
@@ -335,3 +336,4 @@ refer to the [semantic-release GitHub Action] documentation.
 [#test-reporting]: https://d2l.slack.com/archives/C05MMC7H7EK
 [semantic-release GitHub Action]: https://github.com/BrightspaceUI/actions/tree/main/semantic-release
 [Report Format]: ./docs/report-format.md
+[Report Configuration Format]: ./docs/report-configuration-format.md
diff --git a/docs/report-configuration-format.md b/docs/report-configuration-format.md
new file mode 100644
index 0000000..c7c2d76
--- /dev/null
+++ b/docs/report-configuration-format.md
@@ -0,0 +1,34 @@
+# Report Configuration Format
+
+The report configuration file is consumed by the custom test reporters provided
+by this package. It maps test taxonomy to test files via glob patterns, and
+lists patterns to ignore when generating a report.
+
+> [!NOTE]
+> All JSON below is simply a pseudo representation of the actual schemas which
+> are stored in the [`schemas`](../schemas) folder.
+
+## Current
+
+```json
+{
+  "type": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>",
+  "tool": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>",
+  "experience": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>",
+  "ignorePatterns": [
+    "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$'>"
+  ],
+  "overrides": [
+    {
+      "pattern": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$'>",
+      "type": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>",
+      "tool": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>",
+      "experience": "<Non-empty string matching pattern '^(?!\\s).+(?<!\\s)$', optional>"
+    }
+  ]
+}
+```
+
+If `type` is omitted at the top level then every entry in `overrides` must
+specify `type`. The same rule applies to `tool` and `experience`. If all three
+are omitted at the top level then `overrides` is required.