An understanding of the PSVI requires a basic understanding of the XML Infoset. The XML Information Set, or infoset, is an abstract description of the information present in an XML document. In other words, the infoset defines a common vocabulary for the information in an XML document. For simplicity, the information is described as a tree; however there is no requirement that implementations provide the document infoset using a tree structure. For example, the document infoset could be provided using a streaming model (e.g. SAX) where events received by an application contain some properties of the XML Infoset.

The infoset is defined for a well-formed document, that also conforms to the Namespaces in XML specification [Namespace in XML]. A document’s infoset is comprised of a number of information items, each of which is a description of some part of the XML document. Each information item has a number of associated properties, which are denoted in square brackets.

The infoset for a document will contain a single document information item, as well as several other information items. The properties of a document information item provide information about the document as a whole, such as:

There is an element information item for each element in the XML document. We have already seen that one such element information item is the [document element]. Each element information item has properties describing information about the element. Some examples are:

Similarly, attribute information items provide information about attributes in the document’s infoset. As with element information items, the properties for an attribute contain information about the namespace and local name of the attribute, in addition to information specific to attributes, such as:

As we have seen already, one of the possible [children] of an element information item is a character information item. A character information item is provided for each data character that appears in an XML document, and has the following properties:

Other information items include: processing instruction information items, unexpanded entity reference information items, comment information items, unparsed entity information items, notation information items, namespace information items and the document type declaration information item. See the “XML Information Set (Second Edition)” [XML Information Set] for more details about these items.

Consider the following XML instance document:

<p:person xmlns:p=”http://www.example.com/people”>
	<firstName>Sue</firstName>
	<lastName>Smith</lastName>
	<dateofbirth>1960-10-23</dateofbirth>
</p:person>
         

The following shows some of the information items and selected properties for this example.

The infoset associated with an XML document may be retrieved using the W3C Document Object Model API [Document Object Model]. The most recent DOM Level 3 Recommendation has added several new methods for the XML Infoset information items ([Discover key features of DOM Level 3 Core]) missing from DOM Level 2. For example, you can retrieve an [attribute type] property on the attribute information item using the schemaTypeInfo attribute of the Attr interface.

To retrieve the properties of the document information item, use the Document interface, as shown in the figure below:

Document doc; 
...
// get the document element
Element documentElement = doc.getDocumentElement();  

// get the character encoding scheme
String characterEncoding = doc.getXMLEncoding();  

//get the version of the document
String version = doc.getXmlVersion();  
...

Also, it is possible to access to information for an element using the Element interface defined in DOM, and to the data in an attribute information item using the Attr interface. For more information on these interfaces and other interfaces that provide access to the infoset in DOM, see Appendix C in the DOM Level 3 Core specification ([Document Object Model]) that provides the mappings between the XML Infoset model and the DOM.

An XML Schema is comprised of components, such as type definitions and element declarations, which can be used to assess the validity of the element and attribute information items covered in the Section 2 section. In the process of verifying that element and attribute information items conform to the Schema, a processor obtains access to additional information about such elements and attributes. The additional information is used to augment the original infoset of the document; this augmented infoset is called the post-schema-validation infoset, or PSVI.

During the assessment of an element information item, it is possible for a completely new attribute information item to be added to the infoset for the element. This is the case when an attribute default value is provided in the schema and no attribute exists in the infoset for the element.

For both element and attribute information items that are assessed, the PSVI contains properties that describe the outcome of the assessment. These properties are as follows:

This information is useful, as it provides very comprehensive information about the validity of an attribute or element and the extent of validation that was performed.

If an element or attribute information item is assessed as invalid, it is also possible to determine the error, or errors, which caused the invalid outcome. The [schema error code] property provides a list of error codes.

If an element or attribute information item is assessed as valid, then the PSVI may contain, at processor option, the element or attribute declaration used for assessment. In the case of element information items, this is the [element declaration] property; for attributes, it is the [attribute declaration] property. If the declaration contains a [value constraint] (i.e. a fixed or default value), then the PSVI will include the [schema default] property, which is the canonical form for the value.

In addition, the PSVI will contain the property [schema normalized value], which is the normalized value of the information item (as validated); for element information items, this property will only appear if the element’s type is simple. The [schema specified] property indicates whether the [schema normalized value] was derived from a default value in the schema or not.

The PSVI also provides information about the type definition used for validation of the element or attribute information; two alternate sets of properties may be included in the PSVI, depending on whether the schema processor is light-weight or not. The first set (which is the most informative) consists of the following properties:

Element information items have additional properties in the PSVI. If identity constraints apply to a particular element, then the PSVI may contain, at processor option, an identity constraint table containing information about each eligible identity constraint. In addition, if an element information item contains an attribute information item that is valid with respect to a NOTATION, then additional PSVI properties providing information about the NOTATION declaration are included in that element’s PSVI. See “XML Schema Part 1: Structures” [XML Schema Part 1] for more details.

Finally, the element information item at which assessment began (i.e. the validation root) has additional properties that provide information that is global to the schema assessment. For example, the PSVI may be augmented, at processor option, with an ID/IDREF table, providing ID/IDREF binding information. There are additional properties that provide information about the resulting schema. For example, for each target namespace in the schema, the following information is included:

Therefore, it is possible for an application to obtain complete information about all of the components in the schema. This is useful for applications such as query processors that must be able to access information about type hierarchy.

Consider the following schema, which can be used to validate the person.xml described in Figure 1:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:p="http://www.example.com/people"
        targetNamespace="http://www.example.com/people">

<complexType name="personType">
  <sequence>
     <element name="firstName" type="string"/>
     <element name="lastName" type="string"/>
    <element name="dateofbirth" type="date"/>
 </sequence>
</complexType>

<element name="person" type="p:personType"/>

</schema>

The following shows a portion of the augmentation to the “firstName” element information item (using the example from Figure 1).

To understand the design, it is important to understand the requirements and goals of this API.

The basic requirement of the XML Schema API was to enable users to query the PSVI (i.e. to examine the XML Schema components and query the post-schema-validation infoset items). To satisfy this requirement, the API needs to cover all of the XML Schema components and be isomorphic to the schema components to the greatest possible extent. While this requirement has constrained the design, it also facilitates learning the API for someone who is familiar with the definition of the PSVI.

Designers of the XML Schema API also wanted to encourage multiple implementations. Therefore, the design could not impose any concrete implementation, but needed to allow one to implement the API in a layer that sits on top of applications with different class hierarchies. In this case, the layer provides the necessary glue between the API and the existing internal structure that can be different from the view one gets of it through the API. To satisfy this requirement, we use interfaces rather than classes. In general, interfaces provide a simplified view on what could be a complex internal representation of the data and hide the actual implementation.

The other two requirements that the XML Schema API has been designed with are language and platform independence. The API is independent of the programming language being used and independent of the actual implementation and system that it runs on.

These requirements have also impacted the design in several ways. For instance, as with the DOM API, this API could not rely on the Java™ instanceof operator to query a run-time type of an object. Instead, the API provides a special method to query the type defined on the base interface XSObject for the schema component model.

Another example of a trade-off, given this constraint, is that the API could not use any of the available libraries for containers and lists. The API defines a specialized collections framework to retrieve and query objects of the types defined in the specification. For example, the StringList interface is an immutable collection of string objects.

Despite the constraints these requirements have placed on the design, the design allowed this API to be implemented in both the C++ and Java Apache Xerces parsers.

The XML Schema API defines the ElementPSVI and AttributePSVI interfaces that allow users to access the PSVI augmentations for element and attribute information items in tree models, such as DOM, and streaming models, such as SAX.

The ElementPSVI and AttributePSVI represent the PSVI items for element and attribute information items respectively. The common properties of the element and attribute post-schema-validation infoset items, such as [schema default], [schema error code], [schema normalized value], [schema specified], and [type definition], are available on the ItemPSVI interface. Both the ElementPSVI and AttributePSVI interfaces extend from the ItemPSVI interface.

In implementations that represent the XML document infoset via some memory structures (e.g. DOM) and support the XML Schema API, the objects that represent element information items should also implement ElementPSVI. Objects that represent attribute information items should also implement AttributePSVI. For example, in a DOM implementation that supports this API, the objects that implement dom.Element also implement ElementPSVI. The objects that implement dom.Attr also implement AttributePSVI.

In implementations that provide a streaming XML document infoset and support the XML Schema API, a parser object should also implement the PSVIProvider interface. The PSVIProvider interface defines methods to retrieve the PSVI augmentations for elements (PSVIElement) and for attributes (PSVIAttribute). These methods must be called within the scope of the document handler's startElement and endElement methods.

Let us take a closer look at how you can retrieve PSVI from DOM and SAX.

System.setProperty(DOMImplementationRegistry.PROPERTY,
  "org.apache.xerces.dom.DOMXSImplementationSourceImpl");

DOMImplementationRegistry registry = 
     DOMImplementationRegistry.newInstance();
DOMImplementation impl = 
     (DOMImplementation) registry.getDOMImplementation("psvi 1.0");

//dbf is a JAXP DocumentBuilderFactory

// all of the following features must be set:
dbf.setNamespaceAware(true);
dbf.setValidating(true);
dbf.setAttribute("http://apache.org/xml/features/validation/schema", 
    Boolean.TRUE);

// you also must specify Xerces PSVI DOM implementation
// "org.apache.xerces.dom.PSVIDocumentImpl"
dbf.setAttribute("http://apache.org/xml/properties/dom/document-class-name", 
   "org.apache.xerces.dom.PSVIDocumentImpl");
            
Document doc = db.parse("person.xml");
Element documentElement = doc.getDocumentElement() ;
if (documentElement.isSupported("psvi", "1.0")){ 
    ElementPSVI psviElem = (ElementPSVI)doc.getDocumentElement();
    XSModel model = psviElement.getSchemaInformation();
    XSElementDeclaration decl = psviElem.getElementDeclaration();
}

public class MyDocumentHandler extends DefaultHandler{
  // Retrieve psviProvider by casting SAXParser to PSVIProvider
  PSVIProvider psviProvider;   
  public void startElement(String uri, String localName, String qname,
                         Attributes attributes) throws SAXException {
    // retrieve partial PSVI information
    ElementPSVI elemPSVI = psviProvider.getElementPSVI();

    // retrieve PSVI information for attributes
    AttributePSVI attrPSVI;
    for (int i=0;i<attributes.getLength();i++){
        attrPSVI = psviProvider.getAttributePSVI(i);
    }
  }
  public void endElement(String uri, String localName, String qname)    
  throws SAXException {
     // retrieve all PSVI augmentations for current element
     ElementPSVI elemPSVI = psviProvider.getElementPSVI();
  }
}

The interfaces defined are isomorphic to the XML Schema components. Most of the interfaces defined in the API map to the schema component they represent, as shown in the following table:

{type definitions} 
{attribute declarations} 
{element declarations} 
{attribute group definitions} 
{model group definitions} 
… 

public XSNamedMap getComponents(short objectType);
         

		  
<simpleType name='employeeId'>
   <restriction base='string'>
     <length value='6'/>
   </restriction>
</simpleType>

<simpleType name='state'>
   <restriction base='string'>
     <enumeration value='NY'/>
     <enumeration value='CA'/>
     <enumeration value='IL'/>
   </restriction>
</simpleType>

public short getDefinedFacets();
public boolean isDefinedFacet(short facetName);        
public String getLexicalFacetValue(short facetName);
public StringList getLexicalEnumeration();
public StringList getLexicalPattern(); 
         

public XSObjectList getFacets();
public XSObjectList getMultiValueFacets();
public XSObjectList getAnnotations();

public boolean derivedFromType(XSTypeDefinition ancestorType, 
                               short derivationMethod);

public boolean derivedFrom(String namespace, 
                           String name, 
                           short derivationMethod);         
         

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:p="http://www.example.com/people"
        targetNamespace="http://www.example.com/people">

<include schemaLocation=”person.xsd”/>

<complexType name="employee">
  <complexContent>
    <extension base="p:personType">
     <sequence>
       <element name="employeeId" type="ID"/>
       <element name="salary" type="integer"/>  
     </sequence>
    </extension>
  </complexContent>
</complexType>

<element name="person" type="p:personType"/>

</schema>         
         

<p:person xmlns:p=”http://www.example.com/people”
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.example.com/people employee.xsd"
   xsi:type="p:employee">…</:p:person>
         

XSTypeDefinition typeEmployee =           
   model.getTypeDefinition(“http://www.example.com/people”, 
   “employee”);

XSTypeDefinition typePerson = 
   model.getTypeDefinition (“http://www.example.com/people”, 
   “person”);

if (typeEmployee.derivedFromType(typePerson, 
     DERIVATION_EXTENSION|DERIVATION_RESTRICTION)){
   // add xsi:type on the instance document
    …
}
         

The schema document can be loaded in memory independently of an XML instance document using the XSLoader interface. As was mentioned before, application developers should use the DOM Level 3 Bootstrapping mechanism to retrieve the XSImplementation that provides a method to create an XSLoader and then use the XSLoader to load the schema, as shown in the following figure:

// set the system property to reference all known DOM implementations
System.setProperty(DOMImplementationRegistry.PROPERTY,
      "org.apache.xerces.dom.DOMXSImplementationSourceImpl");

// get an instance of DOMImplementationRegistry         
DOMImplementationRegistry registry = 
   DOMImplementationRegistry.newInstance();

// retrieve an implementation that supports XSImplmenetation 
// by specifying “XS-Loader” feature  
XSImplementation impl = (XSImplementation) registry.getDOMImplementation("XS-Loader");

// create XSLoader
XSLoader schemaLoader = impl.createXSLoader(null);

XSModel model = schemaLoader.loadURI(“employee.xsd”);
         

The XSModel in this case represents a schema that was created from the employee.xsd document (Figure 14), which includes the person.xsd document (Figure 3). Therefore, the resulting XSModel contains schema components from both schema documents. Using this XSModel, the user can query and examine type definitions, element declarations and other schema components.