Schema Files

Schema File Format
Installing Schemas
Schema File DTD

This chapter covers the mechanics of writing and installing the GConf schema files. Schema files describe your configuration data and provide default values for it. See the section called “Schemas” for an explanation of schemas. The schema file is not understood by the GConf client library; rather, gconftool (see gconftool Utility Program) knows how to parse it, and then uses the GConf client library to install the information in the GConf database.

Schema File Format

Here is a sample schema file for a hypothetical application, basic-gconf-app, one of the examples that comes with the GConf distribution.

Example 1. Sample schema file

<gconfschemafile>
    <schemalist>
      <schema>
      <key>/schemas/apps/basic-gconf-app/fooandbar</key>
      <applyto>/apps/basic-gconf-app/foo</applyto>
        <applyto>/apps/basic-gconf-app/bar</applyto>
      <owner>basic-gconf-app</owner>
      <type>string</type>
      <locale name="C">
        <default>Blah blah blurgh</default>
        <short>short description in C locale</short>
        <long>long description of foo and bar in C locale</long>
      </locale>
      <locale name="no">
        <default>some thing in norwegian</default>
        <short>short description in Norway</short>
        <long>Long description in Norway. long long long. this is a long sentence.</long>
      </locale>
    </schema>
      <schema>
      <key>/schemas/apps/basic-gconf-app/baz</key>
      <applyto>/apps/basic-gconf-app/baz</applyto>
      <owner>basic-gconf-app</owner>
      <type>string</type>
      <locale name="C">
        <default>Zzzzzzzzzz</default>
        <short>short description in C locale</short>
        <long>long description of baz in C locale</long>
      </locale>
      <locale name="no">
        <default>some thing in norwegian</default>
        <short>short description in Norway</short>
        <long>Long description in Norway. long long long. this is a long sentence.</long>
      </locale>
    </schema>
      <schema>
      <key>/schemas/apps/basic-gconf-app/blah</key>
      <applyto>/apps/basic-gconf-app/blah</applyto>
      <owner>basic-gconf-app</owner>
      <type>string</type>
      <locale name="C">
        <default>bllllllaaaaaaaaaaaaaaaaarrrrrrggggggghhhhh</default>
        <short>short description in C locale</short>
        <long>long description of blah in C locale</long>
      </locale>
      <locale name="no">
        <default>some thing in norwegian</default>
        <short>short description in Norway</short>
        <long>Long description in Norway. long long long. this is a long sentence.</long>
      </locale>
    </schema>
  </schemalist>  
</gconfschemafile>

The file format is straightforward. The root node must be called <gconfschemafile>. This element contains one or more <schemalist> elements; I can't think of a reason to use multiple <schemalist> elements, but you can if you want, and gconftool will load each one. The <schemalist> in turn contains one or more <schema> elements. Each of these describes a single schema.

Warning

gconftool is not very tolerant about whitespace right now; in particular it won't strip whitespace from around key names, type names, etc. This is broken and will be fixed, just watch out for now.

Here are the fields of the <schema> element:

<key>	The key where the schema will be stored; see GConf Conventions for naming conventions. There may be only one key per schema.
<applyto>	A key the schema will be applied to; that is, this schema describes this key. See GConf Conventions for naming conventions. There may be multiple <applyto> elements.
<owner>	Name of the application that uses this schema; may be the command line name, or a human-readable name. However you should use the same value for <owner> for all schemas your app installs. The primary purpose of this field is to enable sysadmins to locate the keys belonging to a given application.
<type>	The type of values described by this schema. i.e. keys the schema is applied to should store values of this type. Allowed values are: `string`, `int`, `bool`, `float`, `list`, `pair`
<default>	The `<default>` element may appear below `<schema>` (a default for all locales, often suitable for numeric values), OR below a `<locale>` element, if the default should be localized. It simply contains the default value for the keys the schema is applied to.
<locale>	The `<locale>` element contains locale-specific data, including the human-readable short and long descriptions, and optionally the default value (`<default>` may also be placed directly underneath the `<schema>` element). There should be one `<locale>` element for each locale, with a `name` attribute specifying the locale name.

A <locale> element can contain a locale-specific <default>, and may also contain short and long descriptions as follows:

<short>	A short description of the purpose of this key, around 40 characters long (about half a line).
<long>	A long description of the configuration key, around a paragraph or two. Should describe the possible values of the key and their effect on the application.