Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved

Chapter 2 XML Tools Palette : Schema

Schema
Resource
The Schema resource of the XML Tools palette enables the creation of an XML Schema file, as defined by the W3C Recommendation (May 2001).
An XML Schema describes the vocabulary and structures that may appear within an XML instance document conforming to that schema. Schemas use their own formal grammars to express document structures and vocabulary. If a set of documents uses the same schema, the documents may have markedly different contents, but can share common processing. Applications check documents against the schema, and process them only if the document passes inspection (more commonly called validation). By providing a common formal vocabulary for describing the terms on which information will be exchanged, schemas act as an easily enforced contract between senders and receivers (and creators and consumers) of information.
When a Schema resource is selected in your project, a set of new panels, menu options, and toolbar buttons is provided, helping you build and edit your schema from a variety of different perspectives. Each panel provides access to a different set of tools. The multiple panels may show information simultaneously, but all of them combine to present a consistent view of your schema. This chapter describes each of the panels in detail.
Configuration Tab
The Configuration tab has the following fields.
Name of the file when persisted. The *.xsd suffix will be automatically added.
Schema Properties Panel
Double-click a Schema resource to edit it. When editing a Schema resource, the configuration panel provides tabs for setting or viewing schema-level properties. You are not required to edit the fields in the configuration panel, although it is recommended that you provide your schema resource with a meaningful name and target namespace.
Target Namespace Tab
The Target Namespace tab has the following fields.
Name of the file when persisted. The *.xsd suffix will be automatically added.
Schema Attributes Tab
The Schema Attributes tab is used to specify schema-level properties (specifically, attributes of the schema element that control how the schema’s components can be used within the schema or within XML instance documents.) Because these attributes serve very specific purposes, the fields within the Attributes tab typically do not need to be edited.
By default, the elementFormDefault attribute of the schema element takes the value qualified. Thus, you must declare top-level elements to be associated with a namespace in the instance document.
By default, the attributeFormDefault attribute of the schema element takes the value unqualified. Thus, unless you specify otherwise, only globally declared attributes can be associated with a namespace in the instance document.
Use the blockDefault attribute of the schema element to control whether types can be replaced by their derived types in instance documents.
The blockDefault attribute takes one of the values in the drop-down menu. The value you select will prevent type replacement in the instance if derivation is of that value. Select #all to prevent any type replacement by derived types
The finalDefault attribute of the schema element allows you to specify that new types may not be derived from any simple or complex type. Click the arrow to display the drop-down menu choices.
The id attribute on the schema element can be used to apply an identifier value to your schema. The value you give for id must be of type ID, which requires an NCName.
The version attribute on the schema element can be used to apply a version value to your schema.
The settings in the Schema Attributes tab are universal, controlling all of the schema’s components. To specify similar properties for an individual component, use the Properties tab of the properties panel. See Properties Tab.
Schema Documentation Tab
This tab displays an edit area where you can add schema level documentation for your schema.
Schema Statistics Tab
The Schema Statistics tab is not editable. The tab displays the number of times a schema component type is used. The tab has the following fields.
Toolbar
For a description of the buttons that appear on the toolbar when editing Schema resources, see Toolbar Buttons.
Schema Menu
A Schema menu becomes available when editing a Schema resource. The Schema menu contains two submenus, View and Edit.
The View menu provides options to control the panels used for editing, organizing, and viewing your schemas. The Edit menu includes options for searching your schema.
The Schema menu options are described in detail in Table 7.
Elements/Types Panel
The elements/types panel enables you to view, create, and edit element and attribute declarations and complex type definitions. The elements/types panel is typically the place you'll start defining your schemas.
The panel is divided into two parts: a graphical view of the content model (the content model diagram) and an editable list of element declarations and complex type definitions and their content models (the element/type list panel). The next diagram illustrates the element/types panel.
Figure 18 Element/Types Panel
Elements/Types List
The elements/types list, located at the bottom of the elements/types panel, is where much of the creation and editing of element declarations and complex type definitions takes place. The next diagram illustrates the element/type list.
Figure 19 Element/Type List
Each element and/or complex type is listed in a row of the table. Information that defines each item appears in columns across the table and includes the following (from left to right).
Warning: Any changes made to unlocked declarations of an included schema will be reflected in the included schema as well.
This column is labelled as either Element or Complex Type depending on the type of declaration indicated in the Declaration Type column for the selected row. A new element or complex type can be created by clicking on a blank row under the Element/Complex Type column, and then entering a name. To edit an element or complex type name, click on an existing name in the Element/Complex Type name column.
Note: Element and complex type names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.
Any — The content model contains any combination of elements and/or character data (text).
Empty — When an element has no content at all, its content model is empty. Essentially, a model is defined that allows only elements in its content but does not actually declare any elements, so the type's content model is empty.
Mixed — In a mixed content model, an element contains other elements interleaved with character content. Character data can appear alongside child elements and is not confined to the deepest child elements.
Elements — The content model contains elements only.
Typed — The content is either a simple type (such as xs:string, xs:integer, or xs:float) or a named complex type.
The Content Model/Data Type column displays the content model of the elements and provides a set of tools for creating and editing content models and data types. (The name of this column is either Content Model or Data Type, depending on the content type set in the Content column.) Users who are comfortable with occurrence and sequence indicator syntax can enter element content models directly by typing them in the Content Model column. For users not yet comfortable with occurrence and sequence indicators, a series of buttons are provided to help the user create and edit content models. See Building Content Models: Occurrence and Sequence Indicators for more information.
The Insert button provides a drop-down menu that differs depending on whether the content model may include elements or data. The Insert menu provides a quick way to add content that's been previously defined, such as a built-in data type, a user-defined simple type, an element, or a complex type. The selected material is inserted at the current location of the cursor. See Example: Building a Content Model for more information.
For a description of XML Schema’s built-in data types, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes
The Attributes column allows the user to specify which attributes may be used for a particular elements. If an attribute name is entered which does not yet exist, it is automatically created with a default data type of xs:string and with no constraints (The declaration can be further refined in the attributes panel at any time. See Attributes Panel for more information.)
When the user tabs to an Attributes field, an Insert Attribute button appears. Click the button to access a menu listing previously defined attributes. Selecting an attribute name adds it to the element or complex type being defined
Building Content Models: Occurrence and Sequence Indicators
For element content models, buttons are also provided for applying sequence and occurrence indicators. Table 14 describes the Occurrence indicators. Table 15 describes the Sequence indicators.
{} and specify the min. and max. values for the range.
 
Occurrence and Sequence indicators combine to make it possible to describe complex structures. For example, a memo might allow multiple entries in its To: and From: fields, multiple (or zero) entries in its cc: field, a single entry for the subject, required content for the body, and an optional set of initials at the bottom for the typist. A MEMO element might therefore have the following content model:
 
(To+, From+, CC*, Subject, Body, Typist?)
This declaration requires the MEMO element to contain, in sequence, one or more To elements, one or more From elements, zero or more CC elements, a single Subject element, a single Body element, and zero or one Typist elements.
In other cases, a document needs to provide choices. A chapter might require an introduction, but then permit any combination of sections or sidebars. Sequence indicators, in combination with occurrence indicators, can make this possible. The content model for a chapter element might therefore look like:
 
(Intro, (Section | Sidebar)*)
The Intro element could appear once (and only once) at the start of the chapter, and then Section or Sidebar elements could follow in any order. (This model is read as “an Intro element followed by zero or more Section or Sidebar elements”.)
Example: Building a Content Model
This section steps you through building a content model for an element or complex type using the buttons provided in the Content Model column. Figure 20 shows a completed content model.
Figure 20 Completed Content Model
You will build the content model for an element based on the structure of a book. The content model would likely include several elements, including a Title, an Author, multiple Chapters, maybe an Appendix (or several), perhaps a Glossary, and possibly an Index. Assuming these elements are already declared (as shown in the next diagram), the steps to build the content model for Book appear below:
Figure 21 Content Model for Book
1.
In the row for Book, click in the blank cell under the Content Model column. This is where the entry for the content model will be created. A series of buttons will appear.
2.
Figure 22 Pull-down Menu
3.
Select the first element to be part of the content model (in this case, you’ll start with Title). Repeat this step, selecting each element that is part of the content model. It is best to select the sub-elements in sequence if possible, because as each sub-element is selected, a comma is inserted between items by default to indicate that they are in sequence. The sub-element will always be inserted where the cursor is placed in the content model.
4.
Which items may be repeatable? Within a book, the chapters usually occur more than once, so this sub-element needs to be indicated as a repeatable item. Highlight Chapter in the Content Model, and click on the Repeatable button. This adds a '+' indicator after Chapter, to indicate it is repeatable. Likewise, there may be more than one appendix, so highlight Appendix and click Repeatable to add a '+' indicator after Appendix.
5.
Which items are optional? Within a book, a glossary or index may not always occur, so these sub-elements need to be made optional. Highlight Glossary, and click the Optional button. Likewise, highlight Index, and click the Optional button. This will place a '?' after each of these sub-elements, to indicate they are optional.
6.
Appendix is also an optional item (not all books have appendices). Highlight Appendix and click the Optional button. Because Appendix is now both optional and repeatable, it is indicated with an '*' after it. Press the <Enter> key or click anywhere else in the element list to complete the content model definition.
The buttons not used in this example include:
Building Content Models: Content Model Editor
If the space provided by the Content Model column is too small to see all of an element content model, select Expand from the Schema > View menu or press the Ctrl Shift E keys to bring up the Content Model Editor dialog box. The Content Model Editor provides more room for editing, making it easier to work with larger content models, and gives easy access to the elements and reusables. To add an element or reusable model group to a content model, click on its name. Occurrence and Sequence indicator buttons are also available in the editor. The Apply button adds the edited content model to the list, but leaves the editor open. The Cancel button closes the editor without making any changes to the content model in the list, while the Save button closes the editor and makes the changes. Figure 6 illustrates the Content Model Editor.
Figure 23 Content Model Editor
Content Model Diagram
The content model diagram of the elements panel graphically displays the content models in a Schema resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.
See Content Model Diagram for more information about the content model diagram.
Attributes Panel
When you select the Schema > View > Attributes menu, or when you click the Attributes button on the toolbar, the attributes panel becomes the primary panel for editing. The attributes panel is used to view, create, and edit attribute type declarations. While you can also create an element’s attribute in the element/type list, you must use the Attributes panel to specify an attribute’s data type. Constraints, facets and enumeration of attributes are set from the properties panel when the attribute is selected.
Figure 24 illustrates the attributes panel.
Figure 24 Attributes Panel
Each attribute is listed in a row of the panel. Information associated with each attribute appears in columns across the panel and includes the following (from left to right).
Note: Attribute names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.
Note: For a description of XML Schema’s built-in data types, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes
Example: Creating or Editing an Attribute
Attributes are created by declaring an attribute type in the attributes panel or by entering attribute names for an element in the element/type list of the elements/types panel.
Creation of an attribute type within the attributes panel consists of several steps. As an example, let's say we have an element Picture, with the attribute GraphicsType. GraphicsType is an attribute that tells us if a picture is a JPG, TIF, or GIF file.
To declare an attribute, follow these steps:
1.
Names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.
An attribute type declaration, by default, sets the data type for an attribute to xs:string. In this example, GraphicsType will be enumerated (that is, it will only ever have the value of JPG, TIF, or GIF). Because the values for this enumeration are best defined as strings, the xs:string data type is appropriate. An attribute type declaration, by default, sets the data type for an attribute to xs:string. In this example, GraphicsType will be enumerated (that is, it will only ever have the value of JPG, TIF, or GIF). Because the values for this enumeration are best defined as strings, the xs:string data type is appropriate. For example:
2.
Right-click the GraphicsType attribute and select Goto Attribute Picture/GraphicsType.
3.
Because GraphicsType can be only be a JPG, TIF, or GIF, these values must be entered in the attribute type declaration. Click on the Properties button on the toolbar and then click on the Enumeration tab. In the text box at the top, enter JPG, and then click the Add button. Follow the same procedure to add TIF and GIF.
Figure 25 Enumeration Tab for Attribute
4.
Figure 26 Properties Tab for Attribute
This completes the declaration for GraphicsType.
Overview Panel
When selected from the Schema > View menu or upon clicking the Overview button on the toolbar, the overview panel loads to the left of the elements/types panel. The overview panel allows you to control the creation of schemas that use imports and includes, as well as explore the overall organization of your schema. The overview panel's tools let you build schemas from declarations in multiple files, creating large composite schemas from sets of smaller ones, enhancing reusability and simplifying management.
Figure 27 illustrates the overview panel, with a right button menu activated.
Figure 27 Overview Panel
Overview Tree
The overview panel provides a tree-like overview of the schema structure. Each schema component type is represented by an icon, described in the table below.
A right menu button is provided for each component in the overview tree. From the menu, you can cut, copy, paste or delete a declaration or module (removing it or changing its location in the schema). There is also an option to “Go to” or “Edit” the component, which will take you to an area to edit the selected item.
If the declaration is located in an external schema that has been added to the current schema, a menu option to unlock the module is provided. Before any edits can be made to included declarations (identified by a document icon with a red slash), the included schema must be unlocked. When a module is unlocked, the red line disappears from the document icon. When you're done editing the included declarations, you can right-click on the module and lock it again .
Import Button
The Import button of the overview panel allows you to import the namespace of another schema in your project, making the components defined in the other schema that can be referenced in your schema. To remove a namespace, right click on the namespace (labelled with the namespace’s prefix) and select Delete from the pop-up menu that appears.
Example: Referencing an element from another namespace
When building a schema, it is often desirable to reuse components already defined in another schema. If the other schema belongs to a different target namespace, its namespace can be added to (technically, imported into) the schema you are building.
To import a namespace and then reference the components from that namespace, follow these steps:
1.
Click the Import button of the overview panel.
2.
Figure 28 Select an XSD Schema
The imported namespace will appear as an icon in the overview panel’s tree and as an entry in the Namespaces tab of the advanced panel.
3.
Figure 29 Referencing an Element From Another Namespace
Include Button
The Include option of the overview panel allows you to include the declarations from another of your project’s schemas into the schema you are currently building. To remove an included schema, right click on the included schema icon and select Delete from the pop-up menu that appears.
Example: Including declarations from another schema
When building a schema, it is often desirable to reuse components already declared in another schema. If the other schema belongs to the same target namespace (or no namespace) as the schema you are building, the declarations in the other schema can be added to (technically, included in) the schema you are building.
This example illustrates the steps required to include another schema’s declarations into your schema.
1.
Click the Include button of the overview panel.
2.
3.
Figure 30 Declaration Panel
Properties Panel
When selected from the Schema > View menu or upon clicking the Properties button on the toolbar, the properties panel loads to the left of the elements/types panel. The properties panel includes three tabs:
Properties Tab
The Properties tab is accessed by clicking the Properties button on the toolbar. The Properties tab is used for setting and viewing component level properties. The properties control how the component can be used within the Schema or within an XML instance document.
The Properties tab becomes active when an element, complex type, attribute, or Simple type declaration (row) is selected in its respective panel. The fields available within the Properties tab, summarized Table 18 below, vary depending on the selected declaration type.
 
Use the block property to control whether types can be replaced by their derived types in instance documents. The block property takes one of the following values:
restriction - prevents type replacement in the instance if derivation is by restriction
extension - prevents type replacement in the instance if derivations is by extension
substitution - prevents replacement by substitution groups in the instance document
restriction extension - prevents type replacement in the instance document if derivation is byrestriction or extension
restriction substitution - prevents replacement in instance documents by substitution groups and prevents type replacement if derivation is by restriction
extension substitution - prevents replacement in instance documents by substitution groups and prevents type replacement if derivation is by extension
#all - to prevent any type replacement in the instance document by derived types or by substitution groups
The final property allows you to prevent new types from being derived from the selected simple or complex type. The final property takes one of the following values:
restriction - to prevent derivation by restriction in the schema document
extension - to prevent derivation by extension in the schema document
#all - to prevent any derivations at all in the schema document
Use this field to specify whether the selected element or attribute should be either qualified or unqualified in the instance document. If qualified, the element or attribute must be associated with the target namespace in the instance document. If unqualified, a locally declared element or attribute must not be associated with the target namespace in the instance document.
(By default, elements and attributes are defined as unqualified. The default setting can be changed in the Attributes tab of the configuration panel).
Facets Tab
The Facets tab is used to further constrain the acceptable values for your schema’s components by applying facets to your simple types (data types). Accordingly, the Facets tab becomes applicable when a declaration uses a simple type, such as a text-only element declarations, attribute declarations, and user-derived data type definitions.
When constraints are applicable, the Facets tab can be accessed by:
The constraining facets available within the Facets tab, summarized in the table below, vary depending on the type of data type being used.
 
 
Enumeration Tab
The Enumeration tab allows you to enumerate allowable values of a specified simple type (data type). Accordingly, the Enumeration tab becomes applicable when a declaration uses a simple type, such as a text-only element declarations, attribute declarations, and user-derived data type definitions.
When an enumeration is applicable, the tab can be accessed by clicking the Properties button on the Toolbar, and then clicking the Enumeration tab in the properties panel.
In the text box at the top of the Enumeration tab, enter a value and then click Add. Repeat this procedure for each of the enumeration's values. The values will appear in the list box beneath the text box used for input. You can use the Up and Down buttons to reorder the values in the list. You can also select a value in the list and either Delete it or Replace it with a value entered in the text box at the top. As you edit the enumeration in the Enumeration tab, the current values are reflected in the appropriate column of the active panel.
Advanced Panel
When you choose the Schema > View > Advanced menu, the advanced panel becomes the primary panel for editing. The advanced panel allows you to define or edit parts of XML schemas that move beyond the description of document structures. The advanced panel consists of three tabs.
Namespaces Tab
The Namespaces tab provides an inventory of the external namespaces being used by your schema. The XML Schema namespace (unless designated as the default namespace) and any namespaces added by way of the Import button of the overview panel will appear in the Namespaces tab.
The Namespaces tab permits only limited editing of the namespace declaration:
The Namespaces tab cannot be used to add a new namespace or change the URI or location for an existing namespace. These operations must be performed within the overview panel.
Each namespace is listed in a row of the panel. Information associated with each namespace appears in columns across the panel and includes the following (from left to right):
Notations Tab
Notations allow you to describe a new data type or file type. The description involves a name for the type and a link to more information on the type or to programs that can process the type. For example, the notations declared in Figure 31 provide information on ISO8601 dates and times, and Java integers. Either could be used for a data type and will appear as an option in the type menus that appear in the elements panel and attributes panel.
Figure 31 Notations Tab of the Advanced Pane
Each notation is listed in a row of the panel. Information associated with each notation appears in columns across the panel and includes the following (from left to right).
Simple Types Panel
When selected from the Schema > View menu or upon clicking the Simple Types button on the toolbar, the simple types panel becomes the primary panel for editing. The simple types panel enables XML Schema authors to create their own simple types (data types), which can then be applied to element declarations and attributes in the schema. These “derived” simple types are created by constraining the set of distinct values available for existing simple types, known as base types. For example, Figure 32 illustrates a user-defined data type called rating that is derived from the base type integer by requiring a minimum value of 1 and a maximum value of 10.
Figure 32 Creating a New Simple Type
Each simple type is listed in a row of the panel. Information associated with each simple type appears in columns across the panel and includes the following (from left to right).
Note: Data type names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.
Note: For a description of XML Schema’s built-in data types, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes
User-defined types, such as rating, can also be used as base types. To further constrain rating, use the Insert user-defined type button within the Base Type column.
Once a new simple type has been defined, it becomes a choice in the Insert menus of the elements/types panel and attributes panel, when appropriate.
Example: Creating a User-Derived Simple Type
In this example a new simple type, called rating is derived. The new type can be any integer from 1 to 10.
1.
Figure 33 Enter Name
2.
Tab to the Base Type field and use the Native Type button to select the type xs:positiveInteger.
3.
4.
In the properties panel, use the minInclusive and maxIncusive facets to restrict the acceptable values of rating to positive integers from 1 to 10.
The rating type is now declared and will become a choice on the User Defined Type menu available in the elements/types panel, the attributes panel, and the simple types panel.
Figure 34 User Defined Type
Schema Props Panel
When selected by way of the Schema > View menu, the schema props panel is displayed. For a description of these properties, see Schema Properties Panel.
Validations Panel
When selected by way of the Schema > View > Validation menu, the validation panel appears between the active editing panel and the configuration panel. The validation panel displays errors or warnings found when a new schema is loaded, as well as errors or warnings detected throughout the editing process.
The validations panel indicates the total number of errors or warnings and provides a list of errors and details about the errors in this panel. Clicking on the error message will take you to the source of the error.
Component Doc Panel
The raw declarations in your schemas are very useful for parsers processing your document, but are rarely sufficient for other humans who need to read and make sense of your schema. Adding notes helps those who use and maintain your schema to understand your schema designs, and can be a critical tool for keeping groups of developers working on the same or related schemas in sync.
The Schema Documentation tab of the Schema Props panel provides an area where you can add schema level documentation to your schema. The Documentation tab of the Component Doc panel allows you to add component level documentation and document individual declarations and preview their source. When selected by way of the Schema > View menu, the Component Doc panel appears between the active editing panel and the configuration panel.
When the Component Doc panel reflects the selected declaration, the following tabs are available:
XML Schema uses two elements for annotations: documentation and appinfo. The Documentation tab displays and adds documention annotations only, which are intended to facilitate human understanding of the schema. There is no facility for adding appinfo annotations through the Component Doc panel.
Source Panel
When selected by way of the Schema > View > Source menu or upon clicking the Source button on the toolbar, the source panel becomes the primary panel for editing. The source panel allows you to edit the source code of your Schema directly. If you are comfortable with Schema syntax, editing your declarations directly may occasionally be useful or even convenient. Even if you don't want to edit your Schemas directly, the source panel provides another way to examine your declarations.
To make the other panels reflect the changes you've made, click Reparse at the top of the panel. Any errors found upon reparse will be listed in the Validation panel.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved