InDesign SDK

IDML is designed to be generated and manipulated by XML tools and programmers. To support this, IDML can be validated against a RelaxNG schema.

When it comes to schemas and validation, there are two types of IDML files:

• There are many single-file variants (snippets, assignments, ICML, etc.). These files need to be validated with the snippet schema.
• Packages are multi-file ZIP archives that represent an entire InDesign document. Packages need to be validated with the package schema.
  For more information on IDML files see the “IDML File Types” post.

Generating Schema Files

IDML can be extended by the scripting support in third-party plug-ins. For this reason, the schema used for validation must match a plug-in configuration. Rather than providing a static schema, InDesign provides a means to create a schema from your plug-in configuration. The following sample code demonstrates producing snippet and package schemas with JavaScript.

This snippet schema is used to validate all single-file variants of IDML. It comprises two files:

The package schema comprises one shared file and schema file for each type of XML file that can appear in an IDML package:

Finding Errors in IDML

For demonstration purposes, we need files that contain errors. Imagine the following IDML fragment in both a snippet file (test.idms) and package (test.idml) file. The IDML contains four fairly obvious errors; try to spot all four.

You may have found it difficult to spot all four errors. Imagine if this was buried in a huge XML file. Instead of trying to find errors ourselves, we use schema validation.

Schema Validation Basics

A RelaxNG schema can be used to verify the structural correctness of a document. It checks to make sure all XML nodes (elements, attributes, text data, etc.) are used at the right places in the document. It detects any unknown or unexpected nodes and ensures that required nodes are present.

InDesign’s RelaxNG schemas can be used to check the structure of a document; however, it does not check the content of these nodes. For example, it doesn’t check that all IDML references exist. It’s possible to do some non-RelaxNG-based error detection. This is discussed in “Additional Error Detection” below.

You can validate IDML files with any software that supports the compact form of RelaxNG. For snippet files, this is relatively straightforward: it amounts to pointing whatever validation engine you are using to the IDMarkupLanguage.rnc file (which includes the datatyps.rnc file).

Validating packages is more complex; there are two difficulties:

• Packages are ZIP archives, and most RelaxNG validation engines don’t deal with ZIP files.
• An IDML package comprises many XML files. The package schema comprises several schema files: there is one schema for each type of file that can appear in an IDML file. To validate a package, you need to match each XML file with its appropriate schema file.

Validating with IDMLTools

The InDesign CS4 Products SDK includes a Java package called IDMLTools. This package contains a validation application based on the Jing RelaxNG Validator, which handles both snippets and package files. It’s especially handy for package files, because it unzips the files and matches XML files to the appropriate schema file.
For information about setting up IDMLTools, see the IDML ReadMe. This amounts to the following:

• Add the IDMLTOOLS_HOME environment variable. This should contain the path to your IDMLTools folder. (Do not terminate with a trailing \ or /.)
• Add /bin to your search PATH environment variable. This provides easy access to the validation script.

Once set up, you can validate files by running the appropriate platform script, validate.bat on Windows and validate.sh on Mac OS. These scripts set the appropriate Java classpath and run the validation application. The validation application can be used to validate both types of IDML files (snippets and package files). Running the platform scripts with no arguments produces the following usage message:

Validator SchemaPath PackagePath [PackagePath...]

This means you validate by specifying a path to the schema folder, followed by paths to one or more package files that you want to validate.

Validating a Snippet

To validate the test.idms snippet, specify the path to the snippet schema, followed by the path to the actual snippet:

validate.bat “c:\idml-schema\snippet” test.idms

The validation application writes errors to standard error. Here are the results from validating test.idms:

Test.idms:143:10: error: required attributes missing
Test.idms:144:527: error: attribute “foo” not allowed at this point; ignored
Test.idms:145:14: error: element “RectData” not allowed in this context
Test.idms:146:15: error: element “Propertie” not allowed in this context

Validating a Package

To validate a package specify the path to the package schema, followed by the path to the IDML file:

validate.bat “c:\idml-schema\package” test.idml

The validation application unzips the archive to a temporary directory, validates each file against the appropriate schema file, then writes any errors to standard error.

Here are the results written when validating test.idml:

Spreads\Spread_ubd.xml:3:245: error: required attributes missing
Spreads\Spread_ubd.xml:27:527: error: attribute “foo” not allowed at this point; ignored
Spreads\Spread_ubd.xml:28:14: error: unknown element “RectData”
Spreads\Spread_ubd.xml:29:15: error: unknown element “Propertie”

Notice that the XML file containing the error is reported on the left. In this case, the error is in the Spread_ubd.xml file. Because package validation deals with multiple XML files in one pass, error results can come from several files.

Interpreting the Results

From the results above, we can deduce the four errors:

1. The Spread element is missing a required attribute. Unfortunately, Jing does not report which attribute is missing, but it is easy enough to look at the schema or Adobe InDesign CS4 IDML File Format Specification and determine that it is the Self attribute that is missing.
2. There is no “foo” attribute on the Rectangle element.
3. “RectData” is not a child of the Rectangle element.
4. Rectangle does not have a child element called “Propertie.” Looking at the schema, Adobe InDesign CS4 IDML File Format Specification, and numerous other examples, we can conclude that this element should be called “Properties” (with an ‘s’).

Additional Error Detection

The IDMLTools validation application includes some non-RelaxNG-based error detection. Currently, it checks for the following errors:

• Missing designmap.xml file.

• Missing or improper processing instruction at the top of the designmap.xml file.

• Missing package files included in designmap.xml; e.g., Spreads/Spread_ubd.xml in the following output:

Because Adobe distributes the source for IDMLTools, it’s possible to add additional error detection. You’ll find the code for these items in the Validator.preVerifyPackage() method.

IDML (InDesign Markup Language) is an XML-based format, introduced in Adobe InDesign CS4, for representing InDesign content. IDML is used in several InDesign and InCopy file types:

• IDML files (or packages) are ZIP archives, containing numerous XML files. The entire set of these files represent a complete InDesign document. The files in an archive are described thoroughly in Adobe InDesign CS4 IDML File Format Specification. IDML files are identified by the *.idml file extension.
• Snippets are IDML-based files that describe a subset of an InDesign document. They are not archives, but single XML files that contain IDML. The application UI, scripting facility, and plug-in API allow you to export snippets from InDesign. Most commonly, such a snippet represents a page item or group of page items. These type of snippets usually are identified by the *.inds file extension.
• ICML (InCopy Markup Language) files are a special type of snippet. An ICML file represent s a single InCopy story using IDML. ICML files use the *.icml file extension.
• InCopy assignment files are another type of IDML snippet. They are used to allow multiple writers to work on one InDesign document. Assignment files use the *.icma extension.
• There are other features that leverage IDML; for example, exporting preflight profiles produces an IDML-based file.