feat(go): embed the specification's example extensions

The specification's example extension and type YAML under `site/examples` are the only worked examples of large parts of the simple-extension schema — parameterized user-defined types, NSTRUCT structures, variadic and optional parameters, lambda signatures, metadata and deprecation markers — which makes them useful fixtures for the typed parsing that lives downstream in substrait-go.

Vendor them alongside the extension, text and test-case data and expose them through a separate `GetSubstraitExamplesFS`. Keeping them in their own directory and their own `embed.FS` is deliberate: they are documentation illustrations, not entries in the Substrait extension catalog, so a consumer walking the extensions FS must not encounter them. `TestExamplesAreNotEmbeddedAsExtensions` asserts that, and fails if a future change flattens the copy.

The plan examples in `site/examples/proto-textformat` are not vendored: they are protobuf text format rather than simple-extension YAML, so they belong with the protobuf modules.

Author: nielspardon

go/substrait-extensions/README.md

@@ -1,12 +1,12 @@
 # substrait-extensions (Go)
 
-Go access to the [Substrait](https://substrait.io/) specification's extension definitions, text schemas and function test cases, bundled via [`embed.FS`](https://pkg.go.dev/embed).
+Go access to the [Substrait](https://substrait.io/) specification's extension definitions, text schemas, function test cases and documentation examples, bundled via [`embed.FS`](https://pkg.go.dev/embed).
 
 This module ships the raw spec **data only** — it does not generate Go types from the extension schema. Unlike the Python and Rust extensions packages (which generate types with datamodel-code-generator and typify), Go has no canonical JSON-schema code generator, and the extension schema's polymorphic function definitions do not map cleanly onto Go's type system. The typed parsing therefore lives downstream (e.g. in [substrait-go](https://github.com/substrait-io/substrait-go)). This mirrors the Java extensions artifact, which also bundles the data as resources without generating types.
 
 It is a drop-in replacement for the legacy `embed.FS` module that lived at the root of the substrait specification repository (`github.com/substrait-io/substrait`): the package is named `substrait` and exposes the same accessors, so consumers only change the import path.
 
-The data is sourced from [extensions](https://github.com/substrait-io/substrait/tree/main/extensions), [text](https://github.com/substrait-io/substrait/tree/main/text) and [tests/cases](https://github.com/substrait-io/substrait/tree/main/tests/cases) in the substrait repository. Versions of this module correspond to Substrait [releases](https://github.com/substrait-io/substrait/releases).
+The data is sourced from [extensions](https://github.com/substrait-io/substrait/tree/main/extensions), [text](https://github.com/substrait-io/substrait/tree/main/text), [tests/cases](https://github.com/substrait-io/substrait/tree/main/tests/cases) and [site/examples](https://github.com/substrait-io/substrait/tree/main/site/examples) in the substrait repository. Versions of this module correspond to Substrait [releases](https://github.com/substrait-io/substrait/releases).
 
 ## Module Usage
 
@@ -17,16 +17,20 @@ func example() {
 	extFS := substrait.GetSubstraitExtensionsFS() // extensions/*.yaml
 	textFS := substrait.GetSubstraitTextFS()      // text/*.yaml
 	testsFS := substrait.GetSubstraitTestsFS()    // tests/cases/**/*.test
+	exFS := substrait.GetSubstraitExamplesFS()    // examples/{extensions,types}/*.yaml
 	_ = extFS
 	_ = textFS
 	_ = testsFS
+	_ = exFS
 }
 ```
 
 ```sh
 go get github.com/substrait-io/substrait-packaging/go/substrait-extensions@vx.y.z
 ```
 
+The examples returned by `GetSubstraitExamplesFS` are **not** catalog entries: their URNs use an example owner rather than `extension:io.substrait:`, they are deliberately absent from the FS returned by `GetSubstraitExtensionsFS`, and their contents and URNs may change without a deprecation cycle. They ship as fixtures for exercising an extension parser against the corners of the simple-extension schema.
+
 ## Generation and Publishing
 
 Code generation and publishing is handled in the [substrait-packaging](https://github.com/substrait-io/substrait-packaging) repository.

go/substrait-extensions/embed.go

@@ -20,6 +20,9 @@ var textFS embed.FS
 //go:embed tests/cases
 var testsFS embed.FS
 
+//go:embed examples
+var examplesFS embed.FS
+
 // GetSubstraitFS returns an embed.FS containing the Substrait extension
 // definition YAML files under the "extensions" directory.
 //
@@ -38,3 +41,13 @@ func GetSubstraitTextFS() embed.FS { return textFS }
 // GetSubstraitTestsFS returns an embed.FS containing the Substrait function
 // test case files under the "tests/cases" directory.
 func GetSubstraitTestsFS() embed.FS { return testsFS }
+
+// GetSubstraitExamplesFS returns an embed.FS containing the example extension
+// and type YAML files from the specification's documentation, under the
+// "examples/extensions" and "examples/types" directories.
+//
+// These are illustrations of the simple-extension format, not entries in the
+// Substrait extension catalog: they are deliberately absent from the FS returned
+// by GetSubstraitExtensionsFS, and their contents and URNs may change without a
+// deprecation cycle. They are useful as fixtures for testing an extension parser.
+func GetSubstraitExamplesFS() embed.FS { return examplesFS }

go/substrait-extensions/embed_test.go

@@ -45,3 +45,37 @@ func TestEmbeddedTests(t *testing.T) {
 		t.Fatal("no embedded test case files found under tests/cases/")
 	}
 }
+
+func TestEmbeddedExamples(t *testing.T) {
+	for _, dir := range []string{"examples/extensions", "examples/types"} {
+		entries, err := GetSubstraitExamplesFS().ReadDir(dir)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(entries) == 0 {
+			t.Fatalf("no embedded example files found under %s/", dir)
+		}
+	}
+}
+
+func TestExamplesAreNotEmbeddedAsExtensions(t *testing.T) {
+	// The examples are illustrations, not catalog entries: code that walks the
+	// extensions FS must not reach them. Guards against a future change that
+	// flattens the copy into extensions/.
+	err := fs.WalkDir(GetSubstraitExtensionsFS(), "extensions", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() && path != "extensions" {
+			t.Errorf("unexpected subdirectory %s in the extensions FS", path)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := GetSubstraitExtensionsFS().ReadDir("examples"); err == nil {
+		t.Fatal("examples/ is reachable from the extensions FS")
+	}
+}

go/substrait-extensions/examples/.gitkeep

@@ -6,6 +6,7 @@ SUBSTRAIT_HOME="${SUBSTRAIT_HOME:-../../substrait}"
 EXTENSIONS_DIR="$SUBSTRAIT_HOME/extensions"
 TEXT_DIR="$SUBSTRAIT_HOME/text"
 TESTCASES_DIR="$SUBSTRAIT_HOME/tests/cases"
+EXAMPLES_DIR="$SUBSTRAIT_HOME/site/examples"
 
 echo "Vendoring Substrait extension files from $SUBSTRAIT_HOME"
 
@@ -27,3 +28,13 @@ cp "$TEXT_DIR"/*.yaml text/
 rm -rf tests/cases
 mkdir -p tests/cases
 cp -r "$TESTCASES_DIR"/. tests/cases/
+
+# Example extension and type YAML files (embedded via //go:embed examples). These
+# are documentation illustrations rather than catalog entries, so they are kept in
+# their own directory and their own embed.FS: a consumer walking the extensions FS
+# must not encounter them. The plan examples in site/examples/proto-textformat are
+# protobuf, not simple-extension YAML, and are not vendored here.
+rm -rf examples
+mkdir -p examples
+cp -r "$EXAMPLES_DIR/extensions" examples/
+cp -r "$EXAMPLES_DIR/types" examples/