Related Topics

Structure and Syntax of the Design File

The Domain Design File

Uploading a Design File to a Domain

The Domain Design File

The relationship between item definitions, column definitions, and actual database columns is the essence of the Domain itself and must be maintained when editing the design file. In order to be usable when uploaded to a Domain, a design file must meet the following conditions:

It must be well-formed XML. This means that all syntax, spelling, and punctuation is correct so that the file contains a hierarchy of elements, attributes, and content.
It must be valid with regards to the XML schema.

The XML schema defines element and attribute names that are allowed and how they are nested to create a hierarchical structure. This ensures that the elements and attributes are the same ones with the same meaning used by Zoola™. The XML schema of a Domain design is given in the XSD file located in: <install-dir>/samples/domain-xsd/schema_1_0.xsd

The design file must be internally consistent and define all the necessary elements of a Domain design. These are constraints that cannot be expressed in the XSD file because they are outside the scope of an XML schema.
The tables and columns in the design must be consistent with their external definition in the data source of the Domain.

The more complex elements of a design file have additional constraints:

SQL queries for a derived table must be valid. The tables and columns in the query must exist in the data source, and the columns in the results must match those declared in the design.

Expressions for filters and calculated fields must be valid programmatic expressions in a local format called the Domain Expression Language (DomEL).

The design of a Domain is stored internally in the repository. The XML is only a representation from which the design can be inferred, and it may have some validity errors that cannot be detected. As a result, the Domain resource and the XML may not remain totally synchronized through several cycles of exporting to XML, editing, and uploading. For example, the Domain Designer sometimes renames the result of a join (JoinTree_1), which affects the security file.

However, the Domain Designer also has limitations and cannot create some valid designs. For example, in a design file, you may select the columns of a table whereas you can only select whole tables on the Tables tab. Furthermore, the Domain Designer cannot read some valid designs, in which case you must not open the uploaded design file in the Domain Designer. These rare cases are documented in the following sections.

As with any XML file, a design file is plain text and can be edited in any text editor. The server exports well- formatted XML, and if you want to make only a few changes or simple additions, a text editor is sufficient. For editing the content of the design file, a specialized XML editor ensures that the design file is well-formed, so you don't introduce other errors. If you want to make structural changes or write a design file from scratch, use an XML editor that understands the XML schema in the schema_1_0.xsd file. By loading both the XML and XSD files, this type of XML editor lets you insert elements and attributes only in the places they are allowed to ensure that the design file is valid.

However, no editor can enforce the internal and external constraints on a design file. The following section explains all of the possible elements and attributes of an XML design file and the various constraints you must maintain on each of them.