XSD Developer FAQ
frequently asked question and answers

XSD Developer FAQ
Last Modified: March 13th, 2002
If you have additional questions that you would like to see answered in future versions of this FAQ or in the Javadoc, please post them to the XSD newsgroup.

Table of contents:
General Goto Toptop
  1. What is XML Schema Infoset Model?

    The XML Schema Infoset Model is a reference library for use with any code that examines, creates or modifies XML Schemas (standalone or as part of other artifacts, such as XForms or WSDL documents). The library provides an API for manipulating the components of an XML Schema as described by the W3C XML Schema specifications, as well as an API for manipulating the DOM-accessible representation of XML Schema as a series of XML documents, and for keeping these representations in agreement as schemas are modified. The library includes services to serialize and deserialize XML Schema documents, and to do integrity checking of schemas (for example, not using a maximum value for a simpleType which is invalid considering the base type of that simpleType).

    The model incorporates many of the ideas that several people at IBM had about an excellent API for schemas. These ideas were shared with the W3C in February 2002, in a requirements document.


Download and Install Goto Toptop
  1. How do I install XSD Infoset Model?

    Download the version of XSD that matches your installation of Eclipse.  Exit Eclipse, and unzip into the eclipse directory.


  2. What should my Java CLASSPATH include, in order to use the library?

    The classpath should be:

    • plugins/org.apache.xerces_4.0.7/xmlParserAPIs.jar;
    • plugins/org.apache.xerces_4.0.7/xercesImpl.jar;
    • plugins/org.eclipse.emf.common_1.0.2/runtime/common.jar;
    • plugins/org.eclipse.emf.ecore_1.0.2/runtime/ecore.jar;
    • plugins/org.eclipse.xsd_1.0.2/runtime/xsd.jar;
    • plugins/org.eclipse.xsd_1.0.2/runtime/xsd.resource.jar; (needed at runtime, not compile at time)
    • yourcode.jar
    Note that this version requires the use of Xerces-J 2.0.2 (or XML4J 4.0.7). Other versions of Xerces-J may not work properly.




  3. What steps should I take to install the source code in one Eclipse project, and to identify another project with my own code as dependent upon and using this library?

    To install the source code in an Eclipse new project, follow these steps :

    • unzip org.eclipse.xsd.zip in <XSD_HOME> directory
    • create a new Eclipse project and import into it the content of <XSD_HOME>/plugins/org.eclipse.xsd
    • set the directory containing the source of the new project to "src" (this directory was imported in the previous step)
    • add the following locations to the classspath:
      • <ECL_HOME>/plugins/org.apache.xerces_4.0.7/xercesImpl.jar;
      • <ECL_HOME>/plugins/org.apache.xerces_4.0.7/xmlParserAPIs.jar;
      • <XSD_HOME>/plugins/org.eclipse.emf.ecore_1.0.2/runtime/ecore.jar;
      • <XSD_HOME>/plugins/org.eclipse.emf.common_1.0.2/runtime/common.jar;
      <ECL_HOME> is the directory where ECL has been installed and <XSD_HOME> is the directory where xsd.zip has been unzipped.

    To identify another project with your own code as dependent upon and using this library, follow these steps :

    • make sure that you have created a new project containing the code of this library as indicated previously;
    • right click on the project folder which should use this library, click on "properties" popup menu item
    • then, in the java Build Path section, go to the Project pane and check the project you previously created for this library.




Capabilities Goto Toptop
  1. Can this library be used outside of the Eclipse environment?

    Yes, it can be used within Eclipse and outside of Eclipse.

    Please note that when running outside Eclipse, you need to include on your classpath this additional jar:

      plugins/org.eclipse.xsd_1.0.2/runtime/xsd.resources.jar




  2. What version of W3C XML Schema is accepted as input?

    The version specified on May 2, 2001 as a W3C Recommendation. This version is described in XML Schema Part 0: Primer, XML Schema Part 1: Structures, and XML Schema Part 2: Datatypes.




  3. Does this library allow me to supply an instance document and have it validated against the schema?

    No. Validating parsers, such as Xerces, should be used for this function.




  4. Is there a function to inquire "Is this parsed or constructed schema completely correct?"

    You can call validate on a schema and check whether there are any diagnostics. The diagnostics may include warnings or informational messages, in addition to error messages.




Compatibility Goto Toptop
  1. What version(s) of Eclipse does this code work on?

    Eclipse 2.1 (and 2.0.x)




Error Handling Goto Toptop
  1. What happens if I pass a DOM which claims to be the XML representation of a Schema, but there are errors in the attribute values?

    The schema can be validated to diagnose all such errors. See the capabilities.




How To Learn Goto Toptop
  1. Are there sample Java methods that show how to use the API?

    Sample code that includes links back to the javadoc is at: XSDPrototypicalSchema.html.

    Examples of convenience functions also illustrate the use of the bare API. Those example convenience functions are in the source code. Info about them is located at XSDSchemaBuildingTools.html and XSDSchemaQueryTools.html.




Miscellaneous Goto Toptop
  1. Is there a way to have schema documents which reference other schema documents through <include> <import> or <redefine> be fetched from locations other than those given in the schemaLocation attribute?

    Yes, you can use a ResourceSet's URIConverter's URI map to map logical URIs to physical URIs. You can see an example of that code in XSDProtocotypicalSchema traceLoading().




  2. When modification are made to a schema document which was used by another schema document (which has been loaded by this library), will my code need to explicitly make the corresponding modifications to the using schema document?

    Yes.




  3. How does the model choose what prefix to use in QNAMEs for a namespace URI in serializing the schema, when more than one prefix has been associated with that namespace?

    One of the prefixes, or the no-prefix, will be chosen, and used consistently whenever an XML representation of schema in the form of a DOM is requested. This version of the code does not allow you to select which one will be chosen.




  4. Does the o1.equals(o2) method determine "semantic equivalence" between two schema components?

    This version of the code returns true if o1 and o2 are the same object, otherwise it returns false.




  5. What happens if I add a schema component to schema2 that I had previously added to schema1?

    It is removed from schema1. This package maintains referential integrity for black diamond relations (in the UML), i.e., containment relations. When you add/set to a black diamond relation, the object will be effectively removed from the current black diamond relation and is then added/set to the new relation.




  6. ComplexTypes and SimpleTypes only have at most 1 annotation. Why is there XSDTypeDefinition.getAnnotations() in addition to getAnnotation(). What is getAnnotations() used for?

    There can be at most one annotation in the element information item in the XML Representation of schema which is a <simpleType> or <complexType>. But there can also be an annotation in the <restriction>, <extension>, <list>, <union> (getDerivationAnnotation), as well as one in the <simpleContent>, <complexContent> (getContentAnnotation) element information items that are part of (children of) the simpleType or complexType element information item. The list returned by getAnnotations() is the list of all these annotations.




  7. If I used one of the getEffectivePROPERTY() methods with a simpleType of the LIST or UNION type, would any of the facet information from the itemType (in the case of List) or the memberTypes (in the case of union) be used to adjust or supplement the values returned (as happens with a simpleType which is atomic and derived by restriction from another type)?

    No. We follow the concepts of effective properties from the W3C Schema specifications, which do not cause facets of the memberTypes or item types to be used in the case of UNION or LIST.




  8. What can cause some of the resources in a resource set, which correspond to schema documents referenced by <include> <import> or <redefine>, to return null from (XSDResourceImpl)resource.getSchema() ?

    This could be seen if you iterate through the resource in a ResourceSet, for example:

    for (Iterator resources = resourceSet.getResources().iterator(); resources.hasNext();) 
      { Resource resource = (Resource)resources.next(); /* Now use getSchema() */ }
    
    If the <include> <import> or <redefine> contained a schemaLocation which has a relative file path, the library will not resolve it, and this can be a symptom.

    To get around this problem, have code which is guaranteed to turn the URI into an absolute URI. For example:

     File file = new File(schemaURL);
     if (file.isFile()) {
       schemaURL = URI.createFileURI(file.getCanonicalFile().toString()).toString();
     }
    




  9. How is a declaration of an attribute or element that specifies anySimpleType processed?

    Following the clarifications to the spec, it is permissible to use anySimpleType in user schemas. However, it is an error to extend or restrict this type except in the schema for schemas.

    Note that an element declaration with an anyType will resolve its type to the complex version of "anyType" and an attribute declaration with an anyType will resolve its type to the simple version of "anyType"; an element's type may be simple or complex, but an attribute's type must be simple.




  10. When will getElement() return null when used against a component?

    If the component you have has been synthesized, getElement() will return null. For example, if you have selected the effective pattern facet, the model synthesized that facet from the zero or more concrete pattern facets. Another effective facet that comes from zero to an unlimited number of concrete facets is the enumeration facet.

    If an XSDComplexTypeDefinition exists that extends another one, normally a synthesized XSDModelGroup is produced, containing one or more synthesized XSDParticle objects; getElement() against those components would also return null.




Programming Tricks Goto Toptop
  1. To obtain a component of a schema by name, or find out such a component does not exist in the schema, what sequence of code should be used?

    The resolveXXXDeclaration and resolveXXXDefinition methods declared in Interface org.eclipse.xsd.XSDConcreteComponent allow lookup of components that have names. Note that these methods always return something. If your schema does not have the component you are looking for, the returned value will be a newly manufactured reference to it.

    Here is an example method to return the component or return null if it was not in the schema, in this case for an Attribute Declaration with a particular name:

    /**
    return the XSDAttributeDeclaration of a given namespace and name defined in a given schema 
    or a schema it includes, redefines or imports
    */
    
    static XSDAttributeDeclaration 
      getAttributeDeclaration(XSDSchema schema, String namespace, String name) {
      
      XSDAttributeDeclaration ret=schema.resolveAttributeDeclaration(namespace,name);
      if (ret.getContainer() == null()) {
        return null;
      } else {
        return ret;
      }
    }
    




  2. How can the attribute maxOccurs="unbounded" be set on a particle?

    Use XSDParticle.setMaxOccurs(-1) to set an unbounded value for maxOccurs. XSDParticle.getMaxOccurs will return -1 if a particle has an unbounded value for maxOccurs.




  3. When passed an object of type XSDSchema, what method tells me if it was parsed from a Resource?

    xsdSchema.eResource() returns a Resource, if one is associated, or returns nill. The Resource returned has methods such as getURI().




  4. When passed an object of type XSDSchema, what method permits me to alter the Resource in which it will be serialized?

    r = xsdSchema.eResource() returns the Resource associated with an XSDSchema. You may invoke r.setURI(uri) if you wish the schema to be saved in the future to another location.




  5. How do I remove a component from the Schema?

    There is generic support for remove in EMF:

      EcoreUtil.remove
    
    The removed component will look like an unresolved reference to any components that still reference it.




  6. If I want the library to parse a Schema from a file which does not have the extension .xsd, or serialize a Schema to a file which does not have the extension .xsd, what do I do?

    As part of your initialization, for each extension that will contain schemas (shown as foo in this example), you should call

    org.eclipse.emf.resource.Resource.Factory.Registry.INSTANCE.registerExtension("foo", 
      new XSDResourceFactoryImpl());
    




  7. Is there a function to inquire "Did this parsed schema have unresolved <include> <import> or <redefine> directives?"

    You can write code like this:

    if (xsdSchema.getAllDiagnostics().isEmpty()) { xsdSchema.validate(); } 
    if (xsdSchema.getAllDiagnostics().isEmpty()) { /* No Unresolved directives */ }
    else { */ Unresolved directives or other problems */ }
    




  8. Is there a way to determine if a string represents a value that a particular simpleType would consider valid?

    Yes. The call

      yourSimpleTypeDefinition.isValidLiteral("a-particular-string") 
    
    will give you the boolean answer.




  9. When I used the method type.getBaseTypeDefinition(), how do I know when I've reached "the top" -- something like anyType?

    For simpleTypes, you would write:

    yourStopVariable = yourSchema.getSchemaForSchema().resolveSimpleTypeDefinition("anyType"); 
    /* as you loop through from one type definition to another, via getBaseTypeDefinition()
       you compare it to yourStopVariable */
    

    For complexTypes, you would write:

    yourStopVariable = yourSchema.getSchemaForSchema().resolveComplexTypeDefinition("anyType"); 
    /* as you loop through from one type definition to another, via getBaseTypeDefinition()
       you compare it to yourStopVariable */
    

    If you are not sure if your time is simple or complex, you could write:

    yourStopVariable = yourSchema.getSchemaForSchema().resolveTypeDefinition("anyType");
    
    There are recognizers of the special types in XSDConstants:
      XSDConstants.isURType
      XSDConstants.isAnyType
      XSDConstants.isAnySimpleType
    




  10. Because td = resolveTypeDefinition(String nsuri, String name) may return an unresolved instance, which is synthesized to hold the namespace and name, if an existing instance cannot be found, what method can be called to tell whether the resulting type definition is synthesized or whether it comes from an existing instance?

    XSDConcreteComponent.getContainer() will yield null for td if resolveTypeDefinition returned a synthesized type definition.