toolspecificType

The toolspecific node holds data that a tool needs to store in a CPACS dataset but that CPACS itself does not define, e.g. tool settings, intermediate results or data whose definition in CPACS is still under development.

CPACS defines only the frame for this data: each tool writes its data into a tool element that is identified by name and version. The structure of the data itself is defined by the tool maintainer in a separate XML schema with its own namespace, the tool schema. The file schema/toolspecific_template.xsd in the CPACS repository is a starting point for such a schema.

Tool-specific data complements CPACS and does not replace it. Data that CPACS already defines should not be copied into the tool-specific part but referenced by its UID. Data that is of interest to other tools as well should be proposed as an extension of CPACS, see how to proceed with missing data.

1. Each tool writes its data into a tool element. Data of several tools is stored side by side as several tool elements.
2. name and version identify the tool that wrote the data. Both are required. version is the version of the tool, not the version of CPACS or of the tool schema.
3. name and version are followed by exactly one element, the root element of the tool data. A tool element without a root element, or with more than one, is invalid.
4. The root element and its content must be qualified with the namespace of the tool schema, e.g. by a namespace declaration xmlns="..." on the root element. A namespace is identified by a URI. It looks like a web address but is only a name: no tool opens or downloads it, it only has to be unique, and a web domain guarantees that. If the tool maintainer has no preference, http://www.cpacs.de/ followed by the name of the tool is proposed, such as http://www.cpacs.de/myTool in the examples below; otherwise the maintainer chooses a URI of their own.
5. The root element must be declared as a global element in the tool schema. The CPACS schema validates the tool data strictly (processContents="strict"): if the validator cannot resolve the tool schema, the whole CPACS dataset is invalid (see section 4).
6. The tool schema should state its own version, e.g. as a schemaVersion attribute of the root element, so that a reader can detect which version of the data structure it is processing.

The tool schema is linked in the root element of the dataset, next to the CPACS schema. xsi:schemaLocation holds pairs of namespace URI and schema file; for several tools, the pairs are listed one after the other, separated by whitespace.

<cpacs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="pathToSchemaFile/cpacs_schema.xsd"
       xsi:schemaLocation="http://www.cpacs.de/myTool pathToToolspecificSchemaFile/toolspecific_myTool.xsd">
    ...
</cpacs>

The data of a single tool is shown below. It corresponds to the example file examples/toolspecific.xml and validates against schema/toolspecific_template.xsd.

<toolspecific>
    <tool>
        <name>myToolName</name>
        <version>1.2.3</version>
        <myToolName xmlns="http://www.cpacs.de/myTool" schemaVersion="1.0">
            <parentElement>
                <childElement1>stringValue</childElement1>
                <childElement2>1.0</childElement2>
            </parentElement>
        </myToolName>
    </tool>
</toolspecific>

Each further tool adds a tool element with its own root element and namespace:

<toolspecific>
    <tool>
        <name>myToolName</name>
        <version>1.2.3</version>
        <myToolName xmlns="http://www.cpacs.de/myTool" schemaVersion="1.0">
            ...
        </myToolName>
    </tool>
    <tool>
        <name>anotherToolName</name>
        <version>0.9</version>
        <anotherToolName xmlns="http://www.cpacs.de/anotherTool" schemaVersion="2.1">
            ...
        </anotherToolName>
    </tool>
</toolspecific>

A dataset without tool data is validated against cpacs_schema.xsd as usual.

A dataset with tool data needs one more thing. The CPACS schema does not describe the tool data, so the validator also needs the tool schema. Without it, the validator reports the dataset as invalid even if all data is correct, with a message such as: Element '{http://www.cpacs.de/myTool}myToolName': No matching global element declaration available, but demanded by the strict wildcard.

Some validators find the tool schema by themselves, through the reference in the root element of the dataset (see section 3). TiXI (schemaValidateFromFile) and lxml (etree.XMLSchema) do not: they only use the one schema file they are given.

The solution is a small schema file that combines both schemas. It is given to the validator instead of cpacs_schema.xsd; neither the dataset nor the tool schema has to be changed. The file examples/toolspecific_combined.xsd does this for the examples:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Validate datasets with tool data against this file instead of cpacs_schema.xsd.
     It combines the CPACS schema with the schema of the tool in toolspecific.xml.
     Add one xsd:import per tool schema. -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:include schemaLocation="../schema/cpacs_schema.xsd"/>
    <xsd:import namespace="http://www.cpacs.de/myTool"
                schemaLocation="../schema/toolspecific_template.xsd"/>
</xsd:schema>

For your own tool, copy the file and adapt the two paths and, in xsd:import, the URI of your tool (see rule 4). The paths are relative to the copied file. For several tools, add one xsd:import line per tool.

How to read, write and validate tool data with lxml or TiXI is shown step by step in the scripts examples/python/toolspecific_lxml.py and examples/python/toolspecific_tixi.py.