ci: validate simple extension examples in docs (#885)

Author: benbellick

.github/workflows/pr.yml

@@ -54,31 +54,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-python@v6
         with:
-          node-version: "20"
-      - run: npm install -g ajv-cli
-      - run: |
-          set -euo pipefail
-          for i in $(ls *.yaml);
-          do
-            ajv validate -s ../text/simple_extensions_schema.yaml --strict=true --spec=draft2020 -d "$i"
-          done
-        working-directory: ./extensions
-      - run: |
-          set -euo pipefail
-          for i in $(ls *.yaml);
-          do
-            ajv validate -s ../../text/dialect_schema.yaml --strict=true --spec=draft2020 -d "$i"
-          done
-        working-directory: ./dialects/tests
-      - run: |
-          set -euo pipefail
-          for i in $(ls *.yaml);
-          do
-            ajv validate -s ../text/dialect_schema.yaml --strict=true --spec=draft2020 -d "$i"
-          done
-        working-directory: ./dialects
+          python-version: '3.13'
+      - run: pip install check-jsonschema
+      - run: check-jsonschema --schemafile text/simple_extensions_schema.yaml extensions/*.yaml
+      - run: check-jsonschema --schemafile text/simple_extensions_schema.yaml site/examples/**/*.yaml
+      - run: check-jsonschema --schemafile text/dialect_schema.yaml dialects/tests/*.yaml
   dry_run_release:
     name: Dry-run release
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -10,6 +10,20 @@ There's no formal set of dependencies for Substrait, but here are some that are
 * [`protoc`](https://grpc.io/docs/protoc-installation/), used by `buf` and usable independent of `buf`
 * A Python environment with [the website's `requirements.txt`](https://github.com/substrait-io/substrait/blob/main/site/requirements.txt) dependencies installed if you want to see changes to the website locally
 
+## Documentation Examples
+
+When adding examples to the documentation, please use external example files instead of inline code blocks. This ensures examples are validated against schemas in CI/CD and prevents documentation drift.
+
+See [`site/examples/README.md`](site/examples/README.md) for complete instructions on creating and including validated examples.
+
+Quick example:
+
+```markdown
+```yaml
+--8<-- "examples/extensions/my_example.yaml"
+```
+```
+
 ## Commit Conventions
 
 Substrait follows [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit message structure. You can use [`pre-commit`](https://pre-commit.com/) to check your messages for you, but note that you must install pre-commit using `pre-commit install --hook-type commit-msg` for this to work. CI will also lint your commit messages. Please also ensure that your PR title and initial comment together form a valid commit message; that will save us some work formatting the merge commit message when we merge your PR.

site/docs/expressions/user_defined_functions.md

@@ -7,26 +7,6 @@ Here's an example function that doubles its input:
 !!! info inline end "Implementation Note"
     This implementation is only defined on 32-bit floats and integers but could be defined on all numbers (and even lists and strings).  The user of the implementation can specify what happens when the resulting value falls outside of the valid range for a 32-bit float (either return NAN or raise an error).
 
-``` yaml
-%YAML 1.2
----
-scalar_functions:
-  -
-    name: "double"
-    description: "Double the value"
-    impls:
-      - args:
-          - name: x
-            value: fp32
-        options:
-          on_domain_error:
-            values: [ NAN, ERROR ]
-        return: fp32
-      - args:
-          - name: x
-            value: i32
-        options:
-          on_domain_error:
-            values: [ NAN, ERROR ]
-        return: i32
+```yaml
+--8<-- "examples/extensions/double_function.yaml"
 ```

site/docs/extensions/index.md

@@ -35,19 +35,7 @@ A YAML file can also reference types and type variations defined in another YAML
 For example, if the extension with extension URN `extension:io.substrait:extension_types` defines a type called `point`, a different YAML file can use the type in a function declaration as follows:
 
 ```yaml
-urn: extension:example:distance_functions
-dependencies:
-  ext: extension:io.substrait:extension_types
-scalar_functions:
-- name: distance
-  description: The distance between two points.
-  impls:
-  - args:
-    - name: a
-      value: ext.point
-    - name: b
-      value: ext.point
-    return: f64
+--8<-- "examples/extensions/distance_functions.yaml"
 ```
 
 Here, the choice for the name `ext` is arbitrary, as long as it does not conflict with anything else in the YAML file.
@@ -125,29 +113,13 @@ A function signature uniquely identifies a function implementation within a sing
 ### Any Types
 
 ```yaml
-scalar_functions:
-- name: foo
-  impls:
-  - args:
-    - name: a
-      value: any
-    - name: b
-      value: any
-    return: int64
+--8<-- "examples/extensions/any_type_function.yaml"
 ```
 
 The `any` type indicates that the argument can take any possible type. In the `foo` function above, arguments `a` and `b` can be of any type, even different ones in the same function invocation.
 
 ```yaml
-scalar_functions:
-- name: bar
-  impls:
-  - args:
-    - name: a
-      value: any1
-    - name: b
-      value: any1
-    return: int64
+--8<-- "examples/extensions/any1_type_function.yaml"
 ```
 The `any[\d]` types (i.e. `any1`, `any2`, ..., `any9`) impose an additional restriction. Within a single function invocation, all any types with same numeric suffix _must_ be of the same type. In the `bar` function above, arguments `a` and `b` can have any type as long as both types are the same.
 

site/docs/types/type_classes.md

@@ -53,22 +53,7 @@ User-defined type classes are defined as part of [simple extensions](../extensio
 For example, the following declares a type named `point` (namespaced to the associated YAML file) and two scalar functions that operate on it.
 
 ```yaml
-types:
-  - name: "point"
-
-scalar_functions:
-  - name: "lat"
-    impls:
-      - args:
-        - name: p
-        - value: u!point
-    return: fp64
-  - name: "lon"
-    impls:
-      - args:
-        - name: p
-        - value: u!point
-    return: fp64
+--8<-- "examples/types/user_defined_point.yaml"
 ```
 
 ### Handling User-Defined Types
@@ -85,18 +70,13 @@ Specifiers of user-defined types may provide additional structure information fo
 For example, the following declares a `point` type with two `i32` values named longitude and latitude:
 
 ```yaml
-types:
-  - name: point
-    structure:
-      longitude: i32
-      latitude: i32
+--8<-- "examples/types/point_with_structure.yaml"
 ```
 
 The name-type object notation used above is syntactic sugar for `NSTRUCT<longitude: i32, latitude: i32>`. The following means the same thing:
 
 ```yaml
-name: point
-structure: "NSTRUCT<longitude: i32, latitude: i32>"
+--8<-- "examples/types/point_with_nstruct.yaml"
 ```
 
 The structure field of a type is only intended to inform systems that don't have built-in support for the type about how they can create and transfer values of that type to systems that do support the type.
@@ -116,74 +96,41 @@ Literals for user-defined types can be represented in one of two ways:
 User-defined types may be turned into compound types by requiring parameters to be passed to them. The supported "meta-types" for parameters are data types (like those used in `LIST`, `MAP`, and `STRUCT`), booleans, integers, enumerations, and strings. Using parameters, we could redefine "point" with different types of coordinates. For example:
 
 ```yaml
-name: point
-parameters:
-  - name: T
-    description: |
-      The type used for the longitude and latitude
-      components of the point.
-    type: dataType
+--8<-- "examples/types/point_with_datatype_param.yaml"
 ```
 
 or:
 
 ```yaml
-name: point
-parameters:
-  - name: coordinate_type
-    type: enumeration
-    options:
-      - integer
-      - double
+--8<-- "examples/types/point_with_enum_param.yaml"
 ```
 
 or:
 
 ```yaml
-name: point
-parameters:
-  - name: LONG
-    type: dataType
-  - name: LAT
-    type: dataType
+--8<-- "examples/types/point_with_two_params.yaml"
 ```
 
 We can't specify the internal structure in this case, because there is currently no support for derived types in the structure.
 
 The allowed range can be limited for integer parameters. For example:
 
 ```yaml
-name: vector
-parameters:
-  - name: T
-    type: dataType
-  - name: dimensions
-    type: integer
-    min: 2
-    max: 3
+--8<-- "examples/types/vector_with_constraints.yaml"
 ```
 
 This specifies a vector that can be either 2- or 3-dimensional. Note however that it's not currently possible to put constraints on data type, string, or (technically) boolean parameters.
 
 Similar to function arguments, the last parameter may be specified to be variadic, allowing it to be specified one or more times instead of only once. For example:
 
 ```yaml
-name: union
-parameters:
-  - name: T
-    type: dataType
-variadic: true
+--8<-- "examples/types/union_variadic.yaml"
 ```
 
 This defines a type that can be parameterized with one or more other data types, for example `union<i32, i64>` but also `union<bool>`. Zero or more is also possible, by making the last argument optional:
 
 ```yaml
-name: tuple
-parameters:
-  - name: T
-    type: dataType
-    optional: true
-variadic: true
+--8<-- "examples/types/tuple_optional_variadic.yaml"
 ```
 
 This would also allow for `tuple<>`, to define a zero-tuple.

site/examples/README.md

@@ -0,0 +1,28 @@
+# Documentation Examples
+
+This directory contains example files that are included in the Substrait documentation.
+
+By storing examples as separate files instead of inline in markdown, we can easily validate against schemas via CI/CD.
+
+## Directory Structure
+
+```
+examples/
+├── extensions/     # Extension function examples (e.g., any types)
+├── types/          # User-defined type examples
+└── README.md       # This file
+```
+
+All examples are validated against `text/simple_extensions_schema.yaml` in CI/CD.
+
+## Including Examples in Markdown
+
+Use the pymdownx.snippets syntax to include example files:
+
+````markdown
+```yaml
+--8<-- "examples/extensions/distance_functions.yaml"
+```
+````
+
+The snippet will be rendered with syntax highlighting and the actual file content.

site/examples/extensions/any1_type_function.yaml

@@ -0,0 +1,11 @@
+# Example showing the 'any1' type - arguments must be of the same type
+urn: extension:example:any1_type
+scalar_functions:
+- name: bar
+  impls:
+  - args:
+    - name: a
+      value: any1
+    - name: b
+      value: any1
+    return: int64

site/examples/extensions/any_type_function.yaml

@@ -0,0 +1,11 @@
+# Example showing the 'any' type - arguments can be of any type
+urn: extension:example:any_type
+scalar_functions:
+- name: foo
+  impls:
+  - args:
+    - name: a
+      value: any
+    - name: b
+      value: any
+    return: int64

site/examples/extensions/distance_functions.yaml

@@ -0,0 +1,13 @@
+urn: extension:example:distance_functions
+dependencies:
+  ext: extension:io.substrait:extension_types
+scalar_functions:
+- name: distance
+  description: The distance between two points.
+  impls:
+  - args:
+    - name: a
+      value: ext.point
+    - name: b
+      value: ext.point
+    return: f64

site/examples/extensions/double_function.yaml

@@ -0,0 +1,22 @@
+%YAML 1.2
+---
+urn: extension:example:double_function
+scalar_functions:
+  -
+    name: "double"
+    description: "Double the value"
+    impls:
+      - args:
+          - name: x
+            value: fp32
+        options:
+          on_domain_error:
+            values: [ NAN, ERROR ]
+        return: fp32
+      - args:
+          - name: x
+            value: i32
+        options:
+          on_domain_error:
+            values: [ NAN, ERROR ]
+        return: i32