ILCD Format Tools Documentation


Table of Contents

Introduction
Prerequisites
Calling Ant
Results
Errors
XML Catalog
Validation
Validation
Schema Validation
ILCD Validation
ILCD Compliance
Migration from ELCD Format Version 1.0.1
Misc
Generating HTML from datasets
Checking dataset references
Appendix
XML Catalog

Introduction

The ILCD SDK package includes tools based on Apache Ant that are useful for several common and repetitive tasks such as validation of datasets or transformation to HTML. This document describes how to use them.

Prerequisites

In order to use these tools, you will need Java and Apache Ant installed on your system. If you don't already have it, see the Ant Howto document for instructions.

Calling Ant

In general, Ant is run from the command line. The basic usage pattern is

ant [options] [target [target2 [target3] ...]] [options]

A target is a set of operations that are carried out on a certain set of datasets. A list of possible target is given below.

Most of the time you will want to operate on a certain folder. All targets supplied with the SDK support the property source.dir that can be used to point to the folder that you want to work with. For passing the property to Ant, the -D option is used. Thus, an example call in order to validate datasets residing in the folder myFolder would look like this:

ant validate -Dsource.dir=myFolder

If source.dir is omitted, it defaults to the folder sample_data supplied with the SDK. Thus, calling

ant validate

will simply validate the datasets in sample_data.

Results

In general, a call to Ant can have two outcomes: success and failure. This is indicated by messages that will be written to the console after completing each run, namely BUILD SUCCESSFUL or BUILD FAILED, respectively. While the first one usually indicates that everything went well, the latter always means that there was an error during execution. If, for instance, validation errors occur when validating datasets, this will result in a failure being reported at the end of the operation.

Errors

Resolver errors

If a message saying Warning: XML resolver not found; external catalogs will be ignored is displayed, follow the instructions in the XML catalog section at the end of this document.

OutOfMemory errors

If an operation fails with an error message like java.lang.OutOfMemoryError: Java heap space, this means that more memory has to be allocated in order to successfully complete the operation. This can be achieved by setting the ANT_OPTS environment variable, for instance by issuing the command (on Windows systems)

set ANT_OPTS=-Xmx512M,

or on *nix systems

export ANT_OPTS=-Xmx512M (that would set the heap size to be 512MB).

XML Catalog

The SDK package ships with an XML catalog that can be used to resolve remote XML Schema components to a locally cached copy instead. This should work automatically out of the box, however, in some cases it may not. If you are experiencing the latter, please refer to the corresponding section at the end of this document.

Validation

Validation

Ant target: validate

For technical reasons, validation requires two passes: one to ensure the XML datasets conform to the ILCD XML Schema documents and another one (referred to as ILCD Validation) to check whether they meet certain criteria that cannot be modelled with XML Schema and thus require another checking approach (which is an XSL transformation).

NOTE: A dataset is only considered valid if it successfully passes BOTH validation tests.

This operation will run both tests sequentially (by calling the following two targets), the XML Schema validation being the first.

Note: The validation will only work if the datasets are wired correctly to the schemas, i.e. the (usually relative) references to the schemas inside the datasets can actually be resolved. If operating on datasets in a location different from the ILCD SDK root directory, the schemas folder has to be copied there for validation to work, or - which is discouraged - the references to the schemas have to be altered accordingly to point to the correct schema location.

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to validate.folder sample_data No

Schema Validation

Ant target: schemavalidate

Validate the given datasets against the ILCD XML Schema documents. This will be the first operation that is performed when calling the validate target. Any errors that are detected are reported to the console and the file schemavalidate.log and the build will fail in this case.

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to validate.folder sample_data No

Example: ant schemavalidate

ILCD Validation

Ant target: ilcdvalidate

Validate the datasets against the ILCD validation XSLT stylesheet. This will be performed after successful XML Schema validation when calling the validate target. Any errors that are detected are reported to the console and the file ilcdvalidate.log and the build will fail in this case.

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to validate.folder sample_data No

ILCD Compliance

Ant target: ilcdcompliance

Validate the datasets against the ILCD Compliance rules. Any errors that are detected are reported to the console and the file ilcdcompliance.log and the build will fail in this case.

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to validate.folder sample_data No

Migration from ELCD Format Version 1.0.1

Ant target: migrate_1.1

Migrate datasets from ELCD Format 1.0.1 syntax to ILCD 1.1 syntax. This will consider all the changes to the format. See the CHANGES document for a complete list. In addition, please note the following when migrating datasets:

  • Some values will have to be changed or even removed during migration. In this case a notice will be issued on the console.

  • Some elements will change to multi-language mode. As the migration stylesheet does not know which one to use, it will default to en. This can be overridden by adding -DtargetLanguage=yourLang to the command line when using the Ant-based migration or by passing the targetLanguage parameter to the XSLT stylesheet when performing the transformation.

  • If multiple telephone and/or fax numbers have been specified inside a contact dataset, only the first entry of each will be transferred to the 1.1 instance. The migration stylesheet will issue a warning for each entry not transferred.

  • ComplianceValues (previously consistencyAndConformityValues): all values of "Sufficiently conform" will be changed to "Not compliant". The migration stylesheet will issue a warning for each of those.

  • References to the 1.0.1 version of the ELCD format will be substituted by a reference to the ILCD Format 1.1. The same applies for references to the ELCD Conformity System (replaced by references to ILCD Compliance System). NOTE: The source datasets "ILCD Format" and "ILCD Compliance" that are residing in the samples folder of this package (as well as any linked datasets and/or external documents) will be copied to the target folder and wired accordingly to the migrated datasets. While any references to "ELCD format 1.0.1" etc. source dataset files will be replaced , the dataset files will have to be removed manually .

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to generate HTML from.folder sample_data No
target.dir The folder the result will be written to.folder migrated_1.1 in current directoryNo
overwrite.existing If true, the output directory will be overwritten in case it already exists. false No
replace If true, the folder specified as source.dir will be overwritten with the result. false No
keepold If true, keep a copy of the source documents as folder previous_1.0.1 (applies only when replace is set to true). true No
targetLanguage Set the target language for content whose parent element changed to be multilanguage. en No

Example:

To migrate ELCD 1.0.1 dasets in the folder D:\data\ELCD_Data, you would - assuming the current folder is the one with the ILCD SDK - first issue the command

ant migrate_1.1 -Dsource.dir=D:\data\ELCD_Data .

This will result in a folder migrated_1.1 to be created that contains the migrated files. To check whether they are valid against the ILCD 1.1 Format definitions, you could now enter

ant validate -Dsource.dir=migrated_1.1 .

Misc

Generating HTML from datasets

Ant target: makehtml

Transform the XML datasets in the specified folder to an HTML representation. The references, if local, will be changed to point to the HTML equivalent (.xml filename extensions will be translated to .html, except on permanentDataSetURI element).

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to generate HTML from.folder sample_data No
target.dir The folder the result will be written to.folder html in current directoryNo

Checking dataset references

Ant target: checkreferences

Check the references in a set of datasets for whether they can be resolved to a valid dataset. This is useful for instance prior to releasing bundles of datasets for exchange to ensure there are no dead links.

Parameters:

OptionDescriptionDefaultRequired
source.dir The folder containing the datasets to generate HTML from.folder sample_data No
checkReferences If true, perform reference check on elements of type GlobalReferenceType. true No
checkPermanentDataSetURI If true, perform reference check on permanentDataSetURI element. false No
localOnly If true, do not try to check any references pointing to a remote location (i.e. those starting with http://), but only local ones. false No

Appendix

XML Catalog

The ILCD schemas use an external XML Schema document from W3C, xml.xsd, which resides on the Internet at http://www.w3.org/2005/08/xml.xsd. That means that for validation of instance documents, be it via Ant or your own XML editor, a network connection has to be established. To circumvent this, it is possible to instruct these tools to use a locally cached copy of xml.xsd instead.

This package ships with an XML catalog that will allow Ant or your favorite XML editor to use this locally cached copy. The catalog is located in the tools directory and it's called ILCD_catalog.xml.

For using this mechanism with Ant (e.g. validating XML instances using the supplied Ant buildfile) you can choose one out of the following two options:

- Set your local CLASSPATH environment variable to include resolver.jar (recommended).

Windows example: SET CLASSPATH=%CLASSPATH%;<ILCD-base-dir>\tools\ext\lib\resolver.jar

Mac, *nix example: export CLASSPATH=$CLASSPATH:<ILCD-base-dir>/tools/ext/lib/resolver.jar

- Pass the option "-lib tools/ext/lib/resolver.jar" to Ant every time when calling tasks that include schema validation.

If Ant can't find resolver.jar, it will issue a warning saying "Warning: catalogpath listing external catalogs will be ignored" and then try to establish a network connection. NOTICE THAT IF YOU'RE NEITHER USING THE XML CATALOG NOR HAVE A NETWORK CONNECTION ESTABLISHED, YOUR DOCUMENTS WILL NOT VALIDATE.

For using this catalog with your favorite XML editor, please refer to its documentation (in oXygen XML Editor, just open the settings, go to XML/XML Catalog and add ILCD_catalog.xml to the list).