KiCad supports nesting schematics hierarchically to simplify the creation of complex designs. A hierarchical schematic uses hierarchical sheets (SCH_SHEET objects) to reference a given schematic file (SCH_SCREEN objects). Each SCH_SHEET corresponds to a schematic file handled by a SCH_SCREEN object. A SCH_SCREEN object contains schematic drawings and has a filename to read/write its data. It is imperative for developers to understand how hierarchies work in order to effectively understand the schematic editor code.

There are two fundamental type of hierarchies in KiCad, simple and complex.

A simple hierarchy is where one SCH_SHEET object is linked to exactly one SCH_SCREEN object.

A complex hierarchy is where a SCH_SCREEN object shared by more than one SCH_SHEET object. Therefore all sub-sheets of a shared sheet are by definition also be shared. This means that that items contained in the SCH_SCREEN object must handle data for more than a single sheet.

This is where SCH_SHEET_PATH objects are involved. Each SCH_SHEET object is assigned a UUID (KIID object) when created. These UUIDs are chained together to form a SCH_SHEET_PATH object that allows access of SCH_ITEM object instance data stored. Sheet paths have the form /ROOT_SHEET_UUID/SHEET_UUID/SUB_SHEET_UUID/... Sheet paths are store in the SCH_ITEM where they are require to access the items instance data. For example, symbol reference field and unit selection instance data are stored in the SCH_SYMBOL object. The sheet page number instance data is stored in the SCH_SHEET object.

For a given SCH_SCREEN SCH_SHEET_PATH objects must: 1) Handle all SCH_SYMBOL references, unit, and variant instance data. 2) Handle all SCH_SHEET page number and variant instance data. 3) Update the currently displayed SCH_SYMBOL references, SCH_SHEET page numbers, and variant data shown in the current SCH_SCREEN.

The SCH_SHEET_LIST object allows handling of the full or partial list of sheets and their paths in a hierarchy. The SCH_SCREENS object allows one to handle a list of SCH_SCREEN objects.