Carbon Editor XML Format

Owned by Cyril Doussin
Last updated: Dec 12, 2022



On This Page

See also: 



Overview

Carbon Editor supports XML (Extensible Markup Language) as an import and export format.

XML created for use in Carbon Editor must adhere to certain formatting requirements.

Example Carbon Editor XML, formatting requirement explanations, and detailed information on individual XML elements are below.


Example Carbon Editor XML

This example contains XML that is suitable for import to Carbon Editor.

There are some differences between XML exported from Carbon Editor, and XML that is suitable for being imported in to Carbon Editor. For more information, see Import XML Format vs Export XML Format. 

Example XML
<?xml version="1.0" encoding="utf-8"?>
<page title="My new page">
	<section name="Introduction" type="introduction">
		<text field_type="title">
            <value format="html"><![CDATA[My new page]]></value>
        </text>
		<text field_type="paragraph">
            <value format="html"><![CDATA[This is an introduction paragraph.]]></value>
        </text>
	</section>
	<section name="Page body" type="body-section">
		<text field_type="heading">
            <value format="html"><![CDATA[This is a heading]]></value>
        </text>
		<text field_type="paragraph">
            <value format="html"><![CDATA[
			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
		]]></value>
        </text>
        <image field_type="logo">
            <value type="file" default="true"><![CDATA[./image1.png]]></value>
        </image>
        <formula field_type="relativity-equation">
            <value format="tex"><![CDATA[e = mc^2]]></value>
        </formula>
	</section>
</page>


Individual XML Elements

Carbon Editor XML format uses a one-file-per-page system.

Each Carbon Editor Page contains one or more Page Section(s).

In turn, Page Sections contain one or more Field(s).

Fields contain the page content itself.


 Pages

Pages

Tag: page

Mandatory attribute(s):

  • title - the descriptive title of the page. Maximum length: 255 characters

Optional attribute(s):

  • embedding_id - an identifier that allows the page to be embedded within other documents. Can be set as a custom value, or will otherwise be automatically generated based on the Page's title.


Example Page Element
<page title="Example Page Title" embedding_id="my-embedding-id">
...
</page>
 Page Sections

Page Sections

Tag: section 

Mandatory attribute(s):

  • name - the descriptive name of the section
  • type - a slug that refers to the Page Section Type, defined in the Space Administration.
    • If a Page Section Type referenced within imported XML has not yet been defined within the Space Administration, a new Page Section Type will be created based on the slug. For more information, see Import XML Format vs Export XML Format.

Optional attribute(s):

  • id - a UUID4 identifier generated upon export. For more information, see Import XML Format vs Export XML Format.
  • embedding_id - an identifier that allows the Section to be embedded within other documents. Can be set as a custom value, or will otherwise be automatically generated based on the Section's title.


Example Page Section Element
<section name="Example Page Section Name" type="example-page-section-slug" embedding_id="my-embedding-id">
...
</section>
 Fields

Fields

Fields are created based on Field Types. Field Types are defined in the Space Administration.

All Field Types must be based on one of the following pre-defined Content Types:

  • Text
  • Image
  • Table
  • List
  • Formula
  • Embed

If a Field Type referenced within imported XML has not yet been defined within the Space Administration, a new Field Type will be created based on the slug. For more information, see Import XML Format vs Export XML Format.


Like Pages and Page Sections, fields also use embedding_id and id.


The XML element Content Types are listed below:


 Text

Text

Tag: text

Mandatory Attribute(s): field_type

Optional Attribute(s):

  • embedding_id
  • id

Child Element:

  • Tag: value
  • Attribute: format
    • Possible Value(s): html


Example Text Field Element
<text field_type="example-field-type" embedding_id="my-embedding-id">
	<value format="html"><![CDATA[Example text field content. Lorem ipsum dolor sit amet.]]></value>
</text>
 Links

It is also possible to include cross page links in imported text, list and table fields. These use the linking ids of documents and pages to automatically determine the correct document or page to link against. This works through an identical mechanism as Embedded Content

Links are described using an anchor tag with a custom protocol in the html content and an additional links element which describes the targets of these links. An example of a text field containing a link is included below, this example will also work for lists and tables.

<text field_type="example-field-type" embedding_id="example-embedding-id">
	<value format="html"><![CDATA[Example text in this field with a <a href="link://my-link-id">LINK</a>]]></value>
	<links>
		<link id="my-link-id">
			<document format="embedding-id">document-embedding-id</document>
			<page format="embedding-id">page-embedding-id</document>
		</link>
	</links>
</text>
 Image

Image

Tag: image

Mandatory Attribute(s): field_type

Optional Attribute(s):

  • embedding_id
  • id

Child Element:

  • Tag: value
  • Attribute: type
    • Possible Value: file


Example Image Field Element
<image field_type="example-field-type" embedding_id="my-embedding-id">
	<value type="file" default="true"><![CDATA[./image1.png]]></value>
</image>
 Table

Table

Tag: table

Mandatory Attribute(s): field_type

Optional Attribute(s):

  • embedding_id
  • id

Child Element:

  • Tag: value
  • Attribute: format
    • Possible Value: html


Example Table Field Element
<table field_type="example-field-type" embedding_id="my-embedding-id">
	<value format="html"><![CDATA[
		<table>
  			<tr>
    			<td>...</td>
  			</tr>
			<tr>
    			<td>...</td>
  			</tr>
	</table>]]>
	</value>
</table>
 List

List

Tag: list

Mandatory Attribute(s):

  • field_type
  • list_type
    • Possible Value(s):
      • ordered
      • unordered

Optional Attribute(s):

  • embedding_id
  • id

Child Element:

  • Tag: value
  • Attribute: format
    • Possible Value(s): html


Example List Field Element
<list field_type="example-field-type" list_type="ordered" embedding_id="my-embedding-id">
	<value format="html"><![CDATA[
<ol>
	<li>1</li>
	<li>2</li>
</ol>]]></value>
</list>
 Formula

Formula

Tag: formula

Mandatory Attribute(s): field_type

Child Element:

  • Tag: value
  • Attribute: format
    • Possible Value(s): tex


Optional Attribute(s):


  • embedding_id
  • id


Example Formula Field Element
<formula field_type="example-field-type" embedding_id="my-embedding-id">
	<value format="tex"><![CDATA[e = mc^2]]></value>
</formula>


Import XML Format vs Export XML Format

Prior to working with XML in Carbon Editor, it is important to understand the differences between the XML that is exported from Carbon Editor, and XML which is suitable for import to Carbon Editor.

id Attributes

One significant difference between exported and importable XML is the use of Universally Unique Identifiers (UUIDs).

XML exported from Carbon Editor includes id attributes for Page, Page Section, and Field elements. The values contained within these id attributes are UUID4 identifiers.

Upon import, the id attribute is only respected for page elements in which case the entire contents of the existing page with the matching id value will be updated, instead of a new page being created. The id attribute is ignored for all other XML elements. 

Slug Handling

The value of field_type and section attributes within Carbon Editor XML format are slugs.

Field Type and Page Section Type slugs can only contain lower-case characters and hyphens. Slugs cannot contain accented characters or unicode characters

When exporting XML from Carbon Editor, slugs will be automatically created based on the name of the Field Type or Page Section Type.

When importing XML to Carbon Editor:

  1. If the Field Type's slug matches an existing Field Type/Page Section Type, the existing Field Type/Page Section Type will be used,
    or, 
  2. If a new slug is used, a new Field Type/Page Section Type will be created. This Field Type/Page Section Type's name will be automatically generated, based on it's slug.
    When a Field Type/Page Section Type's name is automatically generated, hyphens within the slug are converted to spaces, and each word is capitalised.


Generic XML Schema Definition (XSD)


Content Editor XML Format Schema Deifnition
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="page">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="variations" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="section" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
            <xs:attribute type="xs:string" name="embedding_id" use="optional"/>
            <xs:attribute type="xs:string" name="title" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:simpleType name="linkFormat">
        <xs:restriction base="xs:string">
            <xs:enumeration value="embedding-id"/>
            <xs:enumeration value="uuid"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:element name="link">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="document">
                    <xs:complexType>
                        <xs:simpleContent>
                            <xs:extension base="xs:string">
                                <xs:attribute type="linkFormat" name="format"/>
                            </xs:extension>
                        </xs:simpleContent>
                    </xs:complexType>
                </xs:element>
                <xs:element name="page">
                    <xs:complexType>
                        <xs:simpleContent>
                            <xs:extension base="xs:string">
                                <xs:attribute type="linkFormat" name="format"/>
                            </xs:extension>
                        </xs:simpleContent>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="value">
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base="xs:string">
                    <xs:attribute type="xs:string" name="format" use="optional"/>
                    <xs:attribute type="xs:string" name="type" use="optional"/>
                    <xs:attribute type="xs:string" name="default" use="optional"/>
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="links">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="link" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="variation">
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base="xs:string">
                    <xs:attribute type="xs:string" name="slug"/>
                    <xs:attribute type="xs:string" name="visible"/>
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="variations">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="variation" maxOccurs="unbounded" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="text">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="value"/>
                <xs:element ref="links" minOccurs="0"/>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
            <xs:attribute type="xs:string" name="field_type" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="list">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="value"/>
                <xs:element ref="links" minOccurs="0"/>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
            <xs:attribute type="xs:string" name="field_type" use="optional"/>
            <xs:attribute type="xs:string" name="list_type" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="table">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="value"/>
                <xs:element ref="links" minOccurs="0"/>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
            <xs:attribute type="xs:string" name="field_type" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="image">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="value" maxOccurs="unbounded" minOccurs="0"/>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id" use="optional"/>
            <xs:attribute type="xs:string" name="field_type" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="formula">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="value"/>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id"/>
            <xs:attribute type="xs:string" name="field_type"/>
        </xs:complexType>
    </xs:element>
    <xs:group name="fields">
        <xs:choice>
            <xs:element ref="text"/>
            <xs:element ref="list"/>
            <xs:element ref="table"/>
            <xs:element ref="image"/>
            <xs:element ref="formula"/>
        </xs:choice>
    </xs:group>
    <xs:element name="section">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="variations" maxOccurs="1" minOccurs="0"/>
                <xs:group ref="fields" maxOccurs="unbounded" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute type="xs:string" name="id"/>
            <xs:attribute type="xs:string" name="name"/>
            <xs:attribute type="xs:string" name="type"/>
        </xs:complexType>
    </xs:element>
</xs:schema>


Unless otherwise indicated in the Overview page of this WIKI the information contained within this space is Classified according to the /wiki/spaces/ISMS/pages/739344530 as

INTERNAL