Welcome at Open Config Dot Org

Motivation or "What is this site about?"

When working with different software we noticed that every program has a different strategy for the layout and location of its configuration files. Some have one, most have more that one file. Some locate them on logical places, for some you can search for "hours". Often, when a parameter is changed, it does not make a difference because there is an other config file with a different name somewhere else that takes precedence. At other times you only want to change one parameter, risking to disturb normal operation by editing in the config file. In other words, a mess.

The world would be a better place when all programs would organize their config files in the same manner! In this document we want to make a modest start.

Objectives or "How to make the config-world a somewhat better place"

We discuss guidelines and best-practices for organizing your config files so that, to our opinion, it makes handling more easy. When your users have a fixed framework in mind and your config file conforms to that framework, your user can focus directly on the task, without first trying to understand your design logic.

These guidelines

• . .. are easy to understand and implement for the programmer
• . .. make sure your users really can find and understand your configurable parameters
• . .. makes configuration automatable
• ... can be read within one hour

These guidelines

• ... are not limiting your freedom to design your own config file structure

The guidelines

OK, no more bla bla, we have 55 minutes left so here are the guidelines: (for the moment, this is not really structured, that will come in time)

General properties

• Config files are in XML.
• Config files may contain a reference to a doc-type or schema specification.
• If a config file contains such a reference ,validation against this document must ensure acceptance of the config file by the application.
• There are three levels of config: master, user and temporary.

Master config

• There will be only one master config file per application.
• The master config is located in the same directory as the application
• The master config is called your_application_name.conf
• The master config contains a symbolic, but no explicit, reference to the location of its user config files.
• The master config contains all adjustable parameters.
• The application may not contain any default values for outside adjustable parameters, all parameters must be present in the master config.
• The master config may "include" other files trough a valid and complete reference.

User config

• There will be only one user config per user.
• The user config is located in the users directory or in one of its child's directories
• The user config is called your_application_name.conf, it may be preceded by a dot.
• The user config need not to contain all parameters, but may not contain any new parameters not present in the master config
• The user config contains a valid and complete reference to the master config.
• The user may "include" other files trough a valid and complete reference.

Temporary config

• Any user is free to define as many temporary config files to his or her liking.
• The temporary config is located at the users choice
• The temporary config is named at the users choice, however must be ending with .conf
• The temporary config need not to contain all parameters, but may not contain any new parameters not present in the user config.
• The temporary config may "include" other files trough a valid and complete reference.

Handling of config files.

• The application first loads the master config files.
• The application subsequently loads the user config of the current user, all parameters present in this config file take precedence over the master values.
• The application finally loads, if appropriate, the temporary config file, which take precedence over the user values.

Use of XML

• The root node of the config file is: <config scope="master">, or <config scope="user"> or <config scope="temporary">
• Tags defined by the programmer start with a capital, tags stemming from this specification are all lower case.
• Structure of the XML tree is free, with the following restrictions.
• CDATA blocks are not allowed
• Attributes may only be used for type specification of the element content. No user adjustable data may be contained in attributes.

Parameters of the application regarding the config file

• When nothing is specified, the application only loads the master config file and the user config file if present.
• A temporary config file can be specified as follows: your_application_name --config temp.conf
• To see if the configuration files are valid the application must support the following keyword: --config-test. The application may not do anything else but test all loaded config files and report errors if present.
• In the situation that no user config files are wanted, the application must accept the keyword --config-no-user
• The keywords above may be used in any combination

Versioning

• The master config file contains an element <version>your_version_number</version>, directly under the root.
• The application checks if the version of the application is identical with the version of the config files.
• If case the versions are not identical but all necessary fields to continue operation are present, the application issues a warning.
• If case not all necessary fields to continue operation are present, the application terminates with and exception, irrespective of the version numbers.

Your data

For every particular parameter that may be modified by the user, the following structure will be used at the bottom of the tree.

  <Your_Parameter_Name>
    <value>the_value</value>
    <choosefrom>the_first_value,the_second_value,the_third_value</choosefrom>
    <default>the_default_value</default>
    <description lang="us"> The description with a lot of bla bla. </description>
    <modified>name and date of modifier</modifier>
  </Your_Parameter_Name>

Note the following

• The element <value> is required.
• The element <choosefrom> is required whenever there number of possibilities is limited or a description must be given about the form of the input. The format for this description is free, but should be clear to the user, checking is done by the application. If there is a limited number of possibilities they must all be listed here.
• The element <default> is optional
• The element <description> is required for at least one language. The language specification is required in order to let the application make use of it in help or hints.
• The element <description> may contain simple html markup, such as <ul>, <li> etc.
• The element <modified> is optional, and may be used by the user of your program to

Proposed changes

This is a standard in the making. Therefore there already proposed changes

• Change the default behaviour. If defaults and values are split over different files, it is much easier to modify only a few parameters and to see the size of the adjustments. We would than get the following stack
  • master-default
  • master
  • user-default
  • user
  • temporary

  The none default files can be generated at installation and may than contain installation dependent values such as paths etc.