From 5c32c3649fc1a93b5947d5e7b0f0c761c95cfff2 Mon Sep 17 00:00:00 2001 From: NopeCharon <115794254+NopeCharon@users.noreply.github.com> Date: Wed, 11 Nov 2026 23:55:23 +0530 Subject: [PATCH 1/2] Add JSON schemas for the system tests YAML files Add JSON schemas for tests.yaml, components.yaml, and the metadata.yaml files of the tutorials, in tests/schemas/. They describe the structure that the Python parsers in tests/metadata_parser and tests/systemtests expect, including the optional fields (max_time, max_time_windows, timeout, tolerance, skip_compare, run-before, run-after, external sources, build_timeout, value_options). Every schema-covered file now starts with a "# yaml-language-server: $schema=..." comment, so that editors using the YAML language server (e.g., VS Code) offer autocompletion and documentation, and report mistakes while editing. The schemas are also validated against all respective files via check-jsonschema in the pre-commit hooks, and thus in the "Check style" workflow, so that malformed test definitions are caught before the system tests run. The schemas themselves are checked against the JSON Schema metaschema. Document the schemas in tests/README.md. Closes #403 --- .pre-commit-config.yaml | 17 ++ aste-turbine/metadata.yaml | 1 + breaking-dam-2d/metadata.yaml | 1 + channel-transport-particles/metadata.yaml | 1 + channel-transport-reaction/metadata.yaml | 1 + channel-transport/metadata.yaml | 1 + elastic-tube-1d/metadata.yaml | 1 + elastic-tube-3d/metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + flow-over-heated-plate/metadata.yaml | 1 + free-flow-over-porous-media/metadata.yaml | 1 + heat-exchanger-simplified/metadata.yaml | 1 + heat-exchanger/metadata.yaml | 1 + multiple-perpendicular-flaps/metadata.yaml | 1 + oscillator-overlap/metadata.yaml | 1 + oscillator/metadata.yaml | 1 + .../metadata.yaml | 1 + partitioned-burgers-1d/metadata.yaml | 1 + partitioned-elastic-beam/metadata.yaml | 1 + partitioned-heat-conduction-3d/metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + .../metadata.yaml | 1 + partitioned-heat-conduction/metadata.yaml | 1 + partitioned-pipe-multiscale/metadata.yaml | 1 + partitioned-pipe-two-phase/metadata.yaml | 1 + partitioned-pipe/metadata.yaml | 1 + perpendicular-flap-stress/metadata.yaml | 1 + perpendicular-flap/metadata.yaml | 1 + quickstart/metadata.yaml | 1 + resonant-circuit/metadata.yaml | 1 + tests/README.md | 8 + tests/components.yaml | 1 + tests/schemas/components.schema.json | 59 +++++++ tests/schemas/metadata.schema.json | 68 ++++++++ tests/schemas/tests.schema.json | 157 ++++++++++++++++++ tests/tests.yaml | 1 + turek-hron-fsi3/metadata.yaml | 1 + two-scale-heat-conduction/metadata.yaml | 1 + volume-coupled-diffusion/metadata.yaml | 1 + volume-coupled-flow/metadata.yaml | 1 + water-hammer/metadata.yaml | 1 + wolf-sheep-soil-creep/metadata.yaml | 1 + 47 files changed, 351 insertions(+) create mode 100644 tests/schemas/components.schema.json create mode 100644 tests/schemas/metadata.schema.json create mode 100644 tests/schemas/tests.schema.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 453a6ae08..1ebe4a48c 100644 --- 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 index 5c25fefb5..4200a469b 100644 --- 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 index 786fc691f..77319294e 100644 --- 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/channel-transport-particles/metadata.yaml b/channel-transport-particles/metadata.yaml index 1fbf0a728..2212bc2da 100644 --- 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 index 89e96fe1b..cdcfbb49a 100644 --- 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 index 8f4a22470..dc89a913d 100644 --- 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 index 11d90961d..86bf8b902 100644 --- 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 index 438888d8b..212bb8758 100644 --- 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 index 1c34cc08f..3c6c285d0 100644 --- 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 index 046528f09..5f2a9df24 100644 --- 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 index ddd86c96a..018c8829d 100644 --- 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 index 1bc65d444..fbf9210fa 100644 --- 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 index c457cca11..9e803a8b5 100644 --- 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 index 0b384ba25..b5825ec6d 100644 --- 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 index d4593f648..b11c4b611 100644 --- 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 index bf63971a3..95a82064b 100644 --- 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 index 54974dd77..27f862ccf 100644 --- 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 index 3c4121b29..bbf93e3d6 100644 --- 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 index 9c77c5d7b..b0e47b087 100644 --- 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 index 10f8c3cb7..65ff9fdd0 100644 --- 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 index 982e273fd..357fcff56 100644 --- 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 index 06e7998a4..3c91ecd12 100644 --- 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 index 3d9788f88..2bc435a67 100644 --- 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 index df957913f..e1fa7c129 100644 --- 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 index 673a612b3..f3492cf98 100644 --- 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 index 6f7c35a62..d89cb3299 100644 --- 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 index 2e5ea2404..7ebe917d9 100644 --- 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 index 71d18bcc5..6fbfcd5b7 100644 --- 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 index c6b04ac39..83f1c2727 100644 --- 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 index cd39f97d5..391889f29 100644 --- 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 index 2b92c351e..c8ac4f372 100644 --- 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 index fbb1bbc34..409774478 100644 --- 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 index 5fd17c1ea..a06ec593b 100644 --- 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 index 345f41307..9a84cb2b8 100644 --- 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 index 6988337b2..e9379af25 100644 --- 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 index fd2b8d040..55ba3c0bc 100644 --- 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=`, 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 index 9f171c597..ef9c54a63 100644 --- 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 new file mode 100644 index 000000000..cb8e2d4d5 --- /dev/null +++ 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 new file mode 100644 index 000000000..a2d338c41 --- /dev/null +++ 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 + } + } + } + } +} diff --git a/tests/schemas/tests.schema.json b/tests/schemas/tests.schema.json new file mode 100644 index 000000000..89f0eabd0 --- /dev/null +++ b/tests/schemas/tests.schema.json @@ -0,0 +1,157 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/tests.schema.json", + "title": "preCICE tutorials system tests: tests.yaml", + "description": "Test suites that can be triggered by the system tests. Each test suite is a list of tests, i.e., combinations of the cases of a tutorial.", + "type": "object", + "additionalProperties": false, + "required": ["test_suites"], + "properties": { + "test_suites": { + "description": "The available test suites, by name. By convention, test suites follow the name of the respective tutorial or repository, and are sorted alphabetically.", + "type": "object", + "additionalProperties": { "$ref": "#/definitions/testSuite" } + } + }, + "definitions": { + "testSuite": { + "type": "object", + "additionalProperties": false, + "anyOf": [ + { "required": ["tutorials"] }, + { "required": ["external"] } + ], + "properties": { + "tutorials": { + "description": "Tests that use tutorials from this repository.", + "type": "array", + "items": { "$ref": "#/definitions/tutorialTest" } + }, + "external": { + "description": "Tests that fetch the tutorial from an external git repository or archive.", + "type": "array", + "items": { "$ref": "#/definitions/externalTest" } + } + } + }, + "tutorialTest": { + "description": "A test of a tutorial from this repository.", + "type": "object", + "additionalProperties": false, + "required": ["path", "case_combination", "reference_result"], + "properties": { + "path": { "$ref": "#/definitions/path" }, + "case_combination": { "$ref": "#/definitions/caseCombination" }, + "reference_result": { "$ref": "#/definitions/referenceResult" }, + "max_time": { "$ref": "#/definitions/maxTime" }, + "max_time_windows": { "$ref": "#/definitions/maxTimeWindows" }, + "timeout": { "$ref": "#/definitions/timeout" }, + "tolerance": { "$ref": "#/definitions/tolerance" }, + "skip_compare": { "$ref": "#/definitions/skipCompare" }, + "run-before": { "$ref": "#/definitions/runBefore" }, + "run-after": { "$ref": "#/definitions/runAfter" } + } + }, + "externalTest": { + "description": "A test of a tutorial that is sourced from an external git repository or archive.", + "type": "object", + "additionalProperties": false, + "required": ["path", "source", "case_combination", "reference_result"], + "properties": { + "path": { "$ref": "#/definitions/path" }, + "source": { "$ref": "#/definitions/source" }, + "case_combination": { "$ref": "#/definitions/caseCombination" }, + "reference_result": { "$ref": "#/definitions/referenceResult" }, + "max_time": { "$ref": "#/definitions/maxTime" }, + "max_time_windows": { "$ref": "#/definitions/maxTimeWindows" }, + "timeout": { "$ref": "#/definitions/timeout" }, + "tolerance": { "$ref": "#/definitions/tolerance" }, + "skip_compare": { "$ref": "#/definitions/skipCompare" }, + "run-before": { "$ref": "#/definitions/runBefore" }, + "run-after": { "$ref": "#/definitions/runAfter" } + } + }, + "source": { + "description": "Where to fetch an external tutorial from.", + "type": "object", + "required": ["type", "url"], + "properties": { + "type": { + "description": "git: clone the repository at the given ref. archive: download and extract a .tar.gz / .zip.", + "enum": ["git", "archive"] + }, + "url": { + "description": "URL of the git repository or of the archive.", + "type": "string", + "minLength": 1 + }, + "ref": { + "description": "Branch or tag to check out (git only).", + "type": "string", + "minLength": 1 + }, + "subdir": { + "description": "Subdirectory of the repository or archive that contains the tutorial directory.", + "type": "string" + } + }, + "additionalProperties": false, + "if": { "properties": { "type": { "const": "git" } } }, + "then": { "required": ["ref"] } + }, + "path": { + "description": "Name of the tutorial directory (as in the path field of its metadata.yaml).", + "type": "string", + "minLength": 1 + }, + "caseCombination": { + "description": "Names of the cases (as defined in the metadata.yaml of the tutorial) that are run together, one for each participant.", + "type": "array", + "minItems": 1, + "items": { "type": "string", "minLength": 1 } + }, + "referenceResult": { + "description": "Path to the reference results archive, relative to the repository root.", + "type": "string", + "minLength": 1 + }, + "maxTime": { + "description": "Overrides the max-time of the preCICE configuration, to limit the simulated time.", + "type": "number", + "exclusiveMinimum": 0 + }, + "maxTimeWindows": { + "description": "Overrides the maximum number of time windows to simulate.", + "type": "integer", + "minimum": 1 + }, + "timeout": { + "description": "Timeout of this test, in seconds.", + "type": "integer", + "minimum": 1 + }, + "tolerance": { + "description": "Relative tolerance of the fieldcompare comparison. Defaults to 3e-7.", + "anyOf": [ + { "type": "number", "exclusiveMinimum": 0 }, + { + "description": "Numbers such as 1e-2 are loaded as strings by some YAML parsers.", + "type": "string", + "pattern": "^\\+?([0-9]+\\.?[0-9]*|\\.[0-9]+)([eE][+-]?[0-9]+)?$" + } + ] + }, + "skipCompare": { + "description": "Skip the comparison with the reference results, and only check that the build and the run succeed.", + "type": "boolean" + }, + "runBefore": { + "description": "Shell command to run in the copied tutorial directory before the Docker build.", + "type": "string" + }, + "runAfter": { + "description": "Shell command to run in the copied tutorial directory after the simulation and before the comparison.", + "type": "string" + } + } +} diff --git a/tests/tests.yaml b/tests/tests.yaml index a39616bd1..036e857a0 100644 --- a/tests/tests.yaml +++ b/tests/tests.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=schemas/tests.schema.json # Test suites that can be triggered by the system tests. # Define test suites per tutorial in the beginning of the file, # then refer to these in the release test suite and in the individual test diff --git a/turek-hron-fsi3/metadata.yaml b/turek-hron-fsi3/metadata.yaml index 1647e2120..2d8a7363d 100644 --- a/turek-hron-fsi3/metadata.yaml +++ b/turek-hron-fsi3/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Turek-Hron FSI3 path: turek-hron-fsi3 # relative to git repo url: https://precice.org/tutorials-turek-hron-fsi3.html diff --git a/two-scale-heat-conduction/metadata.yaml b/two-scale-heat-conduction/metadata.yaml index d5c748949..d2030128b 100644 --- a/two-scale-heat-conduction/metadata.yaml +++ b/two-scale-heat-conduction/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Two-scale heat conduction path: two-scale-heat-conduction url: https://precice.org/tutorials-two-scale-heat-conduction.html diff --git a/volume-coupled-diffusion/metadata.yaml b/volume-coupled-diffusion/metadata.yaml index c80aeca3f..757942fcb 100644 --- a/volume-coupled-diffusion/metadata.yaml +++ b/volume-coupled-diffusion/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Volume coupled diffusion path: volume-coupled-diffusion # relative to git repo url: https://precice.org/tutorials-volume-coupled-diffusion.html diff --git a/volume-coupled-flow/metadata.yaml b/volume-coupled-flow/metadata.yaml index d6234cf05..559539c19 100644 --- a/volume-coupled-flow/metadata.yaml +++ b/volume-coupled-flow/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Volume coupled flow path: volume-coupled-flow # relative to git repo url: https://precice.org/tutorials-volume-coupled-flow.html diff --git a/water-hammer/metadata.yaml b/water-hammer/metadata.yaml index 190287b0a..f7c1903ee 100644 --- a/water-hammer/metadata.yaml +++ b/water-hammer/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Water hammer path: water-hammer # relative to git repo url: https://precice.org/tutorials-water-hammer.html diff --git a/wolf-sheep-soil-creep/metadata.yaml b/wolf-sheep-soil-creep/metadata.yaml index 0cf1ca53d..c04bf594a 100644 --- a/wolf-sheep-soil-creep/metadata.yaml +++ b/wolf-sheep-soil-creep/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Wolf-sheep-grass soil creep path: wolf-sheep-soil-creep url: https://precice.org/tutorials-wolf-sheep-soil-creep.html From 51dc5aecb742053c21a41108a2091fad2316cd81 Mon Sep 17 00:00:00 2001 From: NopeCharon <115794254+NopeCharon@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:01:18 +0530 Subject: [PATCH 2/2] Add changelog entry for the YAML schemas --- changelog-entries/948.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog-entries/948.md diff --git a/changelog-entries/948.md b/changelog-entries/948.md new file mode 100644 index 000000000..a37fb4ef1 --- /dev/null +++ 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) \ No newline at end of file