<oXygen/> provides a special type of editor for XML Schema schemas. This editor presents the usual text view of an XML document synchronized in real time with a graphical view of the schema components.
The XML Schema editor of <oXygen/> enhances the content completion of the XML editor with special support for the elements and attributes of a Schematron schema inside the xs:annotation/xs:appinfo elements of an XML Schema.
<oXygen/> provides a simple, expressive and easy to read Schema Diagram View for XML Schema schemas.
With this new feature you can easily develop complex schemas, print them on multiple pages or save them as JPEG, PNG and BMP images. It helps both schema authors in developing the schema and content authors that are using the schema to understand it.
<oXygen/> is the only XML Editor to provide a side by side source and diagram presentation and have them synchronized in real-time:
the changes you make in the Editor will immediately be visible in the Diagram (no background parsing).
changing the selected element in the diagram will select the underlaying code in the source editor.
When you create a new schema document or open an existing one the Editor Panel is divided in two sections: one containing the Schema Diagram and the second the source code. The Diagram View has two tabbed panes offering a Full Model View and a Logical Model View.
The Full Model View renders all the XML Schema elements with intuitive icons. The following references can be expanded in place: elements, attributes, groups, assigned types, base types, substitution elements and identity constraints. This coupled with the synchronization support makes the schema navigation easy.
At the top of the diagram view there are buttons corresponding to the following actions:
It is a two state button. When it is turned on the diagram view presents only the top level definition of the schema from the cursor position and it is updated when the cursor goes to another definition. When it is turned off the view presents all the schema definitions.
This option controls how the schema diagram is automatically expanded. For instance if you select it and then edit a top level element or you make a refresh, the diagram will be expanded until it reaches referred components. If this is left unchecked, only the first level of the diagram is expanded, showing the top level elements.
For large schemas, the editor disables this option automatically.
Depending on its state (selected/not selected), the documentation nodes are shown or hidden.
Depending on its state (selected/not selected), the comment nodes are shown or hidden.
Refreshes the Schema Diagram according to the changes in your code (changes in your imported documents or those that are not reflected automatically in the compiled schema)
Prints the diagram. <oXygen/> will split and print your Schema on multiple pages if it is a large document. Each page will be surrounded with a frame and will contain information about the neighboring pages.
Saves the Schema Diagram as a JPEG Image.
The contextual menu offers quick access to:
Add Child: offers a list of possible items to be added as children of the current node.
Insert - Before: offers a list of possible items to be added before the current node.
Insert - After: offers a list of possible items to be added after the current node.
Edit: allows the user to edit the attributes of the current node. This action can also be triggered by double-clicking an element.
Remove: allows the user to remove the current element.
Also, the contextual menu offers access to the Collapse children, Expand children, Print, Print selection, Save as Image, Save Selection as Image and Refresh actions. The diagram can be saved as JPEG, PNG and BMP image.
The Logical Model View displays a diagram of the compiled schema. This is not synchronized automatically with the source editor and it is obtained after resolving the references, type extensions and type restrictions, redefinitions etc.
It presents the global elements that when expanded show the types and identity constraints. If an element has a simple type then the type name is rendered. If an element has a complex type then the content type and attributes are presented.
If the schema is not valid you will see an error message in the Logical Model View instead of the diagram.
The Diagram View also contains a Schema Components View showing the global components grouped by their namespaces and types. It allows a quick access to a component by knowing its name.
The view content depends on the selected view: in Full Model View it contains the global elements, attributes, simple types, complex types, groups, attribute groups. In Logical Model View it contains the global elements, grouped by their namespaces. It can be opened from
-> -> -> ->To create an XML Schema from the structure of a relational database table use the special wizard available in the Tools menu.
To generate sample XML files from an XML Schema use the Generate Sample XML Files... dialog. It is opened with the action ->
Complete the dialog as follows:
Schema's URL. Last used URLs are displayed in the drop-down box.
Displays the namespace of the selected schema.
After the list is selected, a list of elements is displayed in the combo box. The user should choose the root of the XML documents to be generated.
Path to the folder where the generated XML instances will be saved.
Generated files' names have the following format: prefixN.extension, where prefix and extension are specified by the user and N represents an incremental number from 0 upto Number of instances - 1.
The number of XML files to be generated.
When checked, the first generated XML file will be opened in editor.
Here the user can specify the default namespace as well as the proxies (prefixes) for namespaces.
The Options tab becomes active only after the URL field is filled-in and a schema is detected. It allows the user to set specific options for different namespaces and elements.
Allows the user to define settings for:
All elements from all namespaces. This is the default setting and it can also be accessed from Options -> Preferences -> XML / XML Instance Generator.
All elements from a specific namespace.
A specific element from a specific namespace.
When checked, all elements will be generated, including the optional ones (having the minOccurs attribute set to 0 in the schema).
When checked, all attributes will be generated, including the optional ones (having the use attribute set to optional in the schema.)
Controls the content of generated attributes and elements. Several choices are available:
None - No content is inserted;
Default - Inserts a default value depending of data type descriptor of the respective element/attribute. The default value can be either the data type name or an incremental name of the attribute or element (according to the global option from the XML instance generator preferences page);
Random - Inserts a random value depending of data type descriptor of the respective element/attribute.
Allows the user set the preferred number of repeating elements related with minOccurs and maxOccurs defined in XML Schema.
If the value set here is between minOccurs and maxOccurs, that value will be used;
If the value set here is less than minOccurs, the minOccur value will be used;
If the value set here is greater than maxOccurs, that value will be used.
Option to set the maximum allowed depth of the same element in case of recursivity.
Option to be used in case of xs:choice or substitutionGroup. The possible strategies are:
First - the first branch of xs:choice or the head element of substritutionGroup will be always used;
Random - a random branch of xs:choice or a substitute element or the head element of a substitutionGroup will be used.
Option to generate the other possible choices or substitutions (for xs:choice and substitutionGroup). These alternatives will be generated inside comments groups so you can uncomment them and use later. Use this option with care (for example on a restricted namespace and element) as it may generate large result files.
If an XML Schema is organized on several levels linked by xs:include statements sometimes it is more convenient to work on the schema as a single flat file. To flatten schema <oXygen/> recursively adds included files to the master one. That means <oXygen/> replaces the xs:include elements with the ones coming from the included files.
This action can be accessed from the schema editor's contextual menu -> Refactoring -> Flatten Schema.
In the following example master.sxd includes slave.xsd. This, in turn, includes slave1.xsd which includes both slave2.xsd and slave3.xsd.
Listing of master.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="tns" xmlns:tns="tns" xmlns:b="b" > <!-- included elements from slave.xsd --> <xs:include schemaLocation="slave.xsd"></xs:include> <!-- master.xsd --> <xs:element name="element1"> <xs:complexType> <xs:sequence> <xs:element ref="tns:element2" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Listing of slave.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="tns" xmlns:a="a" xmlns:b="b" xmlns:c="c"> <!-- included elements from slave1.xsd --> <xs:include schemaLocation="slave1.xsd"></xs:include> <!-- slave --> <xs:element name="element2" xmlns:c="x"/> </xs:schema>
Listing of slave1.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="tns" xmlns:tns="tns" blockDefault="restriction"> <!-- included elements from slave2.xsd --> <xs:include schemaLocation="slave2.xsd"></xs:include> <!-- included elements from slave3.xsd --> <xs:include schemaLocation="slave3.xsd"></xs:include> <!-- slave1 --> <xs:element name="element0"/> <xs:element name="element7"/> <xs:element name="element7Substitute" substitutionGroup="tns:element7" block="extension"/> <xs:element name="element6"> <xs:complexType> <xs:sequence> <xs:element ref="tns:element7"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="type1"> <xs:sequence> <xs:element ref="tns:element0"/> </xs:sequence> </xs:complexType> </xs:schema>
Listing of slave2.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="tns" xmlns:tns="tns" elementFormDefault="qualified" attributeFormDefault="qualified"> <!-- slave2 --> <xs:element name="a"></xs:element> <a:element name="element9" xmlns:a="http://www.w3.org/2001/XMLSchema"> <xs:complexType> <xs:sequence> <!-- This element is from the target namespace --> <xs:element name="element3" xmlns:b="http://www.w3.org/2001/XMLSchema"/> <!-- Element from no namespace --> <xs:element name="element4" form="unqualified"/> <a:element ref="tns:a"></a:element> </xs:sequence> <!-- Attribute from the target namespace --> <b:attribute name="attr1" type="xs:string" xmlns:b="http://www.w3.org/2001/XMLSchema"/> <!-- Attribute from the no namespace --> <xs:attribute name="attr2" type="xs:string" form="unqualified"/> </xs:complexType> </a:element> </xs:schema>
Listing of slave3.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="tns" finalDefault="restriction" xmlns:tns="tns"> <!-- slave3 --> <xs:complexType name="ct1"/> <xs:complexType name="ct2" final="extension"> <xs:complexContent> <xs:extension base="tns:ct1"/> </xs:complexContent> </xs:complexType> <xs:simpleType name="st1" final="union"> <xs:restriction base="xs:integer"/> </xs:simpleType> <xs:simpleType name="st2" final="union"> <xs:restriction base="tns:st1"> <xs:enumeration value="1"/> <xs:enumeration value="2"/> </xs:restriction> </xs:simpleType> <xs:element name="e1" type="tns:c1" final="restriction"/> <xs:element name="e2ext" type="tns:c2" substitutionGroup="tns:e1"></xs:element> <xs:complexType name="c1"> <xs:sequence> <xs:element ref="tns:e1"/> </xs:sequence> </xs:complexType> <xs:complexType name="c2"> <xs:complexContent> <xs:extension base="tns:c1"> <xs:sequence> <xs:element ref="tns:e1"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> </xs:schema>
Listing of master.xsd after it has been flattened
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="tns" xmlns:a="a" xmlns:b="b" xmlns:c="c" xmlns:tns="tns" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <!-- included elements from slave.xsd --> <!-- included elements from slave1.xsd --> <!-- included elements from slave2.xsd --> <!-- slave2 --> <xs:element block="restriction" name="a"/> <a:element block="restriction" name="element9" xmlns:a="http://www.w3.org/2001/XMLSchema"> <xs:complexType> <xs:sequence> <!-- This element is from the target namespace --> <xs:element block="restriction" form="qualified" name="element3" xmlns:b="http://www.w3.org/2001/XMLSchema"/> <!-- Element from no namespace --> <xs:element block="restriction" form="unqualified" name="element4"/> <a:element ref="tns:a"/> </xs:sequence> <!-- Attribute from the target namespace --> <b:attribute form="qualified" name="attr1" type="xs:string" xmlns:b="http://www.w3.org/2001/XMLSchema"/> <!-- Attribute from the no namespace --> <xs:attribute form="unqualified" name="attr2" type="xs:string"/> </xs:complexType> </a:element> <!-- included elements from slave3.xsd --> <!-- slave3 --> <xs:complexType block="restriction" final="restriction" name="ct1"/> <xs:complexType block="restriction" final="extension" name="ct2"> <xs:complexContent> <xs:extension base="tns:ct1"/> </xs:complexContent> </xs:complexType> <xs:simpleType final="union" name="st1"> <xs:restriction base="xs:integer"/> </xs:simpleType> <xs:simpleType final="union" name="st2"> <xs:restriction base="tns:st1"> <xs:enumeration value="1"/> <xs:enumeration value="2"/> </xs:restriction> </xs:simpleType> <xs:element block="restriction" final="restriction" name="e1" type="tns:c1"/> <xs:element block="restriction" final="restriction" name="e2ext" substitutionGroup="tns:e1" type="tns:c2"/> <xs:complexType block="restriction" final="restriction" name="c1"> <xs:sequence> <xs:element ref="tns:e1"/> </xs:sequence> </xs:complexType> <xs:complexType block="restriction" final="restriction" name="c2"> <xs:complexContent> <xs:extension base="tns:c1"> <xs:sequence> <xs:element ref="tns:e1"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <!-- slave1 --> <xs:element block="restriction" name="element0"/> <xs:element block="restriction" name="element7"/> <xs:element block="extension" name="element7Substitute" substitutionGroup="tns:element7"/> <xs:element block="restriction" name="element6"> <xs:complexType> <xs:sequence> <xs:element ref="tns:element7"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType block="restriction" name="type1"> <xs:sequence> <xs:element ref="tns:element0"/> </xs:sequence> </xs:complexType> <!-- slave --> <xs:element name="element2" xmlns:c="x"/> <!-- master.xsd --> <xs:element name="element1"> <xs:complexType> <xs:sequence> <xs:element ref="tns:element2"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
The case of XML Schema redefinitions is also handled as the example below shows.
Listing of master.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:redefine schemaLocation="slave1.xsd"> <xs:complexType name="tp"> <xs:complexContent> <xs:extension base="tp"> <xs:choice> <xs:element name="el2" type="xs:NCName"/> <xs:element name="el3" type="xs:string"/> </xs:choice> </xs:extension> </xs:complexContent> </xs:complexType> </xs:redefine> <xs:element name="el" type="tp"/> </xs:schema>
Listing of slave1.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:redefine schemaLocation="slave2.xsd"> <xs:complexType name="tp"> <xs:complexContent> <xs:extension base="tp"> <xs:attribute name="a"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:redefine> </xs:schema>
Listing of slave2.xsd
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexType name="tp"> <xs:sequence> <xs:element name="el" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema>
Listing of master.xsd after it has been flattened>
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexType name="tp"> <xs:complexContent> <xs:extension base="tp_Redefined1"> <xs:choice> <xs:element name="el2" type="xs:NCName"/> <xs:element name="el3" type="xs:string"/> </xs:choice> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="tp_Redefined1"> <xs:complexContent> <xs:extension base="tp_Redefined0"> <xs:attribute name="a"/> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="tp_Redefined0"> <xs:sequence> <xs:element name="el" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:element name="el" type="tp"/> </xs:schema>
The references to the included schema files can be resolved through an XML Catalog.
To generate XML Schema regular expressions use the action
-> It will open a dialog which allows you to build and test regular expressions.The dialog contains the following sections:
Regular expressions editor - allows you edit the regular expression to be tested and used. Content completion is available and presents a list with all the predefined expressions. It is accessible by pressing Ctrl + Space.
Category combo box - here you can choose from several categories of predefined expressions. The selected category influences the displayed expressions in the Available expressions table.
Available expressions table - it consists of two columns. The first one presents the regular expressions, the second displays a short description of the expressions. The set of expressions depend on the category selected in the previous combo box. You can add an expression in the Regular expressions editor by double-clicking on the expression row in the table You will notice that in the case of Character categories and Block names the expressions are also listed in complementary format. For example: \p{Lu} - Uppercase letters; \P{Lu} - Complement of: Uppercase letters.
Evaluate expression on radio buttons - there are available two options: Evaluate expression on each line and Evaluate expression on all text . If the first option is selected the edited expression will be applied on each line from the Test area. If the second option is selected the expression will be applied on the whole text.
Test area - it is a text editor which allows you to enter a text sample on which the regular expression will be applied. The matches of the expression will be highlighted.
After editing and testing your regular expression you can insert it in the current editor. The Insert button will become active when an editor is opened in the background and there is an expression in the Regular expressions editor.
To generate HTML documentation for a XML Schema document similar with the Javadoc documentation for Java classes use the dialog Schema documentation. It is opened with the action -> -> . The dialog enables the user to configure a large set of parameters of the process of generating the HTML documentation.
The HTML documentation contains images corresponding to the schema definitions as the ones displayed by the schema diagram view. These images are divided in clickable areas which are linked to the definitions of the clicked names of types or elements. The documentation of a definition includes a Used By section with links to the other definitions which refer to it.
The text field of the Input panel must contain the full path to the XML Schema (XSD) file, if the schema is composed of only one file, or the full path to the main XSD file of the XML Schema document, that is the file that includes or imports other modules of the document.
<oXygen/> is able to include images of the XML Schema components in the final HTML result. The supported image formats are PNG and JPG. The image of an XML Schema component contains the graphical representation of that component as it is rendered in the Schema Diagram panel of the <oXygen/>'s XSD editor panel. The parameters related to images are:
Include in the HTML result the representation of each schema component in the <oXygen/>'s Full Model View of the schema.
Include in the HTML result the representation of each schema component in the <oXygen/>'s Logical Model View of the schema.
When checked the comments are not included in the generated schema documentation.
When checked the annotations are not included in the generated schema documentation.
The Options panel contain parameters for the level of details included in the documentation:
The title displayed at the beginning of the HTML document and in the title bar of the web browser.
If this parameter is set to "true", the schema components are presented sorted by type and name. Otherwise, they are presented in the order that they appear in the schema. By default, this parameter is set to "true."
The generated XHTML document uses JavaScript to hide some details like the underlying schema component XML representation, which can be made to appear with a button press. Since some people have ideological objections to JavaScript, this feature can be turned off. If this parameter is set to "true", JavaScript will be used in the generated documentation. Otherwise, it won't. By default, this parameter is set to "true."
If this parameter is set to "true", xs3p will search for components in "included" schemas when creating links and generating the XML Instance Representation table. When this parameter is set to "true", the "linksFile" parameter must also be set, which is described below. Otherwise, an error will be raised. This search is recursive, so schemas "included" in the current schema's "included" schemas will also be searched.
If this parameter is set to "true", xs3p will search for components in "imported" schemas when creating links and generating the XML Instance Representation table. The above discussion for the "searchIncludedSchemas" parameter also applies to this parameter. Also, when this parameter is set to "true", the "linksFile" parameter must also be set.
The type hierarchy of a global type definition is displayed in its section. If this parameter is set to "true", all super-types of the current type are shown in the type hierarchy. Otherwise, only the immediate parent type is displayed. By default, this parameter is set to "true."
This parameter has a similar concept as printAllSuperTypes. If it is set to "true", all sub-types of the current type are shown in the type hierarchy. Otherwise, only the direct sub-types are displayed. By default, this parameter is set to "true."
If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."
The Output panel contains parameters for the output folder and output file:
The path of the folder containing the HTML result and the image files.
The folder where the images are going to be saved relative to the output file. If there is no folder specified, the images will be saved in the same directory as the output file.
If it is true the HTML result is organized as a main file containing only a table of contents with links to other HTML documents containing descriptions of the schema components. If it is false all the documentation will be stored in one HTML file.
If enabled then the anchors and links will be generated using the hashcode of the component identifier instead of using the identifier itself. This is useful when the schema component names contain characters that are not directly supported by the browsers or by the file system.
It will be generated HTML documentation also for the XML Schemas included or imported by the schema specified in the Input panel. The documentation can be navigated from a schema to the included/imported ones and back to the first schema following HTML hyperlinks.
It will not be generated HTML documentation for the XML Schemas included or imported by the schema specified in the Input panel.
The name of the HTML file containing the documentation of the XML Schema
the file which maps from file locations of "included" and "imported" schemas to the file locations of their xs3p-generated documentation. This file must be provided if either "searchIncludedSchemas" or "searchImportedSchemas" is set to true. If relative addresses are used to specify the location of external xs3p-generated documentation, they must be relative to documentation file currently generated.
The external documentation files does not need to exist at the time of generating the documentation for the current schema. The mapping is specified in XML. The dtd and schema for this mapping syntax are "links.dtd" and "links.xsd" respectively.
The "xmlns" namespace attribute with the correct namespace must be provided in the mapping file for the xs3p stylesheet to work.
The path to a CSS file which will be referred from the result HTML. This is useful for specifying a custom CSS stylesheet to be used in the generated HTML documentation instead of the default one.
If it is true the HTML result will be opened with the default Internet browser set in Preferences or with the system application for HTML files.
The same HTML documentation can be generated for an XML Schema from the
command line by running the script schemaDocumentation.bat
(on Windows) / schemaDocumentation.sh
(on Mac OS X / Unix /
Linux) located in the <oXygen/> installation folder. The script can be integrated in
an external batch process launched from the command line.
The list of actions specific for the XML Schema editor of <oXygen/> is:
-> : move the cursor to the definition of the current element in this XSD schema.
All the following actions can be applied on xs:element, xs:attribute, xs:attributeGroup, xs:complexType, xs:simpleType, xs:group, xs:key, xs:unique or xs:notation parameters only.
Ctrl+Shift+R): Searches in the project all references of the item found at current cursor position.
+ -> (+ -> : Searches in the current file all references of the item found at the current cursor position.
+ -> : Searches all references of the item at the cursor position in the current edited file and all its included and imported files.
+ -> : Opens a dialog that allows the user to specify the list of files used to start searching from. Pressing OK begins searching all references of the item at the cursor position in the selected files and their included and imported files.
Ctrl+Shift+D): Searches in the project all declarations of the item found at current cursor position.
+ -> (+ -> : Searches in the current file all declarations of the item at the current cursor position.
+ -> : Searches all declarations of the item at the cursor position in the current edited file and all its included and imported files.
+ -> : Opens the Start locations dialog that allows the user to specify the list of files used to start searching from. Pressing OK begins searching all declarations of the item at the cursor position in the selected files and all their included and imported files.
Ctrl+Shift+U): Searches all occurrences of the item at the caret position in the currently edited file.
-> (