2 Container format

WARNING: The container formats and processing features differ between the XProc 1.0 and the 3.0 version!

Description of the container format for XProc 1.0
Description of the container format for XProc 3.0

2.1 XProc 1.0 container format

The schema for the XProc 1.0 container format can be found in xsd/container.xsd.

The root of an XProc 1.0 XML container document is an <xtlcon:document-container> element. The prefix xtlcon: must be bound to the namespace http://www.xtpxlib.nl/ns/container (xmlns:xtlcon="http://www.xtpxlib.nl/ns/container").

<xtlcon:document-container timestamp = xs:dateTime
                           href-source-zip? = xs:string
                           href-target-zip? = xs:string
                           href-target-zip-result? = xs:string
                           href-target-zip-tmpdir? = xs:string
                           href-source-path? = xs:string
                           href-target-path? = xs:string
                           href-target-result-path? = xs:string
                           (any)? >
  ( <xtlcon:document> |
    <xtlcon:external-document> |
    <(any)> )*
</xtlcon:document-container>

Attribute	#	Type	Description
`timestamp`	1	`xs:dateTime`	The timestamp when this container was initially created/generated.
`href-source-zip`	?	`xs:string`	When the container was read from a zip file (using `xtlcon:zip-to-container`), this attribute holds the href of this zip file.
`href-target-zip`	?	`xs:string`	Holds the name of the zip file for writing the container to (using `xtlcon:container-to-zip`).
`href-target-zip-result`	?	`xs:string`	After the container is written to a zip file using `xtlcon:container-to-zip`, this attribute will hold the full canonical filename of the zip file.
`href-target-zip-tmpdir`	?	`xs:string`	After the container is written to a zip file using `xtlcon:container-to-zip`, this attribute will hold the full canonical name of the temporary directory used for this process (probably not very useful).
`href-source-path`	?	`xs:string`	When the container was read from a directory (using `xtlcon:directory-to-container`), this attribute holds the href of this directory.
`href-target-path`	?	`xs:string`	Holds the name of the directory for writing the container to (using `xtlcon:container-to-disk`).
`href-target-result-path`	?	`xs:string`	After the container is written to a directory file using `xtlcon:container-to-disk`, this attribute will hold the full canonical name of the directory.
`(any)`	?		Any other attributes are allowed, so additional information can be added for use during processing.

Child element	#	Description
`xtlcon:document`	*	A document inside the container structure. See 2.1.1 Internal documents.
`xtlcon:external-document`	*	An external document, referenced from the container structure. See 2.1.2 External documents.
`(any)`	*	Any other elements are allowed, so additional information can be added for use during processing.

2.1.1 Internal documents

An internal document is a document whose contents is inside the container document. This will in most cases be XML documents, but text is also possible. It must be surrounded by an <xtlcon:document> element:

<xtlcon:document href-source? = xs:string
                 href-source-result? = xs:string
                 href-target? = xs:string
                 href-target-result? = xs:string
                 mime-type? = xs:string
                 (any)? >
  <(any)>
</xtlcon:document>

Attribute	#	Type	Description
`href-source`	?	`xs:string`	href of the source for this document. When this document comes from a zip file, it holds the href of the file in the zip.
`href-source-result`	?	`xs:string`	After processing holds the full canonical name of the source file.
`href-target`	?	`xs:string`	href of the target for this document.
`href-target-result`	?	`xs:string`	After processing holds the full canonical name of the target file.
`mime-type`	?	`xs:string`	Some specific values for this attribute trigger special conversions on output. See 2.1.3 Document MIME type values.
`(any)`	?		Any other attributes are allowed, so additional information can be added for use during processing.

Child element	#	Description
`(any)`	1	Root element + contents of the document.

2.1.2 External documents

An external document is a document that is only referenced from the container. Usually binary files but anything goes. The referencing is done using an <xtlcon:external-document> element:

<xtlcon:external-document (attributes-from-internal-document)?
                          href-source-zip? = xs:string
                          href-source-zip-result? = xs:string
                          not-in-global-source-zip? = xs:boolean >
  <(any)>
</xtlcon:external-document>

All attributes of an internal document plus the following:

Attribute	#	Type	Description
`(attributes-from-internal-document)`	?		See internal documents.
`href-source-zip`	?	`xs:string`	Reference to the source zip file for this document. If present overrides `/*/@href-source-zip`
`href-source-zip-result`	?	`xs:string`	After processing holds the full canonical name of the source zip file.
`not-in-global-source-zip`	?	`xs:boolean`	Default: `false` When set to `true`, the global zip file `/*/@href-source-zip` is not used. This is necessary to allow references to external files that, when a global zip file is used, come from elsewhere.

Child element	#	Description
`(any)`	1	Any other elements are allowed, so additional information can be added for use during processing.

2.1.3 Document MIME type values

The xtlcon:document/@mime-type attribute (see Internal documents) can trigger some special treatment of the contents of the element:

mime-type="application/pdf" and the root element is <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">

The document is assumed to be an XSL-FO document and the FOP XSL-FO processor is called to create a PDF document. The pipelines (both xtlcon:container-to-disk and xtlcon:container-to-zip) allow you to specify an FOP configuration file.

mime-type="text/plain"

The contents of the <xtlcon:document> element will be stringified and stored as text. The schema requires some root element to be present as child of <xtlcon:document> but this is ignored:

<xtlcon:documnent mime-type="text/plain" …>
<dummy-root>Text to be stored
another line…</dummy-root>
</xtlcon:document>

2.2 XProc 3.0 container format

The container format for XProc 3.0 allows documents in XML, HTML, text and JSON format. It can also process JSON as XML.

The schema for the XProc 3.0 container format can be found in xsd/container-xpl3.xsd.

The root of an XProc 3.0 XML container document is an <xtlcon:document-container> element. The prefix xtlcon: must be bound to the namespace http://www.xtpxlib.nl/ns/container (xmlns:xtlcon="http://www.xtpxlib.nl/ns/container").

When you get the container back after processing by one of the pipelines, you'll find most href related attributes (attributes that start with href-) copied to an attribute with the same name plus an underscore in front. The values of these added attributes will be the fully expanded and canonicalized references.

For instance: When the container has an attribute href-target-zip="../out.zip", after processing you'll find an attribute like _href-target-zip="file:///ful/path/to/out.zip" on the result.

<xtlcon:document-container timestamp = xs:dateTime
                           href-source-path? = xs:string
                           href-target-path? = xs:string
                           href-source-zip? = xs:string
                           href-target-zip? = xs:string
                           (any)? >
  ( <xtlcon:document> |
    <xtlcon:external-document> |
    <(any)> )*
</xtlcon:document-container>

Attribute	#	Type	Description
`timestamp`	1	`xs:dateTime`	The timestamp when this container was initially created/generated.
`href-source-path`	?	`xs:string`	When the container was read from a directory (using `xtlcon:directory-to-container`), this attribute holds the href of this directory.
`href-target-path`	?	`xs:string`	Contains the path for the directory when writing the container to (using `xtlcon:container-to-disk`).
`href-source-zip`	?	`xs:string`	When the container was read from a zip file (using `xtlcon:zip-to-container`), this attribute holds the href of this zip file.
`href-target-zip`	?	`xs:string`	Holds the path for the zip file when zipping the container's contents (using `xtlcon:container-to-zip`).
`(any)`	?		Any other attributes are allowed, so additional processing information can be added.

Child element	#	Description
`xtlcon:document`	*	A document inside the container structure. See 2.2.1 Internal documents.
`xtlcon:external-document`	*	An external document, referenced from the container structure. See 2.2.2 External documents.
`(any)`	*	Any other elements are allowed (in a different namespace), so additional processing information can be added.

2.2.1 Internal documents

An internal document is a document whose contents is inside the container document. It must be surrounded by an <xtlcon:document> element.

<xtlcon:document href-source? = xs:string
                 href-target? = xs:string
                 href-source-zip? = xs:string
                 content-type? = xs:string
                 serialization? = xs:string
                 (any)? >
  <(any)>
</xtlcon:document>

Attribute	#	Type	Description
`href-source`	?	`xs:string`	href of the source for this document. Will be filled by `xtlcon:directory-to-container` and the `xtlcon:zip-to-container` pipelines. When this document comes from disk, it holds the the relative filename against the value of the container's `/*/@href-source-path`. When this document comes from a zip file, it holds the (relative) href of the file in the zip.
`href-target`	?	`xs:string`	href of the target location for this document. Used by the `xtlcon:container-to-disk` and `xtlcon:container-to-zip` pipelines. When writing to disk, a relative filename is made absolute against the container's `/*/@href-target-path`. When writing to a zip, it must be a relative filename. This will become the path of the file in the zip file.
`href-source-zip`	?	`xs:string`	If present, overrides the value of the container's `/*/@href-source-zip`
`content-type`	?	`xs:string`	Content (MIME) type of the document. Will be filled by `xtlcon:directory-to-container` and the `xtlcon:zip-to-container` pipelines. If not present when writing a container, `text/xml` is assumed for internal documents
`serialization`	?	`xs:string`	Serialization settings for this document, expressed as a JSON map. To allow the usual double quoted attribute values (`"…"`), all single quotes will be converted to double quotes before JSON parsing is done. For instance: `serialization="{'indent': true}"`
`(any)`	?		Any other attributes are allowed, so additional processing information can be added.

Child element	#	Description
`(any)`	1	Document contents (For text and JSON does not need to be XML).

2.2.2 External documents

An external document is a document that is only referenced from the container. Usually binary files but anything goes. The referencing is done using an <xtlcon:external-document> element:

<xtlcon:external-document href-source? = xs:string
                          href-target? = xs:string
                          href-source-zip? = xs:string
                          not-in-zip? = xs:boolean
                          (any)? >
  <(any)>*
</xtlcon:external-document>

Attribute	#	Type	Description
`href-source`	?	`xs:string`	href of the source for this document. Will be filled by `xtlcon:directory-to-container` and the `xtlcon:zip-to-container` pipelines. When this document comes from disk, it holds the the relative filename against the value of the container's `/*/@href-source-path`. When this document comes from a zip file, it holds the (relative) href of the file in the zip.
`href-target`	?	`xs:string`	href of the target location for this document. Used by the `xtlcon:container-to-disk` and `xtlcon:container-to-zip` pipelines. When writing to disk, a relative filename is made absolute against the container's `/*/@href-target-path`. When writing to a zip, it must be a relative filename. This will become the path of the file in the zip file.
`href-source-zip`	?	`xs:string`	If present, overrides the value of the container's `/*/@href-source-zip`
`not-in-zip`	?	`xs:boolean`	Forces this document to load from disk, even when a zip file reference is specified.
`(any)`	?		Default: `false` Any other attributes are allowed, so additional processing information can be added.

Child element	#	Description
`(any)`	*	Any contents allowed for additional processing purposes.