Create Schema Guide

The formal structure of an XML document is often defined using XML Schemas. A schema defines a class of XML documents, and an XML document that belongs to the class of XML documents is said to conform to the schema.

Schemas can be used when discussing or formalizing XML interfaces as they offer a formal, accepted way to describe the structure of XML documents.

In TransacXML the structure of an XML document is defined using triples and objects - also called an XML model. From the XML model TransacXML can create a schema representation of the XML document structure thereby defining the class of XML documents that can be processed by the XML model.

Schemas are themselves XML documents, which makes them easier to process automatically than the corresponding DTDs.

Schemas and Namespaces

All elements in one schema belong to the same namespace - this is defined in the schema element's targetNamespace attribute.

A natural extension of this is that it is necessary to create a separate schema file for each namespace used in the document. These files can refer to each other using the import element.

One schema file can contain information about several documents and sub elements of documents, as long as they belong to the same namespace.

Limitations

W3C schemas are very versatile and can express a number of situations, which will only very rarely occur in real life applications. A couple of these situations are not fully supported by TransacXML. A brief description of each known limitation is given below.

Fields in own namespace

It is possible to define that a field (simple element) has a different namespace than the XMLElement entity, which it is contained in.

In this case a schema containing information about the XMLElement entity's namespace and a schema containing information about the field's namespace should be created together with a reference from the schema for the XMLElement entity to the schema for the field.

This situation is not fully handled by TransacXML when the XML schema file is generated. The panel requesting the filename for the namespace for the field will be shown, but the schema file defining the field will not be created.

The schema for the XMLElement entity will be complete; it will have an import statement for the file entered in the prompt window and the field will refer to the field from this file.

This means you must create the schema file defining the namespace for the field manually.

Namespace for element reoccurs in the sub tree of the element

This is only an issue, if an element in one namespace refers to an element in another namespace, which then refers back to the first namespace.

Example

When the CreateSchema function for ItemList is executed, the prompt panel, where the filename for the schema is entered, will be shown three times:

When the prompt panel is shown the third time, you are not allowed to enter the same file as you did the first time - even though it is the same namespace. The file does not exist on the disk at this moment.

You will have to enter a new file, which will then contain the information regarding the child element of the ItemList.Item element.

After the generation is finished you can manually move the information from this schema file to the schema file defined for the ItemList element.

Namespaces without prefixes

Defining a namespace for elements without defining a prefix for them is equivalent to declaring the namespace as default namespace for the part of the document scoped under the element.

In most definitions, the namespace, which the top element of the document belongs to, is defined as the default namespace (if any default namespace is used).

It is also legal to define a default namespace on one or more sub elements, even though this is not a recommended approach.

The CreateSchema functions use the prefix to refer to the elements in the schema. This means that if an XMLElement entity has a namespace defined, different from the namespace of the parent XMLElement entity, and has no prefix defined, you will have to enter the prefixes manually in the schema defining the namespace for the parent element.

The necessary changes are: insert prefix in the xmlns declaration of the child's namespace, insert prefix in the ref attribute for the declaration of the child element.

It is strongly recommended to have at most one default namespace (no prefix specified) for each XML model and to let this namespace be the namespace of the topelement of the document, thereby avoiding the problem described in this section.

Implementing

The following is an example, which shows how to create a schema based on the ItemList document, defined in the TransacXML tutorial.

Inherit from XmlElementWithServiceFunctions

All of the XMLElement entities, which are part of the document, must inherit from XmlElementWithServiceFunctions, as this is the entity, which includes the CreateSchema function:

Please note that XmlElementWithServiceFunctions inherits from XmlElement. This means that it is not necessary to inherit from both XmlElement and XmlElementWithServiceFunctions, although it does no harm to inherit from both library entities.

The XmlRepeatingElement on the other hand contains a function, which is not scoped by the XmlElementWithServiceFunctions entity. This means that an XMLElement entity has to inherit from both the XmlElementWithServiceFunctions and the XmlRepeatingElement if it is both a repeating element and part of a document, which a schema should be created for.

Special Case for Java functions

When using the Java version you must create an additional function. This function calls the CreateSchema function of the topmost XMLElement of the document.

This is done by creating your own instance of the abstract function StartCreateSchema:

This function will show a panel, where you can enter the position of the file which you want to contain the schema.

This extra function is necessary for the Java version as an error in the Plex Java runtime otherwise will terminate the CreateSchema function without giving you the possibility to enter the necessary data.

Generate and build library functions

A number of service functions must be generated and built. Some of these service functions are in most cases already generated and built to make it possible to handle the XML documents. If this is the case, it is not necessary to generate and build these objects again.

Generate and build the functions contained in the following library subject areas

Generate and build CreateSchema and GetName functions

All of the CreateSchema and GetName functions scoped by XMLElement entities, which are part of the document, must be generated and built.

Run the CreateSchema function

(Windows only) When executing the CreateSchema function from the Generate and Build window it is necessary to create an EXE file for the CreateSchema. If no EXE file is created the CreateSchema function is unable to load the Websydian TransacXML runtime dll (WsydXml11.dll).

The following sections describe the behavior of the CreateSchema function for different combinations of namespace definitions in the XML model.

No Namespaces used in the document

As the ItemList element does not belong to a namespace, no value is shown for the Target Namespace.

In the field Schema File enter the full path to the file where the schema should be saved.

It is recommended to use the ".xsd" extension for the schema files, as this will make them recognizable as schemas for most application programs.

Press OK and the schema will be created and saved to the file. If you just enter the filename without a path, the file will be saved to the current folder. If the CreateSchema function is executed from the generate and build window the current folder is:

The "Use existing file" option has a default value of "No". This means that if a file with the indicated location exists, it will be overwritten.

If the validation does not return an error, the definition for the ItemList element is added as a new global definition (an element which is a child of the schema element itself).

If an element with the name ItemList already exists in the schema file, no further processing is done - as it is not possible to have more than one global definition with the same name in a schema.

This is a way of extending an existing schema file to contain new global definitions - and thereby define elements belonging to more than one document in one schema file.

One namespace defined for the document

This is the scenario that occurs in most real life situations: one namespace is defined, which the document then belongs to.

The namespace for the ItemList element is then defined in the source code object CommonXml.ItemList.Namespace as http://www.websydian.com/CreateSchema/Item (for more details about namespaces in TransacXML see here).

After the above change the CreateSchema and GetName functions for the ItemList and Item elements must be generated and built.

The only difference from the previous situation is that the namespace is shown - and the only difference in the created schema will be that a targetNamespace attribute is added to the schema element.

Several namespaces defined for the document

This is a somewhat more complex situation. As one schema can only contain information about one namespace, the CreateSchema function creates several files (one for each namespace).

In this example a namespace is also defined for the Item element (http://www.websydian.com/CreateSchema/ItemInformation). This means that the ItemList element belongs to one namespace and the Item element belongs to another.

In order to specify a namespace for the Item element the ItemList.Item entity must inherit from NamespaceAware:

The namespace is entered in the source code object CommonXML.ItemList.Item.Namespace and a prefix is entered in the source code object CommonXML.ItemList.Item.Prefix (this example uses the prefix IT).

It is necessary to specify a prefix for the second namespace as this is used during schema generation, and it is only possible to have one default namespace in the schema. Please refer to the Namespaces without prefixes section for details.

When the CreateSchema function is called, the same panel as above will be shown:

After the path and filename has been entered and "OK" pressed, the processing continues.

A part of the document (the Item element) belongs to a different namespace. When the processing reaches this element the following panel is shown:

Enter the name of the file where you want to save the part of the schema belonging to the namespace http://www.websydian.com/CreateSchema/ItemInformation.

If a namespace is referred more than once in the document, the prompt panel will be shown for each occurrence of the namespace.

You can choose to save each occurrence in its own file - but it is recommended to use one file for each namespace.

Running the CreateSchema function from another program

The CreateSchema function can be called from another program. When this is done the location of the schema file must be passed as parameters. When the Schema File location is passed as a parameter to the CreateSchema function, the panel will not be shown.

Identifying errors

If errors occur during the execution of the CreateSchema function, the program terminates without saving the schema file.

The field CreateSchemaErrorDescription in the variable Output/Error will contain information about the function, which has thrown the error and, if possible, a textual description of the error.

When the CreateSchema function is executed from the generate and build window error messages can be seen by inserting the following code in the post point Start terminate in the called CreateSchema function:

If Output/Error<CreateSchemaErrorDescription> != <CreateSchemaErrorDescription.*Blank>
Cast Environment<*Message text>, Output/Error<CreateSchemaErrorDescription>
Dialog Message Message: OBJECTS/Message

Manually adjusting the content of the schema

The schemas created by the CreateSchema function are a correct description of the information represented in the Plex model.

However, schemas have the capability of expressing information, which is not represented in the model. If the schemas must contain such information, these changes must be applied manually after the schema is created.

Adjusting the schema location

When several namespaces has been used in the document, several files have been created (at least one for each namespace).

This element declares which namespace is imported and where to find the schema file containing the declarations for the imported namespace.

The CreateSchema function creates these import elements using the value entered in the prompt panel. So if you have entered e.g. c:\temp\ItemList.xsd - then this is what is written to the file.

If this schema has to be moved to another location or made available for external users, you would normally want to change this to either an URL or a relative reference such as the filename without a path.

MyStartCreateSchema	is a FNC	StartCreateSchema
MyStartCreateSchema	replaces FNC ...by FNC	XmlElementWithServiceFunctions.CreateSchema
MyStartCreateSchema	replaces FNC ...by FNC	CommonXml.ItemList.CreateSchema

Online documentation - Websydian v6.0