## Schema Definition Page

### About This Page

This form page allows you to edit the structure and properties of schema objects that constitute the edited schema's grammar.

The structure of schema objects are edited in the Extension Point Elements section. This section occupies the upper left-hand portion of the editor area.

The properties of schema objects are edited in the <schema-object> Details sections. These sections are activated in the upper right-hand portion of the editor area depending on the type of schema element selected in the Extension Point Elements section.

### Page Sections

This page is comprised of the following sections:

- Extension Point Elements Section
- Description Section
- Element Details Section
- Compositor Details Section
- Element Reference Details Section
- Attribute Details Section

### Extension Point Elements Section

This section allows you to do the following:

- Visualize and edit the structure of schema objects that constitute the edited schema's grammar.
- Activate the corresponding <schema-object> Details section used to edit the properties of a selected schema object.

This section is directly accessible through the Schema Definition form page.

### Extension Point Elements Section Fields

Use the extension point element viewer field to do the following:

- Visualize and edit the structure of the elements, attributes and compositors that constitute the edited schema's grammar.
- Activate the corresponding <schema-object> Details section used to edit the properties of a selected element, attribute or compositor.

This viewer contains the following nodes:

Elements:

- - Select the Element node, to activate the Element Details section.
- - Select the Element Reference node, to activate the Element Reference Details section.

Compositors:

- - Select the Sequence Compositor node, to activate the Compositor Details section.
- - Select the Choice Compositor node, to activate the Compositor Details section.

Attributes:

- - Select the Required Attribute node, to activate the Attribute Details section.
- - Select the Optional Attribute node, to activate the Attribute Details section.
- - Select the Class Attribute node, to activate the Attribute Details section.
- - Select the Resource Attribute node, to activate the Attribute Details section.

Example: The extension element specifies that a sequence of one or more shortcut elements are allowed as its legal children. An element reference is used to represent the shortcut element. A Sequence compositor is used to represent a sequence of elements.

Example: The shortcut element specifies that either a description or category element is allowed as its legal child. Element references are used to represent the description and category elements. A Choice compositor is used to represent a choice of elements.

### Extension Point Elements Section Actions

Click the Add Element button to add a new global element declaration to the extension point schema grammar. This action is available when any node is selected. Note: Element declaration order is not important

Click the Add Attribute button to add a new local attribute declaration to a selected element in the extension point schema grammar. This action is available for all selected element nodes except for the extension element node. The extension element node always has the same attributes: id, name, point. Note: Attribute declaration order is not important.

To delete a schema object from the extension point schema grammar, right-click on a selected node and select Delete. This action is available for all selected nodes except for the extension element node. For non-shared schemas, the extension element node is the special root element used to define the entry point to the edited schema's grammar. Any extension defined in the Plug-in Manifest Editor must use an extension parent element to specify its XML related mark-up.

To specify that an element's children is composed of a sequence or choice of other elements in the extension point schema grammar, do the following:

1. Select and right-click the element node you wish to designate as the parent element.
2. Select New > Compositor > Sequence to define a sequence of elements. Select New > Compositor > Choice to define a choice of elements.
3. Select and right-click the new compositor node.
4. Select the element from the New > Reference sub-menu that you wish to designate as a child of the parent element. The Reference sub-menu is populated with all the elements declared globally in the extension point schema grammar.
5. Repeat steps (3) and (4) to specify additional child elements. If a Sequence compositor was specified, this amounts to specifying additional elements in the sequence. If a Choice compositor was specified, this amounts to specifying additional element choices.

Note: To specify that an element is the child of another element, an intermediate Sequence or Choice compositor must always be used by the parent element. The compositor nodes are connector nodes; whereas, the element reference nodes are leaf nodes. Therefore, compositor nodes should always specify at least one child element reference node.

Note: Sequence and Choice compositors may be nested any number of times to create more complex grammars.

Note: A grammar must not contain self-referent cycles. The most basic form of a prohibited cycle occurs when Element A requires Element B as a child and Element B requires Element A as a child.

To specify that an element has no children and allows text to be specified within its start and end XML tags (character content), simply leave the element's structure as is by not adding attributes, compositors and element references to it (element content). Note: An element cannot specify mixed content (both character content and element content).

### Description Section

This section allows you to provide a brief description for any element, attribute or compositor within the edited schema's grammar.

This section is directly accessible through the Schema Definition form page.

### Description Section Fields

Edit the description text field to provide a brief description for the current element, attribute or compositor node selected in the Extension Point Elements section. Valid HTML mark-up may be used within this field as needed.

Note: Updating an element reference description also updates the description of the global element declaration it refers to and vice versa.

### Element Details Section

This section allows you to edit the properties of an element. There are two kinds of elements: extension element, non-extension element. An extension element is the special root element declaration used to define the entry point to the edited schema's grammar. A non-extension element is a global element declaration used as a basic structural building block within the edited schema's grammar.

This section is activated by selecting either a extension element node or non-extension element node in the Extension Point Elements section.

The Element Details section for an extension element.

The Element Details section for a non-extension element.

### Element Details Section Fields

Edit the Name field to specify the element name.

Click either the true button or false button within the Internal field to indicate whether the element is internal or not. The Plug-in Manifest Editor will flag any extension XML mark-up that is internal with a warning (by default). This field is analogous to x-internal attribute on exported packages.

Click either the true button or false button within the Deprecated field to indicate whether the element is deprecated or not. The Plug-in Manifest Editor will flag any extension XML mark-up that is deprecated with a warning (by default). This field is analogous to Java's Javadoc @deprecated tag.

If an extension element is marked as deprecated, edit the Replacement field to specify the non-deprecated extension point the user should use in its place to achieve the same functionality.

Select one of the element's defined attributes from the Label Property field to specify the attribute value to use as the element's label in the Plug-in Manifest Editor. For instance, if a value is selected, the element's node label in the All Extensions section of the Extensions page in the Plug-in Manifest Editor will be as follows: selected-attribute-value (element-name). Otherwise, if no value is selected, the element's node label will be as follows: (element-name).

Select one of the element's defined resource type attributes from the Icon field to specify the icon resource to use to represent the element's node in the Plug-in Manifest Editor. In order for the element's node icon to show up correctly in the All Extensions section of the Extensions page in the Plug-in Manifest Editor, the following conditions must be met:

- The element must define a resource type attribute.
- That attribute must be selected as the value of this field.
- The contributed XML mark-up supplying the attribute value must point to a valid icon resource file.

Click either the true button or false button within the Translatable field to indicate whether the element's character content is translatable or not. This field is only applicable for elements that have no specified children (element content) or attributes and allow text to be specified within its start and end XML tags (character content). If an element's character content is marked as translatable, then PDE tools can be used on contributed extension XML mark-up to externalize the content into a properties file for multi-language support.

Use the read-only DTD approximation field to view an approximate one-to-one mapping of the element schema grammar to the equivalent element DTD grammar. A DTD (Document Type Definition) is an easier to read, less-powerful alternative to XML Schema for specifying an XML document's formal grammar. The following notation is used to specify the DTD approximation:

- element-name - Represents an element in the defined grammar.
- EMPTY - Indicates that no element content or character content is allowed (only attribute declarations).
- #PCDATA - Indicates that only character content is allowed (Parsed Character Data).
- () - Used to group an element's defined sequence and choice compositors.
- | - Used to delimit element choices. Represents a logical or disjunction.
- , - Used to delimit element sequences. Represents a logical and conjunction.
- + - A qualifier used to indicate one or more instances are allowed.
- * - A qualifier used to indicate zero or more instances are allowed.

### Compositor Details Section

This section allows you to edit the properties of a compositor. There are two types of compositors: sequence compositor, choice compositor. A sequence compositor allows you specify that an element's children is composed of a sequence of other elements in the edited schema's grammar. A choice compositor allows you specify a that an element's children is composed of a choice of other elements in the edited schema's grammar.

This section is activated by selecting either a Sequence or Choice node in the Extension Point Elements section.

### Compositor Details Section Fields

Edit the Min Occurrences field to specify the minimum number of occurrences this compositor of other elements and / or compositors is allowed to appear in the contributed extension XML mark-up. This field's value is used by PDE to validate multiplicity constraints within the Plug-in Manifest Editor. If Element A requires exactly one Element B or Element C as its child and it uses a Choice compositor specifying 2 minimum occurrences, then any 2 instances of Element B in combination with Element C must be defined in the contributed extension XML mark-up in order to be valid.

Edit the Max Occurrences field to specify the maximum number of occurrences this compositor of other elements and / or compositors is allowed to appear in the contributed extension XML mark-up. This field's value is used by PDE to validate multiplicity constraints within the Plug-in Manifest Editor. If Element A requires exactly one Element B or Element C as its child and it uses a Choice compositor specifying 2 maximum occurrences, then no more than 2 instances of Element B in combination with Element C can be defined in the contributed extension XML mark-up to remain valid.

Check the Unbounded field to specify that there is no constraint on the maximum number of allowed occurrences this compositor may appear within the contributed extension XML mark-up.

Select a value from the Type field to specify whether this compositor is a sequence or choice.

Use the read-only DTD approximation field to view an approximate one-to-one mapping of the compositor schema grammar to the equivalent compositor DTD grammar. The notation used to specify the DTD approximation is described under the Element Details Section Fields heading in this document.

### Element Reference Details Section

This section allows you to edit the properties of an element reference. An element reference is a reference to a global element declaration within the edited schema's grammar. Element references are used by compositors as atomic building blocks to define the grammar for global element declarations.

This section is activated by selecting an element reference node in the Extension Point Elements section.

### Element Reference Details Section Fields

Edit the Min Occurrences field to specify the minimum number of occurrences this element is allowed to appear in the contributed extension XML mark-up. This field's value is used by PDE to validate multiplicity constraints within the Plug-in Manifest Editor. If Element A specifies 2 minimum occurrences, then 2 instances of Element A must be defined in the contributed extension XML mark-up in order to be valid.

Edit the Max Occurrences field to specify the maximum number of occurrences this element is allowed to appear in the contributed extension XML mark-up. This field's value is used by PDE to validate multiplicity constraints within the Plug-in Manifest Editor. If Element A specifies 2 maximum occurrences, then no more than 2 instances of Element A can be defined in the contributed extension XML mark-up to remain valid.

Check the Unbounded field to specify that there is no constraint on the maximum number of allowed occurrences this element may appear within the contributed extension XML mark-up.

Use the read-only DTD approximation field to view an approximate one-to-one mapping of the element schema grammar to the equivalent element DTD grammar. The notation used to specify the DTD approximation is described under the Element Details Section Fields heading in this document.

### Element Reference Details Section Actions

Click the element-name hyperlink within the Reference field to edit the properties of the global element declaration this local element reference refers to. When this action is complete, the referenced element node is selected in the Extension Point Elements section and the corresponding Element Details section is activated.

### Attribute Details Section

This section allows you to edit the properties of an attribute. Attributes are used to provide additional information about elements.

This section is activated by selecting either a required attribute, optional attribute, class attribute or resource attribute node in the Extension Point Elements section.

The Attribute Details section for a required attribute of type string that specifies an enumeration restriction.

The Attribute Details section for an optional attribute of type boolean that specifies a default value.

The Attribute Details section for a class attribute that indicates that the class represented by the attribute value must extend the specified class and / or implement the specified interface.

The Attribute Details section for a resource attribute.

### Using the Schema Indentifier Attribute

Extension point authors can define attributes that reference other attributes. This is accomplished by setting your extension point attributes as type identifier and choosing the attribute it references. An example of this would be the org.eclipse.ui.handlers extension point. The commandId attribute references commands defined in the org.eclipse.ui.commands extension point.

Extension developers contributing a handler can then select from all valid identifiers for the commandId attribute. Warnings are issued for identifiers that don't exist to prevent the common mistake of a misspelled identifier.

### Attribute Details Section Fields

Edit the Name field to specify the attribute name.

Click either the true button or false button within the Deprecated field to indicate whether the attribute is deprecated or not. The Plug-in Manifest Editor will flag any extension XML mark-up that is deprecated with a warning (by default). This field is analogous to Java's Javadoc @deprecated tag.

Select a value from the Use field to indicate whether the attribute must be specified on its defining element within contributed extension XML mark-up. The following selections are available:

- optional - The attribute may be optionally specified on its defining element.
- required - The attribute must be specified on its defining element.
- default - The attribute may be optionally specified on its defining element. If the attribute is not specified, then its value will assume the defined default value.

Edit the Default Value field to specify the default value to use for an attribute when it is not specified on its defining element within contributed extension XML mark-up. This field is only applicable when the default value from the Use field is selected.

Select a value from the Type field to specify the attribute value type. The following selections are available:

- string - The attribute value can be any valid string.
- boolean - The attribute value can be either true or false (case insensitive).
- java - The attribute value can be any fully-qualified class name on the target platform's classpath (e.g. java.lang.String).
- resource - The attribute value can be any project relative path to an existing file or folder resource.

Click either the true button or false button within the Translatable field to indicate whether the attributes's value is translatable or not. This field is only applicable when the string value from the Type field is selected. If an attribute's value is marked as translatable, then PDE tools can be used on contributed extension XML mark-up to externalize these values into a properties file for multi-language support.

Use the Restrictions field to view a list of string values the attribute is restricted to using as its own value. If the field contains no values, then there are no restrictions on the attribute value. This field is only applicable when the string value from the Type field is selected. Note: An enumeration restriction on the string base type is used in the edited schema's grammar to accomplish this functionality.

Edit the Extends field to specify a fully-qualified class name on the target platform's classpath (e.g. org.eclipse.ui.part.EditorPart) that must be sub-classed by the class specified as the attribute value. PDE will validate the class attribute value in the contributed extension XML mark-up to ensure it extends the super-class. This field is only applicable when the java value from the Type field is selected.

Edit the Implements field to specify a fully-qualified interface name on the target platform's classpath (e.g. org.eclipse.ui.IEditorPart) that must be implemented by the class specified as the attribute value. PDE will validate the class attribute value in the contributed extension XML mark-up to ensure it implements the interface. This field is only applicable when the java value from the Type field is selected.

### Attribute Details Section Actions

Click the Add... button in the Restrictions field to open the New Restriction dialog in order to add a new restriction to the attribute value. Once the dialog is completed, the new restriction is added to the list of string values the attribute is restricted to using as its own value. This action is only available when the string value from the Type field is selected.

Select a string value within the Restrictions field and click the Remove button to remove a restriction from the list of string values the attribute is restricted to using as its own value. This action is only available when the string value from the Type field is selected.

If the value specified in the Extends field refers to a fully-qualified class name on the target platform's classpath, then clicking on the Extends hyperlink will open that class in a new Java source editor. Otherwise, clicking on the Extends hyperlink will open the New Java Class wizard allowing you to create the new class. This action is only available when the java value from the Type field is selected.

If the value specified in the Implements field refers to a fully-qualified interface name on the target platform's classpath, then clicking on the Implements hyperlink will open that interface in a new Java source editor. Otherwise, clicking on the Implements hyperlink will open the New Java Class wizard allowing you to create the new interface. This action is only available when the java value from the Type field is selected.

Click the Browse... button to open the Select Type dialog in order to select an existing class on the target platform's classpath to use as the value for the Extends field. This action is only available when the java value from the Type field is selected.

Click the Browse... button to open the Select Type dialog in order to select an existing interface on the target platform's classpath to use as the value for the Implements field. This action is only available when the java value from the Type field is selected.

### Relevant Links

- Extension Point Schema Editor
- New Extension Point Schema Wizard
- Plug-in Manifest Editor