Project file syntax

Project files .prj have to be valid XML documents. For information of specific tags see our Doxygen-documentation.

Two methods allow you to modularize your project files and avoid repetition:

Option 1: Include XML-content from other files

The <include file="other_file.xml" />-tag allows to include the content of another XML into the current project file.

Limitation: Only one child include-element per (regular) XML-element is allowed.



        <include file="../cube_1x1x1_SteadyStateDiffusion/SteadyStateDiffusion.xml"/>


        <secondary_variable internal_name="darcy_velocity" output_name="v"/>

Note on file encoding

Please do not use UTF-8 with BOM-encoding! The BOM-marker from the included file will be included somewhere in the middle of the final prj-file and this will cause OGS’ ConfigTree to crash. In a text editor you typically can convert a file to other encodings. Please also check your text editor for default encodings on creating new files. In general UTF-8 or ISO 8859-1 should be fine.

Option 2: Apply patch files to the project file

Patch files contain <replace>, <add> and <remove>-elements with XPath-selectors to modify a specific part of the project file (in-memory during run-time):


<?xml version="1.0" encoding="ISO-8859-1"?>
    <add sel="/*/time_loop/output/prefix/text()" pos="after">_neumann</add>
    <replace sel="/*/parameters/parameter[2]/name/text()">p_neumann</replace>
    <replace sel="/*/parameters/parameter[3]/name/text()">p_Dirichlet</replace>
    <replace sel="/*/parameters/parameter[3]/value/text()">1</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]/parameter/text()">p_Dirichlet</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/type/text()">Neumann</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/parameter/text()">p_neumann</replace>
    <add sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]" pos="after">

Option 2a: Supply patch file(s) additionally to the prj-file

ogs -p path/to/square_1e0_neumann.xml [other/optional/patch_file.xml] path/to/square_1e0.prj

Supplied patch files are applied in the given order.

Option 2b: Use a patch file directly

If the patch file specifies a base_file:


<?xml version="1.0" encoding="ISO-8859-1"?>
<OpenGeoSysProjectDiff base_file="cube_1e0.prj">
    <replace sel="/*/mesh/text()">cube_1x1x1_hex_1e1.vtu</replace>
    <replace sel="/*/time_loop/output/prefix/text()">cube_1e1</replace>

you can just pass this patch file:

ogs path/to/cube_1e1.xml

In this case you have just one patch file.

Combination of include and patch method

When both methods are combined the logical order is the following:

  1. Apply patches
  2. Insert includes
  3. Apply patches marked with after_includes="true"-attribute only.


<?xml version="1.0" encoding="ISO-8859-1"?>
<OpenGeoSysProjectDiff base_file="cube_1e0.prj">
    <!-- The first line is run before the includes: -->
    <replace sel="/*/mesh/text()">cube_1x1x1_hex_1e1.vtu</replace>
    <!-- The following is evaluated after the includes are run: -->
    <replace sel="/*/time_loop/output/prefix/text()" after_includes="true">cube_1e1</replace>

Check project file syntax with xmllint

You can check the formatting with the xmllint-tool:

xmllint --noout myproj.prj

Install xmllint

We recommend to install via Chocolatey:

choco install xsltproc

Alternative installation

Another method is to use the Windows Subsystem for Linux where you can simply install Linux packages:

sudo apt-get install libxml2-utils
sudo apt-get install libxml2-utils

xmllint is part of the Homebrew xmlstarlet package:

brew install xmlstarlet

This article was written by Lars Bilke. If you are missing something or you find an error please let us know.
Generated with Hugo 0.101.0 in CI job 237559 | Last revision: September 7, 2022
Commit: [ci] Added job build wheels linux. 39ce500ae  | Edit this page on