allow for multi-file spec formats

CONTRIBUTING.md

@@ -20,13 +20,25 @@ that address issues outside the core GraphQL specifications.
 
 Each `GAP-NNNN` folder must include:
 
-- `DRAFT.md` — the working document of the proposal/specification, written in
-  [`spec-md`](https://spec-md.com/) format
+- `DRAFT.md` or `DRAFT/` — the working document of the proposal/specification,
+  written in [`spec-md`](https://spec-md.com/) format (see below)
 - `README.md` — a brief overview, why it exists, current status, challenges,
   drawbacks, and related resources/prior art (written in GitHub Flavoured
   Markdown)
 - `metadata.yml` — maintainers, status, and related metadata
 
+#### Single-file vs split-file format
+
+Specifications may be authored as either:
+
+- **Single-file**: A single `DRAFT.md` file containing the entire specification.
+- **Split-file**: A `DRAFT/` directory with an `Index.md` entry point that may
+  include other files. This is useful for larger specifications that benefit
+  from being organized into multiple sections.
+
+For split-file specs, the `DRAFT/index.md` file serves as the main entry point
+and should use spec-md's import syntax to include other files as needed.
+
 #### `metadata.yml`
 
 Required fields:
@@ -67,11 +79,15 @@ by the TSC. The authors are responsible for guiding contribution to the GAP.
 
 ### Versioning
 
-To release a version of a GAP, copy the current `DRAFT.md` into a `versions`
-folder named for the year and month of release:
+To release a version of a GAP, copy the current draft into a `versions` folder
+named for the year and month of release:
 
 ```bash
+# Single-file format
 cp GAP-NNNN/DRAFT.md GAP-NNNN/versions/YYYY-MM.md
+
+# Split-file format
+cp -r GAP-NNNN/DRAFT GAP-NNNN/versions/YYYY-MM
 ```
 
 Rules:

scripts/validate-structure.js

@@ -58,6 +58,28 @@ function validateReadmeExists(dirPath, gapName) {
   }
 }
 
+function validateDraftExists(dirPath, gapName) {
+  const draftFilePath = join(dirPath, "DRAFT.md");
+  const draftDirPath = join(dirPath, "DRAFT");
+  const draftIndexPath = join(draftDirPath, "Index.md");
+
+  const hasDraftFile = existsSync(draftFilePath);
+  const hasDraftDir = existsSync(draftDirPath) && statSync(draftDirPath).isDirectory();
+  const hasDraftIndex = hasDraftDir && existsSync(draftIndexPath);
+
+  if (!hasDraftFile && !hasDraftDir) {
+    error(gapName, "No DRAFT.md file or DRAFT/ directory found");
+  }
+
+  if (hasDraftFile && hasDraftDir) {
+    error(gapName, "Both DRAFT.md and DRAFT/ directory exist - only one is allowed");
+  }
+
+  if (hasDraftDir && !hasDraftIndex) {
+    error(gapName, "DRAFT/ directory exists but DRAFT/Index.md is missing");
+  }
+}
+
 function validateMetadata(dirPath, gapName) {
   const metadataPath = join(dirPath, "metadata.yml");
 
@@ -148,6 +170,9 @@ function main() {
   // Validate README.md exists
   validateReadmeExists(dirPath, gapName);
 
+  // Validate DRAFT.md or DRAFT/ exists
+  validateDraftExists(dirPath, gapName);
+
   // Validate metadata.yml
   validateMetadata(dirPath, gapName);
 }