NopeCharon · Nov 11, 2026 · Nov 11, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -48,6 +48,23 @@ repos:
       language: script
       entry: .dev-tools/linting/check-links-to-precice.sh
       types_or: ["markdown", "html"]
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.39.0
+  hooks:
+    - id: check-metaschema
+      files: ^tests/schemas/.*\.schema\.json$
+    - id: check-jsonschema
+      name: validate tests.yaml
+      files: ^tests/tests\.yaml$
+      args: [ --schemafile, tests/schemas/tests.schema.json ]
+    - id: check-jsonschema
+      name: validate components.yaml
+      files: ^tests/components\.yaml$
+      args: [ --schemafile, tests/schemas/components.schema.json ]
+    - id: check-jsonschema
+      name: validate metadata.yaml
+      files: ^[^/]+/metadata\.yaml$
+      args: [ --schemafile, tests/schemas/metadata.schema.json ]
 - repo: https://github.com/rhysd/actionlint
   rev: v1.7.12
   hooks:

diff --git a/aste-turbine/metadata.yaml b/aste-turbine/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: ASTE turbine
 path: aste-turbine
 url: https://precice.org/tutorials-aste-turbine.html

diff --git a/breaking-dam-2d/metadata.yaml b/breaking-dam-2d/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Breaking dam 2D
 path: breaking-dam-2d # relative to git repo 
 url: https://precice.org/tutorials-breaking-dam-2d.html

diff --git a/changelog-entries/948.md b/changelog-entries/948.md
@@ -0,0 +1 @@
+- Added JSON schemas for `tests.yaml`, `components.yaml`, and the `metadata.yaml` files, which provide editor support and are checked by the pre-commit hooks. [#948](https://github.com/precice/tutorials/pull/948)
diff --git a/channel-transport-particles/metadata.yaml b/channel-transport-particles/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Channel transport particles
 path: channel-transport-particles
 url: https://precice.org/tutorials-channel-transport-particles.html

diff --git a/channel-transport-reaction/metadata.yaml b/channel-transport-reaction/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Channel transport reaction
 path: channel-transport-reaction
 url: https://precice.org/tutorials-channel-transport-reaction.html

diff --git a/channel-transport/metadata.yaml b/channel-transport/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Channel transport
 path: channel-transport
 url: https://precice.org/tutorials-channel-transport.html

diff --git a/elastic-tube-1d/metadata.yaml b/elastic-tube-1d/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Elastic tube 1D
 path: elastic-tube-1d
 url: https://precice.org/tutorials-elastic-tube-1d.html

diff --git a/elastic-tube-3d/metadata.yaml b/elastic-tube-3d/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Elastic tube 3D
 path: elastic-tube-3d # relative to git repo 
 url: https://precice.org/tutorials-elastic-tube-3d.html

diff --git a/flow-around-controlled-moving-cylinder/metadata.yaml b/flow-around-controlled-moving-cylinder/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow around a controlled moving cylinder
 path: flow-around-controlled-moving-cylinder
 url: https://precice.org/tutorials-flow-around-controlled-moving-cylinder.html

diff --git a/flow-over-heated-plate-nearest-projection/metadata.yaml b/flow-over-heated-plate-nearest-projection/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow over heated plate nearest projection
 path: flow-over-heated-plate-nearest-projection
 url: https://precice.org/tutorials-flow-over-heated-plate-nearest-projection.html

diff --git a/flow-over-heated-plate-partitioned-flow/metadata.yaml b/flow-over-heated-plate-partitioned-flow/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow over heated plate partitioned flow
 path: flow-over-heated-plate-partitioned-flow # relative to git repo 
 url: https://precice.org/tutorials-flow-over-heated-plate-partitioned-flow.html

diff --git a/flow-over-heated-plate-steady-state/metadata.yaml b/flow-over-heated-plate-steady-state/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow over heated plate steady state
 path: flow-over-heated-plate-steady-state # relative to git repo 
 url: https://precice.org/tutorials-flow-over-heated-plate-steady-state.html

diff --git a/flow-over-heated-plate-two-meshes/metadata.yaml b/flow-over-heated-plate-two-meshes/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow over heated plate with two meshes
 path: flow-over-heated-plate-two-meshes # relative to git repo 
 url: https://precice.org/tutorials-flow-over-heated-plate-two-meshes.html

diff --git a/flow-over-heated-plate/metadata.yaml b/flow-over-heated-plate/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Flow over heated plate
 path: flow-over-heated-plate # relative to git repo 
 url: https://precice.org/tutorials-flow-over-heated-plate.html

diff --git a/free-flow-over-porous-media/metadata.yaml b/free-flow-over-porous-media/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Free flow over porous media
 path: free-flow-over-porous-media
 url: https://precice.org/tutorials-free-flow-over-porous-media-2d.html

diff --git a/heat-exchanger-simplified/metadata.yaml b/heat-exchanger-simplified/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Heat Exchanger simplified
 path: heat-exchanger-simplified # relative to git repo 
 url: https://precice.org/tutorials-heat-exchanger-simplified.html

diff --git a/heat-exchanger/metadata.yaml b/heat-exchanger/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Heat exchanger
 path: heat-exchanger # relative to git repo 
 url: https://precice.org/tutorials-heat-exchanger.html

diff --git a/multiple-perpendicular-flaps/metadata.yaml b/multiple-perpendicular-flaps/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Multiple perpendicular flaps
 path: multiple-perpendicular-flaps
 url: https://precice.org/tutorials-multiple-perpendicular-flaps.html

diff --git a/oscillator-overlap/metadata.yaml b/oscillator-overlap/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Oscillator overlap
 path: oscillator-overlap
 url: https://precice.org/tutorials-oscillator-overlap.html

diff --git a/oscillator/metadata.yaml b/oscillator/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Oscillator
 path: oscillator
 url: https://precice.org/tutorials-oscillator.html

diff --git a/partitioned-backwards-facing-step/metadata.yaml b/partitioned-backwards-facing-step/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned backwards facing step
 path: partitioned-backwards-facing-step # relative to git repo 
 url: https://precice.org/tutorials-partitioned-backwards-facing-step.html

diff --git a/partitioned-burgers-1d/metadata.yaml b/partitioned-burgers-1d/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned Burgers' equation 1D
 path: partitioned-burgers-1d # relative to git repo 
 url: https://precice.org/tutorials-partitioned-burgers-1d.html

diff --git a/partitioned-elastic-beam/metadata.yaml b/partitioned-elastic-beam/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned elastic beam
 path: partitioned-elastic-beam # relative to git repo 
 url: https://precice.org/tutorials-partitioned-elastic-beam.html

diff --git a/partitioned-heat-conduction-3d/metadata.yaml b/partitioned-heat-conduction-3d/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned heat conduction 3D
 path: partitioned-heat-conduction-3d # relative to git repo 
 url: https://precice.org/tutorials-partitioned-heat-conduction-3d.html

diff --git a/partitioned-heat-conduction-complex/metadata.yaml b/partitioned-heat-conduction-complex/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned heat conduction complex
 path: partitioned-heat-conduction-complex # relative to git repo 
 url: https://precice.org/tutorials-partitioned-heat-conduction-complex.html

diff --git a/partitioned-heat-conduction-direct/metadata.yaml b/partitioned-heat-conduction-direct/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned heat conduction direct
 path: partitioned-heat-conduction-direct # relative to git repo 
 url: https://precice.org/tutorials-partitioned-heat-conduction-direct.html

diff --git a/partitioned-heat-conduction-overlap/metadata.yaml b/partitioned-heat-conduction-overlap/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned heat conduction overlap
 path: partitioned-heat-conduction-overlap # relative to git repo 
 url: https://precice.org/tutorials-partitioned-heat-conduction-overlap.html

diff --git a/partitioned-heat-conduction/metadata.yaml b/partitioned-heat-conduction/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned heat conduction
 path: partitioned-heat-conduction # relative to git repo 
 url: https://precice.org/tutorials-partitioned-heat-conduction.html

diff --git a/partitioned-pipe-multiscale/metadata.yaml b/partitioned-pipe-multiscale/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned pipe multiscale
 path: partitioned-pipe-multiscale # relative to git repo 
 url: https://precice.org/tutorials-partitioned-pipe-multiscale.html

diff --git a/partitioned-pipe-two-phase/metadata.yaml b/partitioned-pipe-two-phase/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned pipe two phase
 path: partitioned-pipe-two-phase # relative to git repo 
 url: https://precice.org/tutorials-partitioned-pipe-two-phase.html

diff --git a/partitioned-pipe/metadata.yaml b/partitioned-pipe/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Partitioned pipe
 path: partitioned-pipe # relative to git repo 
 url: https://precice.org/tutorials-partitioned-pipe.html

diff --git a/perpendicular-flap-stress/metadata.yaml b/perpendicular-flap-stress/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Perpendicular flap stress
 path: perpendicular-flap-stress
 url: https://precice.org/tutorials-perpendicular-flap-stress.html

diff --git a/perpendicular-flap/metadata.yaml b/perpendicular-flap/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Perpendicular flap
 path: perpendicular-flap
 url: https://precice.org/tutorials-perpendicular-flap.html

diff --git a/quickstart/metadata.yaml b/quickstart/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Quickstart
 path: quickstart # relative to git repo 
 url: https://precice.org/quickstart.html

diff --git a/resonant-circuit/metadata.yaml b/resonant-circuit/metadata.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Resonant circuit
 path: resonant-circuit
 url: https://precice.org/tutorials-resonant-circuit.html

diff --git a/tests/README.md b/tests/README.md
@@ -320,6 +320,7 @@ Metadata and workflow/script files:
   - `components.yaml`: Declares the available components and their parameters/options
   - `reference-results-metadata.md.template`: Template for reporting the versions and machine used to generate each reference results archive
   - `reference_versions.yaml`: List of arguments to use for generating the reference results
+  - `schemas/`: JSON schemas that describe `tests.yaml`, `components.yaml`, and the `metadata.yaml` files of the tutorials
   - `tests.yaml`: Declares the available tests, grouped in test suites
 
 User-facing tools:
@@ -350,6 +351,7 @@ Implementation scripts:
 Every tutorial contains a file called `metadata.yaml` describing some important properties of the tutorial. For example:
 
 ```yaml
+# yaml-language-server: $schema=../tests/schemas/metadata.schema.json
 name: Elastic tube 3D
 path: elastic-tube-3d
 url: https://precice.org/tutorials-elastic-tube-3d.html
@@ -390,6 +392,12 @@ Description:
   - `run`: Command that executes the tutorial
   - `component`: Component or list of components that this case depends upon (typically an adapter)
 
+### Schemas
+
+The structure of `metadata.yaml`, `components.yaml`, and `tests.yaml` is described by the JSON schemas in the [`schemas/`](https://github.com/precice/tutorials/tree/develop/tests/schemas) directory. Each of these files starts with a comment of the form `# yaml-language-server: $schema=<path to the schema>`, which makes editors that use the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (e.g., the YAML extension for VS Code) offer autocompletion, show documentation on hover, and highlight mistakes while you edit. When you add a `metadata.yaml` file for a new tutorial, start it with the same comment as the existing ones.
+
+The same schemas are checked by the [pre-commit](https://pre-commit.com/) hooks (and therefore in the "Check style" workflow), so that a malformed entry is reported before the system tests run. If you add a new option to one of these files, also extend the respective schema.
+
 ### Components
 
 The components mentioned in the Metadata are defined in the central `components.yaml` file. This file also specifies some arguments and their default values. These arguments can be anything, but most often they are version-related information. For example, the version of OpenFOAM used by the openfoam-adapter component, or the component version itself. For example:

diff --git a/tests/components.yaml b/tests/components.yaml
@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=schemas/components.schema.json
 bare: # A default component used when the solver does not have any dependencies apart from preCICE itself
   template: component-templates/bare.yaml
   build_arguments: # these things mean something to the docker-service

diff --git a/tests/schemas/components.schema.json b/tests/schemas/components.schema.json
@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/components.schema.json",
+  "title": "preCICE tutorials system tests: components.yaml",
+  "description": "The components (e.g., adapters, language bindings) that can be used by the cases of the tutorials, together with the parameters that their Docker image accepts.",
+  "type": "object",
+  "additionalProperties": { "$ref": "#/definitions/component" },
+  "definitions": {
+    "component": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["template", "build_arguments"],
+      "properties": {
+        "template": {
+          "description": "Path to the Docker Compose service template of this component, relative to the tests directory.",
+          "type": "string",
+          "minLength": 1
+        },
+        "repository": {
+          "description": "Repository of the component.",
+          "type": "string"
+        },
+        "build_timeout": {
+          "description": "Timeout for building the Docker image of this component, in seconds.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "build_arguments": {
+          "description": "The build arguments of the Docker image of this component, by name.",
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/buildArgument" }
+        }
+      }
+    },
+    "buildArgument": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "description": {
+          "description": "Short description of the build argument.",
+          "type": "string"
+        },
+        "repository": {
+          "description": "Repository that a _REF build argument refers to.",
+          "type": "string"
+        },
+        "default": {
+          "description": "Default value. Build arguments without a default value are required.",
+          "type": "string"
+        },
+        "value_options": {
+          "description": "The values that are accepted. If not specified, all values are accepted.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}
diff --git a/tests/schemas/metadata.schema.json b/tests/schemas/metadata.schema.json
@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/metadata.schema.json",
+  "title": "preCICE tutorials: metadata.yaml",
+  "description": "Metadata of a tutorial: its participants and the cases (directories) that can play the role of each participant.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "path", "url", "participants", "cases"],
+  "properties": {
+    "name": {
+      "description": "Human-readable name of the tutorial.",
+      "type": "string",
+      "minLength": 1
+    },
+    "path": {
+      "description": "Directory of the tutorial, relative to the root of the repository.",
+      "type": "string",
+      "minLength": 1
+    },
+    "url": {
+      "description": "URL of the documentation page of the tutorial.",
+      "type": "string",
+      "minLength": 1
+    },
+    "participants": {
+      "description": "The participants of the coupled simulation.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "cases": {
+      "description": "The available cases, by name. Each case provides one participant.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/definitions/case" }
+    }
+  },
+  "definitions": {
+    "case": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["participant", "directory", "run", "component"],
+      "properties": {
+        "participant": {
+          "description": "The participant that this case provides. Must be one of the listed participants.",
+          "type": "string",
+          "minLength": 1
+        },
+        "directory": {
+          "description": "Directory of the case, relative to the tutorial directory.",
+          "type": "string",
+          "minLength": 1
+        },
+        "run": {
+          "description": "Command to run the case, executed in its directory. Leave empty (null) for cases that do not run anything, e.g., a placeholder for a participant that is not needed.",
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "component": {
+          "description": "The component (as defined in tests/components.yaml) that this case needs.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		- Added JSON schemas for `tests.yaml`, `components.yaml`, and the `metadata.yaml` files, which provide editor support and are checked by the pre-commit hooks. [#948](https://github.com/precice/tutorials/pull/948)