home page
Overview Table of

How to Use this Document

If you are new to the OrganSpec standard, you should start by reading all of this Overview. After that, you should probably start with the Organ element and work downward from there. If you'd rather just dive in headfirst, take a look at the example. To learn about how to deal with specific organ features, try the Index, Glossary and How-To.


A familiarity with XML is helpful in understanding this document, but it is not required. You may want to look at the XML Overview.

Some familiarity with pipe organs is required, or very little of this will make sense.

General Structure of an OrganSpec

An OrganSpec consists of elements which represent major features of a pipe organ, such as stops, ranks, couplers, consoles, keyboards, chambers, etc. The topmost or outermost element is the Organ, which represents one entire organ.

The OrganSpec standard provides a fair amount of flexibility in how a specification is formatted. This flexibility allows simple specifications to avoid unnecessary complexity, while providing enough power to represent large and complex specifications. It's possible to get overwhelmed by the level of detail allowed by the various elements; look at the example to see how simple an OrganSpec can be.

In a simple specification, the Organ specification might contain a Location element to describe where the organ is located, a Builder element to describe the organ builder, a Source element to describe where the specification was copied from, and one Keyboard element for each manual or pedal keyboard. The Keyboard elements would contain some number of Stop elements, and perhaps some Coupler elements.

In a more complex specification, the Organ element might contain Chamber elements to describe the chambers and the Console elements to describe multiple consoles. The Chamber element might contain one Rank element for each rank of pipes. The Console element would contain the Keyboard and Coupler elements, and perhaps a Division element to describe a floating division.

Element Descriptions

Each element is described on its own page, which has the following sections:

Order of Elements

In general, the order in which elements occur does not convey any information, is not significant, and is not guaranteed to be maintained. Ordering information may be specified through the use of the "order" attribute which is allowed in many elements.


Many elements within an OrganSpec may optionally have installation and/or removal dates associated with them. This allows one OrganSpec to record not just a single snapshot in time of an instrument, but how it was altered over time. Interesting historical events regarding an organ, which do not fit into some other element, can be stored in a History element.


The OrganSpec standard is designed to capture a great deal of interesting information about an organ in a way which can easily be processed by software. A Remark element is available for storing information which doesn't fit anywhere else.

Language Independence

The OrganSpec standard is designed to allow OrganSpecs to be independent of any language, and to allow rendering in human-readable form in any language. Free-form narrative text is allowed only in the Remark element, which contains a required "language" attribute for specifying the language of the remark, and allows the simultaneous inclusion of the same remark in multiple languages.

Character Set

The XML standard provides for a specification of the character set being used. To maximize compatability, only the "UTF-8" character set should be used. To maximize transmittability over the internet, only ASCII (7-bit) characters should be used. (ASCII is a subset of UTF-8). If a NON-ASCII character is needed, then it should be encoded as one of the character entities, which are intentionally compatible with HTML. Accents should not be dropped, nor should they be approximated using ASCII characters. For example:

Original   Correct Incorrect
Baßflöte Baßflöte   Bassflote, Baßflöte, BaBflo"te
Flûte à Bec   Flûte à Bec   Flute a Bec, Flûte à Bec, Flu^te a' Bec

Outstanding Issues

Copyright © Institute for Pipe Organ Research And Education, Inc. 2002