11. Splitting up a CPACS dataset into several files

A dataset can be split into several files, e.g. to keep a library of airfoils in files of its own and share it between datasets. An <externaldata> element, which may stand at any position of the dataset, takes the place of the content of external files. Its <path> names the directory of the files as a URI, and each following <filename> names one file in it. When the dataset is read, the root element of each file is inserted at the position of the <externaldata> element, which it replaces.

The following dataset takes two airfoils from external files, one <externaldata> element for each, and defines a third one itself:

<?xml version="1.0" encoding="utf-8"?>
<cpacs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="pathToSchemaFile/cpacs_schema.xsd">
    ...
    <vehicles>
        <profiles>
            <wingAirfoils>
                <externaldata>
                    <path>file://airfoils</path>
                    <filename>NACA0010.xml</filename>
                </externaldata>
                <externaldata>
                    <path>file://airfoils</path>
                    <filename>NACA2412.xml</filename>
                </externaldata>
                <wingAirfoil uID="NACA0012">
                    <name>NACA 0012</name>
                    <pointList>...</pointList>
                </wingAirfoil>
            </wingAirfoils>
        </profiles>
    </vehicles>
</cpacs>

Dataset with two airfoils in external files

An external file is a complete XML file whose root element is the element to be inserted:

<?xml version="1.0" encoding="utf-8"?>
<wingAirfoil uID="NACA0010">
    <name>NACA 0010</name>
    <pointList>...</pointList>
</wingAirfoil>

External file airfoils/NACA0010.xml

The schema does not define <externaldata>. A split dataset is therefore validated after its files have been merged.
An external file may contain <externaldata> elements itself. The files must not include each other in a cycle, e.g. file A including file B, which includes file A again.
A relative path is resolved against the directory of the main dataset, also where it stands in an external file.
The trailing separator / of a path may be omitted.

Paths are written as URIs, for example:

Location	Path
absolute local directory	`file:///tmp/airfoils`, `file:///c:/data/airfoils`
relative local directory	`file://airfoils`, `file://../library/airfoils`
remote resource	`https://www.example.org/airfoils`

The XML processor TiXI merges a split dataset into a single tree, which can then be validated against the schema. It marks each inserted element with three attributes, so that the dataset can be split again into the same files when it is saved:

Attribute	Meaning
`@externalFileName`	name of the file the element was read from, as in `<filename>`
`@externalDataDirectory`	directory of that file, as in `<path>`
`@externalDataNodePath`	path of the parent element in the merged dataset, i.e. where the `<externaldata>` element stood

The schema permits these attributes on every complex element, so that the merged dataset is valid. For an element read from an external file that was itself included by an external file, the path also refers to the merged dataset, e.g. /cpacs/vehicles/profiles/wingAirfoils/wingAirfoil[1]. Merged, the dataset of the example reads:

<?xml version="1.0" encoding="utf-8"?>
<cpacs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="pathToSchemaFile/cpacs_schema.xsd">
    ...
    <vehicles>
        <profiles>
            <wingAirfoils>
                <wingAirfoil uID="NACA0010" externalFileName="NACA0010.xml" externalDataDirectory="file://airfoils"
                             externalDataNodePath="/cpacs/vehicles/profiles/wingAirfoils">
                    <name>NACA 0010</name>
                    <pointList>...</pointList>
                </wingAirfoil>
                <wingAirfoil uID="NACA2412" externalFileName="NACA2412.xml" externalDataDirectory="file://airfoils"
                             externalDataNodePath="/cpacs/vehicles/profiles/wingAirfoils">
                    <name>NACA 2412</name>
                    <pointList>...</pointList>
                </wingAirfoil>
                <wingAirfoil uID="NACA0012">
                    <name>NACA 0012</name>
                    <pointList>...</pointList>
                </wingAirfoil>
            </wingAirfoils>
        </profiles>
    </vehicles>
</cpacs>

Dataset after merging the external files