CDXML Support

CDXML Support

This page describes ChemDraft 1.0.0's progressive, warning-backed CDXML import and export rather than promising universal compatibility.

CDXML is useful for exchanging drawings, but it is not ChemDraft's native document model. ChemDraft keeps its own validated document internally and translates at the boundary through its compatibility package. That design allows an editable native save to retain more information than the visible CDXML subset can express.

What ChemDraft writes

When you save a native .chemdraft document, ChemDraft writes a CDXML envelope containing two layers:

1. A visible CDXML representation of the supported drawing subset.
2. A ChemDraft-owned metadata payload embedded on the first page.

The metadata includes codec and document-schema versions, a SHA-256 hash for the native payload, a hash for the visible CDXML layer, and the compact encoded native document. This provides a lossless ChemDraft-to-ChemDraft path while still providing a visible representation for compatible readers.

File > Export… can also create a .cdxml file. In the Export dialog, choose CDXML, set the optional Creation program text if needed, choose a destination, and export. The dialog reports compatibility warnings returned by the conversion. For the other export choices, see Exporting.

The visible subset

The current writer produces visible CDXML for these native objects:

ChemDraft object	Visible CDXML form
Molecule	Fragment with atom and bond elements
Text	Text element
Plus sign	Text containing +
Simple reaction arrow and graphics	Graphic element
Bracket	Graphic representation
Page	Page element

The importer reads pages, fragments, atoms, bonds, text, simple graphics, and line graphics that represent reaction arrows. It can also resolve some crossing information into the native page-level crossing model. Object colors, ordinary line styles, and several standard arrowhead forms are handled where the representation is available.

This is a progressive subset. It is deliberately narrower than the full external format, and it has no claim of perfect geometry fidelity for arbitrary documents.

What happens to unsupported content

ChemDraft uses three honest outcomes:

Situation	Outcome
There is a supported native equivalent	Import it as an editable native object.
The format has no faithful equivalent for a native detail	Keep the native detail in the embedded payload when saving a native document and issue a compatibility warning for the visible layer.
An external object has no supported native equivalent	Preserve it as an unknown compatibility object where feasible and warn.

Examples that can produce warnings include aromatic or unknown bond-order approximation, bond display styles that cannot be represented, unsupported atom or molecule metadata, over/under crossing information that cannot be fully retained, partial reaction schemes, and mechanism annotations that remain payload-only. Curved artwork, richer bracket details, decorative arrow markers, complex graphics, images, unusual fonts, and proprietary style state deserve particular inspection after interchange.

For abbreviations, a native document retains the detailed information in its embedded payload. A visible-only CDXML import may expand a resolvable abbreviation into its carried atoms; unsupported, charged, or overly nested cases remain literal labels instead of being guessed. A warning tells you when that distinction matters.

External edits and conflict choice

The native envelope hashes the visible layer as it was saved. If someone edits that visible CDXML layer outside ChemDraft and then opens the file again, ChemDraft detects that the visible hash no longer matches. Rather than silently choosing a version, it offers a conflict choice:

• import the externally edited visible subset, or
• restore the embedded ChemDraft document.

The embedded document is a guarantee for the native round trip, not a claim that externally edited visible CDXML remains lossless. If you need both versions, preserve a copy before choosing.

Coordinates and pages

ChemDraft converts between CSS pixels and CDXML points using 96 CSS pixels per inch and 72 points per inch. It writes and reads point pairs in horizontal-then-vertical order and uses left, top, right, bottom order for bounding boxes. Page objects are imported and exported, but external documents with advanced page setup or graphics should be checked visually.

Practical workflow

1. Keep the working source as a .chemdraft file.
2. Use File > Export… and choose CDXML when a recipient needs CDXML.
3. Read any export warnings before sending the file.
4. When opening received CDXML, review the imported page and warnings before editing or re-exporting it.
5. If the file is an edited native envelope, make an informed choice at the visible-layer conflict prompt.

On macOS, ChemDraft may be offered as an alternate handler for CDXML. The Windows installer deliberately registers only .chemdraft, so open CDXML through File > Open… or an explicit Open With selection. See macOS and Windows Differences for broader desktop differences.

See also

• File Formats and Compatibility
• Exporting
• Chemistry Guarantees
• Saving Sessions and Recovery