Fix #403 : Add YAML schemas for components, tests, and metadata .

tools/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
   repository: https://github.com/precice/precice
   template: component-templates/bare.yaml

tools/tests/schemas/component-template.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://precice.org/schemas/component-template.schema.json",
+  "title": "preCICE Component Template (Docker Compose Service Fragment)",
+  "description": "Schema for component template YAML files. These are Jinja2 templates that render into a single Docker Compose service definition. The rendered output follows a subset of the Docker Compose service specification. Note: Jinja2 template expressions ({{ ... }}, {% ... %}) are present in the raw files and will not validate against this schema directly — this schema describes the expected *structure* of the template.",
+  "type": "object",
+  "required": ["build", "depends_on", "volumes", "command"],
+  "additionalProperties": false,
+  "properties": {
+    "build": {
+      "type": "object",
+      "description": "Docker build configuration for the service image.",
+      "required": ["context", "args", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "Build context path (Jinja2 template variable: {{ dockerfile_context }})."
+        },
+        "args": {
+          "description": "Build arguments passed to Docker. Rendered from Jinja2 loop over build_arguments.",
+          "oneOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "description": "Build argument in KEY=VALUE format."
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "target": {
+          "type": "string",
+          "description": "The Docker multi-stage build target to use (e.g., 'precice', 'openfoam_adapter', 'fenics_adapter')."
+        }
+      }
+    },
+    "depends_on": {
+      "type": "object",
+      "description": "Service dependencies. Typically depends on the 'prepare' service.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "condition": {
+            "type": "string",
+            "description": "Condition for the dependency (e.g., 'service_completed_successfully').",
+            "enum": [
+              "service_started",
+              "service_healthy",
+              "service_completed_successfully"
+            ]
+          }
+        },
+        "required": ["condition"],
+        "additionalProperties": false
+      }
+    },
+    "volumes": {
+      "type": "array",
+      "description": "Volume mounts for the service container.",
+      "items": {
+        "type": "string",
+        "description": "Volume mount in HOST:CONTAINER format."
+      }
+    },
+    "command": {
+      "description": "The command to run inside the container. Typically a bash script that changes to the case directory and executes the run command.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    }
+  }
+}

tools/tests/schemas/components.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://precice.org/schemas/components.schema.json",
+  "title": "preCICE System Test Components",
+  "description": "Schema for defining adapter components used in preCICE system tests. Each component maps to a Docker build target and a Jinja2 service template.",
+  "type": "object",
+  "additionalProperties": {
+    "$ref": "#/definitions/component"
+  },
+  "definitions": {
+    "component": {
+      "type": "object",
+      "description": "A component (adapter) definition including its repository, Docker Compose service template, and build arguments.",
+      "required": ["repository", "template", "build_arguments"],
+      "additionalProperties": false,
+      "properties": {
+        "repository": {
+          "type": "string",
+          "description": "The GitHub repository URL for this component (e.g., 'https://github.com/precice/openfoam-adapter').",
+          "format": "uri"
+        },
+        "template": {
+          "type": "string",
+          "description": "Relative path to the Jinja2 service template YAML file (e.g., 'component-templates/openfoam-adapter.yaml').",
+          "pattern": "^component-templates/.+\\.yaml$"
+        },
+        "build_arguments": {
+          "type": "object",
+          "description": "Docker build arguments passed when building images for this component. Common arguments include PLATFORM, PRECICE_REF, and adapter-specific refs.",
+          "additionalProperties": {
+            "$ref": "#/definitions/build_argument"
+          }
+        }
+      }
+    },
+    "build_argument": {
+      "type": "object",
+      "description": "A single build argument with its description, default value, and optional value constraints.",
+      "required": ["default"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what this build argument controls."
+        },
+        "semnantic": {
+          "type": "string",
+          "description": "Semantic description of the build argument (alternative to 'description', used in some components)."
+        },
+        "default": {
+          "type": "string",
+          "description": "The default value for this build argument, used when not overridden via command-line."
+        },
+        "value_options": {
+          "type": "array",
+          "description": "An optional list of allowed values for this argument. If omitted, any value is accepted.",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

tools/tests/schemas/metadata.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://precice.org/schemas/metadata.schema.json",
+  "title": "preCICE Tutorial Metadata",
+  "description": "Schema for tutorial metadata.yaml files that describe a preCICE tutorial, its participants, and available solver cases.",
+  "type": "object",
+  "required": ["name", "path", "url", "participants", "cases"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable name of the tutorial (e.g., 'Flow over heated plate')."
+    },
+    "path": {
+      "type": "string",
+      "description": "Relative path of the tutorial directory within the tutorials repository (e.g., 'flow-over-heated-plate')."
+    },
+    "url": {
+      "type": "string",
+      "description": "URL to the tutorial's documentation page on precice.org.",
+      "format": "uri"
+    },
+    "participants": {
+      "type": "array",
+      "description": "The list of coupling participants in the simulation (e.g., ['Fluid', 'Solid']).",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "cases": {
+      "type": "object",
+      "description": "A mapping of case names to their definitions. Each case represents a solver setup for a specific participant.",
+      "additionalProperties": {
+        "$ref": "#/definitions/case"
+      }
+    }
+  },
+  "definitions": {
+    "case": {
+      "type": "object",
+      "description": "A case definition specifying which participant it serves, the directory, run command, and which component (adapter) it uses.",
+      "required": ["participant", "directory", "run", "component"],
+      "additionalProperties": false,
+      "properties": {
+        "participant": {
+          "type": "string",
+          "description": "The participant this case belongs to. Must match one of the entries in the top-level 'participants' list."
+        },
+        "directory": {
+          "type": "string",
+          "description": "Relative path to the case directory within the tutorial (e.g., './fluid-openfoam')."
+        },
+        "run": {
+          "type": "string",
+          "description": "The command to execute this case (typically './run.sh')."
+        },
+        "component": {
+          "type": "string",
+          "description": "Name of the component (adapter) from components.yaml that this case uses (e.g., 'openfoam-adapter', 'fenics-adapter')."
+        }
+      }
+    }
+  }
+}

tools/tests/schemas/tests.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://precice.org/schemas/tests.schema.json",
+  "title": "preCICE System Tests",
+  "description": "Schema for defining system test suites that specify which tutorial-case combinations to run and their expected reference results.",
+  "type": "object",
+  "required": ["test_suites"],
+  "additionalProperties": false,
+  "properties": {
+    "test_suites": {
+      "type": "object",
+      "description": "A mapping of test suite names to their definitions. Each test suite groups a set of tutorial runs.",
+      "additionalProperties": {
+        "$ref": "#/definitions/test_suite"
+      }
+    }
+  },
+  "definitions": {
+    "test_suite": {
+      "type": "object",
+      "description": "A test suite groups one or more tutorial runs with specific case combinations.",
+      "required": ["tutorials"],
+      "additionalProperties": false,
+      "properties": {
+        "tutorials": {
+          "type": "array",
+          "description": "The list of tutorial runs included in this test suite.",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/tutorial_run"
+          }
+        }
+      }
+    },
+    "tutorial_run": {
+      "type": "object",
+      "description": "Defines a single tutorial execution with a specific case combination and its reference result.",
+      "required": ["path", "case_combination", "reference_result"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "The relative path of the tutorial directory (e.g., 'flow-over-heated-plate', 'perpendicular-flap'). Must match a tutorial's 'path' field in its metadata.yaml."
+        },
+        "case_combination": {
+          "type": "array",
+          "description": "An ordered list of case names that form the combination to run. Each name must match a case defined in the tutorial's metadata.yaml.",
+          "minItems": 2,
+          "items": {
+            "type": "string",
+            "description": "Name of a case (e.g., 'fluid-openfoam', 'solid-calculix')."
+          }
+        },
+        "reference_result": {
+          "type": "string",
+          "description": "Relative path to the reference result archive (.tar.gz) used for field comparison.",
+          "pattern": ".*\\.tar\\.gz$"
+        }
+      }
+    }
+  }
+}

tools/tests/tests.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=schemas/tests.schema.json
 test_suites:
   openfoam_adapter_pr:
     tutorials: