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.96.0. Last revision: February 16, 2022
Commit: explanation stress concentration and running model 5c94789  | Edit this page on