Adding entries to the XML Catalog

An XML Catalog entry contains two parts - a Key (which represents a DTD or XML schema) and a Uniform Resource Identifier (URI) (which contains information about a DTD or XML schema's location). You can place the Key in an XML file. When the XML processor encounters it, it will use the XML Catalog entry to find the location of the DTD or XML schema associated with the Key

XML Catalog entries can be used in various situations. For example, you are working on an XML file on your main desktop computer and point its schemaLocation towards a schema called c:\MySchema.xsd. You then save it to your laptop computer so you can work on it later. When you open the file on your laptop, however, you encounter a problem - the XML editor cannot find the MySchema.xsd schema because it is actually installed on your D drive. You will have to edit the schemaLocation to point to d:\MySchema.xsd. When you have finished editing the XML file and are ready to publish it on the Web, you will need to edit the URI again so that it points to a resource that is accessible on the Web. By now, the problem is obvious. A URI used within an XML file is not as portable as you would like it to be. To avoid making frequent changes to your XML document, you can use the XML Catalog.

An XML Catalog entry is used by an XML processor when resolving entity references. You can provide rules to the catalog to specify how entities should be resolved. If you consider the preceding example, you could specify a rule that redirects an Internet resource reference (for example, "http://www.ibm.com/published-schemas/MySchema.xsd") so that it points to a resource on the developer's local machine (for example, "file:///C:/MySchema.xsd"). Now, instead of frequently editing XML documents to update the URIs (especially when there are many documents in your project), you only need to update a single rule in your XML Catalog.

The following instructions were written for the Resource perspective, but they will also work in many other perspectives.

To add an entry to the XML Catalog, follow these steps:

  1. Open the XML file that you want to associate with a DTD or XML schema.
  2. Click Window > Preferences > Web and XML > XML Catalog.
  3. The XML Catalog Entries field contains a list of any user-defined and plug-in defined catalog entries.
    1. Select any entry to see details about it in the Details field.
    2. Click Add to create a new catalog entry.
  4. In the URI field, type the location of the DTD or XML schema or browse for it.
  5. If you specified a DTD in the URI field, you can select either Public ID or System ID from the Key Type field. If you select Public ID, the value you enter in the Key field should be the same as the Public ID in the XML file's DOCTYPE declaration. If you select System ID, the value you enter should correspond to the System ID in an XML file's DOCTYPE declaration.
  6. If you specified an XML schema in the URI field, you can select either Namespace Name or Schema Location from the Key Type field. If the schema defines a target namespace, it will automatically appear in the Key field. Otherwise, you can enter the schema location in the Key field.
  7. Select the Specify alternative Web address check box if you want to be able to specify an alternate Web address for the resource. This Web address is used when an XML instance is generated from this catalog entry. Note: This option is only available if you select Public ID (for a DTD) or Namespace Name (for a schema) in the Key type field.
  8. If you want to refer to another catalog without importing it into the workbench, click Next Catalog. Type or browse for the XML catalog you want to refer to.
  9. When you are done creating catalog entries, click OK to close the Add XML Catalog Entry dialog.
  10. Click Advanced if you want to import or export any XML Catalog settings.
  11. Click Export if you want to persist the XML Catalog information. Only your user specified entries will be exported.
    1. You will be prompted to select a project and provide a file name to store your catalog entries in an .xmlcatalog file, which can be opened from the Navigator view. Snce your catalog entries are stored in an .xmlcatalog file, you can check them in and out and share them like any other project resource.
    2. Click OK.
  12. Click Import if you want to import an .xmlcatalog file. You will be prompted to select the file you want to import.
    1. When you import a .xmlcatalog file, any entries in it will be loaded into the XML Catalog (and any existing entries will be overwritten).
    2. Click OK.
  13. Click OK to close the Advanced XML Catalog Preferences dialog.
  14. Make sure the XML file is in focus and click the Reload dependencies toolbar button.
The XML file is now associated with the latest version of the XML schema or DTD.
Related concepts
XML file associations with DTDs and XML schemas
Related tasks
Editing with DTD or XML schema constraints
Editing DOCTYPE declarations
Updating XML files with changes made to DTDs and schemas
Editing namespace information