Facets

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  User Guide and Reference > Editing Views > Schema View > Entry Helpers in Schema View >

Facets

A new simple type (named or anonymous) is created by restricting the simple type's base type (which is an existing simple type). Such a restriction is effected by adding facets to restrict the values of the base type. In Schema View, the Facets entry helper (see screenshots below) enables you to graphically and easily edit the facets of a simple type. The available facets are organized in tabs of the Facets entry helper as listed in the table below.

 

Tab

Available facets

Facets

minInclusive, maxInclusive, minExclusive, maxExclusive, length, minLength, maxLength, totalDigits, fractionDigits, whiteSpace, explicitTimezone

Patterns

pattern

Enumerations

enumeration

Assertions

assertion

Samples

altova:exampleValues is an annotation, not a facet. This annotation is used to generate sample values in the instance XML document generated by XMLSpy from the XML Schema.

 

Each of these tabs is described in the sections below.

 

Selecting the simple type in the design

A simple type (named or anonymous) can be selected in the following design environments:

 

In Schema Overview (either in the global components list or in the Attributes tab below the global components list), or
In Content Model View (either in the diagram or in the Attributes tab below the diagram).

 

When a simple type is selected in the design in any of the design environments listed above, applicable facets in the Facets entry helper become enabled and can be edited in the Facets entry helper.

 

Facets tab

In the Facets tab, only facets applicable to the type selected in the design will be displayed. For example, if it is the xs:string type that is being restricted, then non-applicable facets like totalDigits will not be displayed.

 

The four bounds facets (minInclusive, maxInclusive, minExclusive, maxExclusive) are applicable only to the numeric and date/time types and to types derived from these types.
The three length facets (length, minLength, maxLength) are applicable only to string-based types, the binary types, and anyURI.
The totalDigits facet apply to xs:decimal and integer types, and to any types derived from them. The fractionDigits facet can be applied only to xs:decimal.

EHFacetsFacetsEP

To enter a value, either select a value from the dropdown list of a combo box (if present) or double-click in the value field and enter a value. If an invalid value is entered, the resulting conflicts are displayed in red. Valid values are displayed in blue. For example, a minInclusive facet and a maxInclusive facet cannot exist together; so if a value is entered for the second of these facets, then the values of both facets are displayed in red.

 

To specify a fixed facet (giving the facet an attribute-value of fixed="true"), click the open-lock symbol to the right of the facet so that the symbol becomes a closed-lock. In the screenshot above, the totalDigits facet has been set as a fixed facet. More than one facet can be fixed. To unfix a facet, click the closed-lock symbol to make it an open-lock symbol.

 

Patterns tab

In the Patterns tab (screenshot below), you can add one or more pattern facets to a restriction. The pattern (of a pattern facet) is specified with the regular expression syntax. The pattern in the screenshot below specifies the pattern of email addresses.

EHFacetsPatternsEP

If multiple pattern facets are specified, then the XML instance value must match one of the specified patterns. For example, a pattern to restrict postcodes could have two pattern facets, one each for US and EU postcodes. An XML instance value must then match one of the patterns for it to be valid.

 

Add a pattern facet by clicking the Append or Insert icon at top left and then entering a regular expression to define the required pattern. To delete a pattern, select it and click the Delete icon at top right.

 

Enumerations tab

In the Enumerations tab (screenshot below), you can add one or more enumeration facets to a restriction. Each enumeration facet specifies a valid value for the type. Taken together, a set of enumeration facets specifies a range of allowed values. In the screenshot below, enumeration facets specify the allowed range of size values for the restriction.

EHFacetsEnumerationsEP

Add an enumeration facet by clicking the Append or Insert icon at top left and then entering the enumeration value. To delete an enumeration, select it and click the Delete icon at top right.

 

Assertions tab

Assertions are an XSD 1.1 feature. So the Assertions tab will be enabled only in XSD 1.1 mode. Assertion facets defined in the Assertions tab of the Facets entry helper are assertions for simple types—as opposed to assertions for complex types (which can be defined and edited in Schema Overview or Content Model View, not in the Facets entry helper).

 

When a simple type (element or attribute of simple content) is selected in the design, an assertion can be specified for it by switching to the Assertions tab (see screenshot below), clicking the Append or Insert icon at top left, and then entering the XPath 2.0 expression that will be used to define the assertion. A special variable called $value must be used in the XPath expression to hold the value of the simple type. (Note that, since there are no descendants to test but only a value, the normal self::node() path step (or the period abbreviation of this path step '.') cannot be used in the XPath expression.)

 

For example, the XPath expression string-length($value) = 6 (see screenshot below) tests whether the value of the simple type has six characters. If the element or attribute in the instance document does have six characters, then it is valid according to the assertion.

EHFacetsAssertionsEP

Note:Syntax errors in the XPath expression will be flagged by the expression turning red. But, since the datatype is determined at runtime, type errors will not be flagged when you enter the XPath expression. You must take care to construct types as required. For an example of type construction, see the third XPath expression in the screenshot above, which converts a string value (assuming that the assertion is defined on an xs:string simple type) into a number before doing a numeric comparison.

 

Multiple assertions can be specified on a single simple type, as in the screenshot above. In this case, all the assertions must be satisfied for the element or attribute in the instance document to be valid. The assertions in the screenshot above specify that the instance document value must be a six-character string starting with the characters EU and having numeric characters that have a number value of 0000 to 4999 as its final four characters.  To edit the details of an assertion, right-click the assertion in the Facets entry helper, and click Details in the menu that pops up. This brings up the Assertion Details modal window (see screenshot below).

AssertionMessageXSD

It is very useful if an explanation of the assertion is supplied together with its definition, so that in case the assertion is not fulfilled when the XML instance document is validated, an appropriate message can be displayed. Since the XML Schema specification does not make provision for such a message, XMLSpy allows a message in the Altova xml-schema-extensions namespace http://www.altova.com/xml-schema-extensions (or any other namespace) to be provided with the definition of the assertion and to be used in the validation of the XML instance document. For example:

 

<xs:assert test="count(//MyNode) ge 1altova:message="There must be at least one MyNode element"/> or

<xs:assertion test="count(//MyNode) ge 1altova:message="There must be at least one MyNode element"/>

 

If the restriction specified in the assertion is not fulfilled, XMLSpy's validation engine will display, along with the validation-error message, the message associated with the assertion as a hint. The validator will report the value of an assert/@message attribute or of an assertion/@message attribute regardless of the namespace in which the message attribute is. However, in Schema View, you can edit only message attributes that are in the Altova xml-schema-extension namespace. To edit message attributes in other namespaces, use Text View.

 

 

See Assertion Messages for details.

 

Note:It is a good practice recommendation to use other facets in preference to assertions where possible. For example, the restriction specified by the first assertion in the screenshot above would be better specified by the length facet (in the Facets tab).

 

Samples tab

In the Samples tab (screenshot below), you can specify sample values that can be used when generating an XML file from the XML Schema (with the menu command DTD/Schema | Generate Sample XML File). If a sample value is invalid, a warning is indicated by displaying the sample value in orange. In the screenshot below, the first value is invalid because it does not match the pattern facet specified for emails (see Patterns tab above).

EHFacetsSamplesEP

Note:Click the Display Validation Warnings icon icValWarnings in the toolbar to switch on the display of invalid sample-value warnings. An invalid sample value does not invalidate the XSD file if the file is valid in other respects.

 

Sample values are placed in an altova:example annotation element that is in the http://www.altova.com/xml-schema-extensions namespace. Add an altova:example annotation by clicking the Append or Insert icon at top left and then entering the altova:example value. To delete an altova:example annotation, select it and click the Delete icon at top right.

 


© 2019 Altova GmbH