Catalogs in XMLSpy

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

Home >  User Guide and Reference > DTDs and XML Schemas >

Catalogs in XMLSpy

XMLSpy supports a subset of the OASIS XML catalogs mechanism. The catalog mechanism enables XMLSpy to retrieve commonly used schemas (as well as stylesheets and other files) from local user folders. This increases the overall processing speed, enables users to work offline (that is, not connected to a network), and improves the portability of documents (because URIs would then need to be changed only in the catalog files.)

 

The catalog mechanism in XMLSpy works as outlined below.

 

RootCatalog.xml

When XMLSpy starts, it loads a file called RootCatalog.xml (structure shown in listing below), which contains a list of catalog files that will be looked up. You can modify this file and enter as many catalog files to look up as you like, each in a nextCatalog element. Each of these catalog files is looked up and the URIs in them are resolved according to the mappings specified in them.

 

<?xml version="1.0" encoding="UTF-8"?>

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"

   xmlns:spy="http://www.altova.com/catalog_ext"

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog Catalog.xsd">

  <nextCatalog catalog="%PersonalFolder%/Altova/%AppAndVersionName%/CustomCatalog.xml"/> 

  <nextCatalog catalog="CoreCatalog.xml"/>

  <!-- Include all catalogs under common schemas folder on the first directory level -->

  <nextCatalog spy:recurseFrom="%AltovaCommonFolder%/Schemas" catalog="catalog.xml" spy:depth="1"/>

  <!-- Include all catalogs under common XBRL folder on the first directory level -->

  <nextCatalog spy:recurseFrom="%AltovaCommonFolder%/XBRL" catalog="catalog.xml" spy:depth="1"/>

</catalog>

 

In the listing above, notice that in the Schemas and XBRL folders of the folder identified by the variable %AltovaCommonFolder% are catalog files named catalog.xml. (The value of the %AltovaCommonFolder% variable is given in the table below.)

 

The catalog files in the Altova Common Folder map the pre-defined public and system identifiers of commonly used schemas (such as SVG and WSDL) and XBRL taxonomies to URIs that point to locally saved copies of the respective schemas. These schemas are installed in the Altova Common Folder when XMLSpy is installed. You should take care not to duplicate mappings in these files, as this could lead to errors.

 

CoreCatalog.xml, CustomCatalog.xml, and Catalog.xml

In the RootCatalog.xml listing above, notice that CoreCatalog.xml and CustomCatalog.xml are listed for lookup:

 

CoreCatalog.xml contains certain Altova-specific mappings for locating schemas in the Altova Common Folder.
CustomCatalog.xml is a skeleton file in which you can create your own mappings. You can add mappings to CustomCatalog.xml for any schema you require but that is not addressed by the catalog files in the Altova Common Folder. Do this using the supported elements of the OASIS catalog mechanism (see below).
There are a number of Catalog.xml files in the Altova Common Folder. Each is inside the folder of a specific schema or XBRL taxonomy in the Altova Common Folder, and each maps public and/or system identifiers to URIs that point to locally saved copies of the respective schemas.

 

Location of catalog files and schemas

The files RootCatalog.xml and CoreCatalog.xml are installed in the XMLSpy application folder. The file CustomCatalog.xml is located in your MyDocuments\Altova\XMLSpy folder. The catalog.xml files are each in a specific schema folder, these schema folders being inside the folders: %AltovaCommonFolder%\Schemas and %AltovaCommonFolder%\XBRL.

 

Shell environment variables and Altova variables

Shell environment variables can be used in the nextCatalog element to specify the path to various system locations (see RootCatalog.xml listing above). The following shell environment variables are supported:

 

%AltovaCommonFolder%

C:\Program Files\Altova\Common2019

%DesktopFolder%

Full path to the Desktop folder for the current user.

%ProgramMenuFolder%

Full path to the Program Menu folder for the current user.

%StartMenuFolder%

Full path to Start Menu folder for the current user.

%StartUpFolder%

Full path to Start Up folder for the current user.

%TemplateFolder%

Full path to the Template folder for the current user.

%AdminToolsFolder%

Full path to the file system directory that stores administrative tools for the current user.

%AppDataFolder%

Full path to the Application Data folder for the current user.

%CommonAppDataFolder%

Full path to the file directory containing application data for all users.

%FavoritesFolder%

Full path of the Favorites folder for the current user.

%PersonalFolder%

Full path to the Personal folder for the current user.

%SendToFolder%

Full path to the SendTo folder for the current user.

%FontsFolder%

Full path to the System Fonts folder.

%ProgramFilesFolder%

Full path to the Program Files folder for the current user.

%CommonFilesFolder%

Full path to the Common Files folder for the current user.

%WindowsFolder%

Full path to the Windows folder for the current user.

%SystemFolder%

Full path to the System folder for the current user.

%LocalAppDataFolder%

Full path to the file system directory that serves as the data repository for local (nonroaming) applications.

%MyPicturesFolder%

Full path to the MyPictures folder.

 

How catalogs work: DTDs

Catalogs are commonly used to redirect a call to a DTD to a local URI. This is achieved by mapping, in the catalog file, public or system identifiers to the required local URI. So when the DOCTYPE declaration in an XML file is read, the public or system identifier locates the required local resource via the catalog file mapping.

 

For popular schemas, the PUBLIC identifier is usually pre-defined, thus requiring only that the URI in the catalog file point to the correct local copy. When the XML document is parsed, the PUBLIC identifier in it is read. If this identifier is found in a catalog file, the corresponding URL in the catalog file will be looked up and the schema will be read from this location. So, for example, if the following SVG file is opened in XMLSpy:

 

<?xml version="1.0" standalone="no"?>

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"

"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

 

<svg width="20" height="20" xml:space="preserve">

  <g style="fill:red; stroke:#000000">

     <rect x="0" y="0" width="15" height="15"/>

     <rect x="5" y="5" width="15" height="15"/>

  </g>

</svg>

 

This document is read and the catalog is searched for the PUBLIC identifier. Let's say the catalog file contains the following entry:

 

<catalog>

  ...

    <public publicId="-//W3C//DTD SVG 1.1//EN" uri="schemas/svg/svg11.dtd"/>

  ...

</catalog>

 

In this case, there is a match for the PUBLIC identifier, so the lookup for the SVG DTD is redirected to the URI schemas/svg/svg11.dtd (this path is relative to the catalog file), and this local file will be used as the DTD. If there is no mapping for the Public ID in the catalog, then the URL in the XML document will be used (in the example above: http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd).

 

How catalogs work: Schemas

In XMLSpy, you can also use catalogs to redirect to an XML Schema. In the XML instance file, the reference to the schema will occur in the xsi:schemaLocation attribute of the top-level document element of the XML document. For example,
 

xsi:schemaLocation="http://www.xmlspy.com/schemas/orgchart OrgChart.xsd"

 

Normally, the URI part of the attribute's value (bold in the example above) is a path to the actual schema location. However, if the schema is referenced via a catalog, the URI part need not point to an actual XML Schema, but it does need to exist so that the lexical validity of the xsi:schemaLocation attribute is maintained. A value of foo, for example, would be sufficient for the URI part of the attribute's value. The schema is located in the catalog by means of the namespace part of the xsi:schemaLocation attribute's value. In the example above, the namespace part is http://www.xmlspy.com/schemas/orgchart. In the catalog, the following entry would locate the schema on the basis of that namespace part.

 

<uri name="http://www.xmlspy.com/schemas/orgchart" uri="C:\MySchemas\OrgChart.xsd"/>        

 

The catalog subset supported by XMLSpy

When creating entries in CustomCatalog.xml (or any other catalog file that is to be read by XMLSpy), use only the following elements of the OASIS catalog specification. Each of the elements below is listed with an explanation of their attribute values. For a more detailed explanation, see the XML Catalogs specification. Note that each element can take the xml:base attribute, which is used to specify the base URI of that element.

 

<public publicId="PublicID of Resource" uri="URL of local file"/>
<system systemId="SystemID of Resource" uri="URL of local file"/>
<uri name="filename" uri="URL of file identified by filename"/>
<rewriteURI uriStartString="StartString of URI to rewrite" rewritePrefix="String to replace StartString"/>
<rewriteSystem systemIdStartString="StartString of SystemID" rewritePrefix="Replacement string to locate resource locally"/>

 

In cases where there is no public identifier, as with most stylesheets, the system identifier can be directly mapped to a URL via the system element. Also, a URI can be mapped to another URI using the uri element. The rewriteURI and rewriteSystem elements enable the rewriting of the starting part of a URI or system identifier, respectively. This allows the start of a filepath to be replaced and consequently enables the targeting of another directory. For more information on these elements, see the XML Catalogs specification.

 

From release 2014 onwards, XMLSpy adheres closely to the XML Catalogs specification (OASIS Standard V1.1, 7 October 2005) specification. This specification strictly separates external-identifier look-ups (those with a Public ID or System ID) from URI look-ups (URIs that are not Public IDs or System IDs). Namespace URIs must therefore be considered simply URIs—not Public IDs or System IDs—and must be used in URI look-ups rather than external-identifier look-ups. In XMLSpy versions prior to version 2014, schema namespace URIs were translated through <public> mappings. From version 2014 onwards, <uri> mappings have to be used.

 

Prior to v2014:  <public publicID="http://www.MyMapping.com/ref"  uri="file:///C:/MyDocs/Catalog/test.xsd"/>

V-2014 onwards:  <uri name="http://www.MyMapping.com/ref"  uri="file:///C:/MyDocs/Catalog/test.xsd"/>

 

File extensions and intelligent editing according to a schema

Via catalog files you can also specify that documents with a particular file extension should have XMLSpy's intelligent editing features applied in conformance with the rules in a schema you specify. For example, if you create a custom file extension .myhtml for (HTML) files that are to be valid according to the HTML DTD, then you can enable intelligent editing for files with these extensions by adding the following element of text to CustomCatalog.xml as a child of the <catalog> element.

 

<spy:fileExtHelper ext="myhtml" uri="schemas/xhtml/xhtml1-transitional.dtd"/>

 

This would enable intelligent editing (auto-completion, entry helpers, etc) of .myhtml files in XMLSpy according to the XHTML 1.0 Transitional DTD. Refer to the catalog.xml file in the %AltovaCommonFolder%\Schemas\xhtml folder, which contains similar entries.

 

XML Schema specifications

XML Schema specification information is built into XMLSpy and the validity of XML Schema (.xsd) documents is checked against this internal information. In an XML Schema document, therefore, no references should be made to any schema that defines the XML Schema specification.

 

The catalog.xml file in the %AltovaCommonFolder%\Schemas\schema folder contains references to DTDs that implement older XML Schema specifications. You should not validate your XML Schema documents against these schemas. The referenced files are included solely to provide XMLSpy with entry helper info for editing purposes should you wish to create documents according to these older recommendations.

 

More information

For more information on catalogs, see the XML Catalogs specification.

 


© 2019 Altova GmbH