Extensible 3D (X3D) encodings
Part 1: Extensible Markup Language (XML) encoding

4 Concepts

--- X3D separator bar ---

cube4.1 Introduction and table of contents

4.1.1 Introduction

This clause describes key concepts in this part of ISO/IEC 19776. This includes how the X3D constructs defined in [I19775-1] are encoded using the Extensible Markup Language (XML) (see [XML]).

4.1.2 Topics

Table 4.1 lists the topics for this clause.

Table 4.1 — Topics in this clause

4.1 Introduction and table of contents
  4.1.1 Introduction
  4.1.2 Topics
  4.1.3 Conventions used TODO add, see Mantis 1125
4.2 Overview
  4.2.1 Introduction
  4.2.2 The structure of an X3D file
  4.2.3 Header
4.3 XML file syntax
  4.3.1 XML encoding
  4.3.2 Statements
  4.3.3 Node and Field statement syntax
  4.3.4 DEF and USE attribute syntax
  4.3.5 containerField attribute syntax
  4.3.6 class attribute syntax
  4.3.7 Prototype and field declaration syntax
  4.3.8 IS/connect statement syntax
  4.3.9 ExternProtoDeclare statement syntax
  4.3.10 ProtoInstance and fieldValue statement syntax
  4.3.11 ROUTE statement syntax
  4.3.12 IMPORT/EXPORT statement syntax
  4.3.13 Encapsulating Script node code
4.4 X3D files and the World Wide Web
  4.4.1 File extension and MIME type
  4.4.2 X3D XML Document Type Definition (DTD)
  4.4.3 X3D XML Schema
  4.4.4 X3D XML Schematron

cube4.2 Overview

4.2.1 Introduction

The Extensible Markup Language (XML) (see [XML]) is used for a self-validating X3D encoding of Extensible 3D (X3D) Graphics. This X3D encoding provides a Web-compatible format that maximizes interoperability with other Web languages. XML supports structuring data, is similar to HTML, is readable by systems and humans, is verbose for clarity, represents a modular family of technologies, and is fundamentally interoperable with Web technologies. See [XML10] for more background information.

There is a fundamental and complete correspondence between the elements of the abstract X3D scene graph and constructs in the XML encoding. The X3D XML Encoding has full expressive power for all scene constructs defined in the X3D Architecture [I19775-1]. This section describes the design patterns that govern the correspondence.

4.2.2 The structure of an X3D file

An X3D file is structured as defined in the X3D Architecture [I19775-1].

4.2.3 Header

The header is a single line of UTF-8 text identifying the file as an XML file, followed by the XML declaration that identifies the validating XML DTD, followed by X3D tags that identify the validating XML Schema, X3D profile, and (optionally) the necessary additional components of the file.

For easy identification of X3D files, every X3D file shall begin with an XML file declaration (see [XML]).

<?xml version="1.0" encoding="UTF-8"?>

The identifier "UTF-8" indicates a clear text character encoding that allows for international characters to be displayed in X3D using the UTF-8 encoding defined in [ISO/IEC 10646-1].

The XML header is immediately followed by an XML DOCTYPE statement which provides both PUBLIC and SYSTEM literals for the X3D XML Document Type Definition (DTD) (see [XML]).

The X3D DOCTYPE declaration is as follows:

EXAMPLE 1 XML Document Type Definition (DTD or DOCTYPE) validation syntax for an X3D model.

<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 4.0//EN"   "https://www.web3d.org/specifications/x3d-4.0.dtd">
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.3//EN"   "http://www.web3d.org/specifications/x3d-3.3.dtd">

In addition As an alternative to DTD validation, XML Schema validation can be performed through identification of XML Schema and X3D namespaces within the root X3D tags as defined in [XML_SCHEMA] [XML_NAMESPACES] .

EXAMPLE 2 1 XML Schema validation syntax for an X3D model.

<X3D profile='Immersive' version='4.0'
<X3D profile='Immersive' version='3.3'

A DOCTYPE or schema declaration is optional. The reference DTD and location is specified in this document. To allow for extensible tag sets (supersets of the base specification), authors may point to a document definition other than the ones listed in this specification. However, the alternate definition shall specify an equivalent document to the base X3D DTD/Schema (i.e., the tag instances shall look exactly the same regardless of the source DTD schema). Authors shall use the X3D DOCTYPE and/or X3D Schema extension mechanisms to add validation capability for new nodes and fields.

Next comes the required X3D document root tag that specifies version and profile information with optional schema validation. Within the X3D document root tag is the optional header section, and the required scene body.

EXAMPLE 3 2 XML syntax for a complete X3D model.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 4.0//EN"   "https://www.web3d.org/specifications/x3d-4.0.dtd">

<X3D version='4.0' version='3.3' profile='Immersive'>
    <component name='Geospatial' level='1'/>
    <component name='NURBS' level='2'/>
    <meta name='description' content='X3D scene header and prototype syntax examples. '/>
    <meta name='title' content='X3dHeaderPrototypeSyntaxExamples.x3d'/>
    <meta name='identifier'
    <!-- Scene graph nodes are added here -->

This example header indicates that the content is XML encoded, matches X3D version 4.0, 3.3, follows the Immersive Profile, and explicitly lists additional expected components. The X3D header may also contain further semantic information, using meta tags for name='metadataTerm' and content='value' pairs. Note that the third meta tag should not break in the middle of the string.

4.3 XML file syntax

4.3.1 XML encoding

This clause describes the syntax of XML-encoded, human-readable X3D files. The syntax of X3D in terms of the XML encoding are presented in this part of ISO/IEC 19776. The semantics of X3D are as defined in [I19775-1]. Rules for parsing and handling XML-encoded documents are defined in [XML].

Two formal grammar descriptions of the XML syntax for X3D may be found in Annex A X3D XML Document Type Definition (DTD) and Annex B X3D XML Schema. These grammars are directly implementable by XML parsers.

In the XML encoding, the character sequences <!-- and --> delimit a comment.

EXAMPLE 4 XML comment syntax.

<!-- This is an X3D comment. -->

The only exceptions to this description of XML comments are within XML CDATA sections, which are ignored during XML parsing and typically only used for embedded script code. Comment exceptions also occur within double-quoted SFString and MFString fields, where the comment characters are escaped (using &lt; for < and &gt; for >) and are defined to be part of the string.

Attribute values may be delimited by paired single-quote (') or double-quote (") characters. Neither authors nor parsers can guarantee which type types of paired delimiting characters might be encountered when processing an XML file, is encountered since XML processors are allowed to independently choose either form. These rules are described in  [XML] and [XML_INFOSET] . which take precedence over all rules in this clause.

XML elements (e.g., (i.e., X3D nodes) may not appear within attribute values.

Space characters, Spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of XML attribute values. Separator characters are collectively termed whitespace. Commas are not ignorable whitespace when mixed between XML elements or element and attribute values.

Within X3D attribute values, the rules are slightly different. Commas, spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of XML attribute values. Separator characters and comments are collectively termed whitespace.

Field, event, PROTO, EXTERNPROTO, and node names shall not contain control characters (0x0-0x1f, 0x7f), space (0x20), double or single quotes (0x22: ", 0x27: '), sharp (0x23: #), comma (0x2c: ,), period (0x2e: .), brackets (0x5b, 0x5d: []), backslash (0x5c: \) or braces (0x7b, 0x7d: {}). Further, their first character shall not be a digit (0x30-0x39), plus (0x2b: +), or minus (0x2d: -) character. Otherwise, names may contain any ISO 10646 character encoded using UTF-8. X3D is case-sensitive; "Sphere" is different from "sphere" and "BEGIN" is different from "begin."

In order to maintain interoperable conversion capabilities translatability between the various file encodings and programming-language bindings different X3D encodings of X3D scenes, the following reserved keywords shall not be used for field, event, Protytype or node names:

4.3.2 Statements

After the required XML header and <X3D> document-root tag, an X3D file may contain any combination of the following:

  1. A single optional head element which can contain component, unit, and metadata information (as described 4.3.1 XML encoding); then
  2. A single required Scene element, which serves as a root node and contains one or more of the scene graph elements specified in items c. through g. (also see 4.4.1 Root nodes in Part 1 of ISO/IEC  19775);
  3. Any number of ProtoDeclare or ExternProtoDeclare statements (see 4.8 Prototype semantics in Part 1 of ISO/IEC 19775);
  4. Any number of node elements (see 4.3.3 Scene graph hierarchy in Part 1 of ISO/IEC 19775), either as DEF or USE nodes (see 4.6.2 DEF/USE semantics in Part 1 of ISO/IEC 19775);
    e. Any number of USE statements (see 4.6.2 DEF/USE semantics in Part 1 of ISO/IEC 19775);
  5. Any number of ROUTE statements (see 4.10.2 Route semantics in Part 1 of ISO/IEC 19775).
  6. Any number of IMPORT or EXPORT statements (see 4.4.5 IMPORT/EXPORT semantics in Part 1 of ISO/IEC 19775).

4.3.3 Node and field statement syntax

X3D nodes are expressed as XML elements (i.e., tagged names).

Simple non-node X3D fields are expressed as XML attributes in the form of name="value" pairs.

Nodes which serve as fields to other X3D nodes are expressed as contained XML elements, i.e. additional tagged names. Each includes an implicit (default) or explicitly defined containerField value.

A node statement consists of the type-name for the node element followed by the allowed simple-field attributes. A node instance can be given a label using the attribute DEF followed by an equals sign and the quoted name of the node.

Each tag begins and ends with angle brackets < and >, respectively. A node's body is enclosed by a pair of matching open and closing tags, where a closing tag has a slash / prepended to the element name.

EXAMPLE 1 The following XML declarations illustrate illustrates the use of node and field syntax:

<Group DEF='ExampleChildElement'>
      <Material diffuseColor='0.6 0.4 0.2'/>

Alternatively, if no further elements are contained as child nodes, a singleton single tag may omit the closing element tag by ending the single element with /> characters.

EXAMPLE 2 A pair of XML singleton elements.

<Viewpoint DEF='ExampleSingleElement'
           description='Hello syntax'/>
<NavigationInfo type='"EXAMINE" "ANY"'/>

A node element contains zero or more field attributes, as appropriate for each node type. When nested inside a ProtoDeclare ProtoBody, a node's content can optionally begin with a single IS statement, which in turn contains one or more connect statements. A node then contains zero or more child nodes, ROUTE statements, ProtoDeclare statements or ExternProtoDeclare statements. These contained nodes and statements are allowed as appropriate for each node type, and can typically appear in any order.

Whitespace shall separate the name of the node and attribute="value" pairs, but is not required before or after the tags that enclose the node's body.

XML-based scene validation for proper parent-child relationships among nodes can be performed using using either the X3D XML Document Type Definition (DTD) or X3D Schema. The DTD and Schema also define default values for attribute fields, matching the abstract specification. See 6 Encoding of nodes for the specification of the XML encoding of each node type.

4.3.4 DEF and USE attribute syntax

A declared node with accompanying DEF identification can be copied by reference through a USE reference. Both DEF and USE node types shall be exactly the same.

A USE attribute indicates that a node is a reference copy of a DEF node with the same ID. DEF is assigned XML type ID, and USE is assigned XML type IDREF, respectively. The same name-construction conventions regarding legal character combinations apply.

Each DEF (ID) value in a scene shall be unique. Non-unique node DEF names in the body of ProtoDeclare definitions will cause validation errors when checked by the X3D DTD or Schema. This is a constraint from limitation of XML that requires each XML DTD and Schema to have a single namespace for ID types.

Nodes being reused via a USE="someDEFname" attribute can include no other attributes except containerField and class. Modified values for other fields in a USE node are not allowed, since explicit and implicit field definitions found in the original DEF node declaration take precedence and remain unchanged by the USE node.

EXAMPLE Reusing the ExampleChildElement node declared in Example 5 as a USE node: Continuing the previous example statements:

<Transform DEF='ExampleWithChildUSEnode' DEF='ExampleUSE'
           rotation='0 1 0 0.78'
           translation='0 2.5 0'>
   <Group USE='ExampleChildElement' containerField='children' USE='ExampleChildElement'/>

Nodes containing a USE="someName" attribute can include no other attributes except containerField and class. Default values for other fields shall be ignored since field definitions in the original DEF node declaration have precedence.

4.3.5 containerField attribute syntax

Each node type defines the names and types of the fields that each node of that type contains. In general, nearly all field-node relationships are unambiguous due to the well-defined parent-child node relationships in X3D.

In order to achieve a compact tagset in the XML encoding for X3D, the name of the parent node's field field typically containing each node is accounted for by the containerField attribute. For example, Sensor nodes are typically contained by the children field of Grouping nodes, hence each Sensor node has containerField='children' as the default value.

Ordinarily the containerField value can be omitted. The default containerField value for a given node may be overridden when necessary to indicate a different relationship with a given node's parent.

EXAMPLE Again reusing the ExampleChildElement node declared in Example 5 as a USE node, this time without including the default containerField='children' attribute:

  <Shape containerField='proxy'>
  <Group USE='ExampleChildElement'/>

4.3.6 class attribute syntax

The class attribute is reserved for use with XML Cascading Style Sheets (see [W3C-CSS-Snapshot]). [CSS]).

TODO discuss purpose of cascading stylesheets, X3D Architecture Annex L HTML Guidelines

4.3.7 Prototype and field declaration syntax

A Prototype declaration consists of the ProtoDeclare keyword, followed in order by the prototype name attribute, optional prototype interface field declarations contained within a ProtoInterface, and required prototype body definition contained within a ProtoBody.

Prototype field statements consist of the field keyword, followed in any order by the attribute values for field name, field type and field accessType (having value inputOnly, outputOnly, initializeOnly or inputOutput).

EXAMPLE 1 A prototype declaration example (without and with field declarations, respectively) follow:

<ProtoDeclare name='NewWorldInfoNode'>
    <WorldInfo DEF='ExamplePrototypeBody' title='Hello New World Intro'/>
<ProtoDeclare name='EmissiveMaterial'>
    <field name='onlyColor'
    <!-- Override default diffuseColor value 0.8 0.8 0.8 -->
    <Material diffuseColor='0 0 0'>
      <!-- Connect emissiveColor field of current node to onlyColor field of parent ProtoDeclare. -->
        <connect nodeField='emissiveColor' protoField='onlyColor'/>

A field statement also contains the default value of the field when the accessType is either initializeOnly or inputOutput. Simple values are contained in the value attribute (e.g., value='true'). If the default value of an SFString or MFString field is empty, the default value may be omitted. Node (or node array) values are contained as child nodes within the field declaration.

EXAMPLE 2 The <Group DEF='DefaultNodeValue'/> below in EXAMPLE 10 provides a default initialization for the children field in the ProtoDeclare body.

EXAMPLE 10  X3D prototype definition using XML ProtoDeclare syntax.

<ProtoDeclare name='ShiftGroupUp2m'>
    <field name='children'
      <Group DEF='DefaultNodeValue' bboxSize='2 2 2'/>
    <Transform translation='0 2 0'>
          <connect nodeField='children'

The same field name may be used independently by multiple node prototypes.

See 5 Encoding of fields for the specification of the XML encoding of each X3D field type.

4.3.8 IS/connect statement syntax

The body of a node statement that is inside a prototype definition may optionally contain a single <IS> statement, which in turn contains one or more <connect> statements. Each <connect> statement consists of a nodeField attribute with the name of a field from the parent node's interface, followed by a protoField attribute with the name of a field from the ancestor ProtoDeclare. When defined in a scene, any contained <IS> element shall be the first child element within a node definition, with two exceptions. Script, ComposedShader, PackagedShader, and ShaderProgram nodes include field definitions before IS/connect. ProtoInstance definitions include fieldValue initializations before IS/connect.

The type and accessType of each field shall match exactly. These nodeField and protoField names may be overloaded; i.e., these two names may be identical since each is part of a different namespace.

See the Prototype declaration specified in 4.3.7 Prototype and field declaration syntax for example use of IS/connect constructs.

ISO/IEC 19775-1 (see 4.4.4 Prototype semantics) specifies [I19775-1] for details on external prototype statements.

TODO: provide an example.

4.3.9 ExternProtoDeclare statement syntax

An ExternProtoDeclare statement consists of the ExternProtoDeclare element, a name attribute for the referenced Prototype, and a url of one or more addresses referring to the scene defining this Prototype. Zero or more contained field definitions then follow to provide the interface for the prototype.

Contained field statements consist of the field keyword, followed in any order by the attribute values for field name, field type and field accessType (inputOnly, outputOnly, initializeOnly and inputOutput).

url values are "quote delimited" local filenames and/or remote addresses. Each filename or address should have a pound # symbol appended, followed by the case-sensitive literal name of the externally defined Prototype node. (This url syntax is similar to HTML bookmarks and X3D Anchor viewpoint links.)

EXAMPLE 11  An external prototype declaration follows:

         "https://www.myorg.org/examples/ViewPositionOrientationPrototype.wrl#ViewPositionOrientation"' >
    <field name='enabled'

See 4.4.5 External prototype semantics in [I19775-1] for details on external prototype statements.

4.3.10 ProtoInstance and fieldValue statement syntax

The ProtoInstance element is used to create instances of nodes, which shall be defined previously in the scene using either ProtoDeclare or ExternProtoDeclare statements.

ProtoInstance can contain zero or more fieldValue elements which are used to provide initial values for fields defined in the corresponding predecessor ProtoDeclare or ExternProtoDeclare statement. These fieldValue initializations are only used for field definitions with accesstype of initializeOnly or inputOutput and override any default values defined in the corresponding ProtoDeclare.

EXAMPLE 12  ProtoInstance fieldValue initialization

<Transform translation='0 -2.5 0'>
      <ProtoInstance name='EmissiveMaterial'>
        <fieldValue name='onlyColor'
                    value='0.2 0.6 0.6'/>
    <Text string='"Prototype syntax" "examples"'>
      <FontStyle justify='"MIDDLE" "MIDDLE"'/>
<ProtoInstance DEF='MyVPO' name='ViewPositionOrientation'>
  <fieldValue name='enabled' value='true'/>

ProtoInstance definitions always require a valid name, even when defining a USE node.

EXAMPLE 13  ProtoInstance USE node

<ProtoInstance USE='MyVPO' name='ViewPositionOrientation'/>

4.3.11 ROUTE statement syntax

A ROUTE statement consists of a ROUTE element followed by attributes fromNode, fromField, toNode and toField. The fromNode and toNode attributes are of XML type IDREF, meaning that corresponding DEF values shall be found in the preceding nodes.

The following semantic restrictions apply:

EXAMPLE 14  The following illustrates ROUTE statement syntax:

<TimeSensor DEF='Clock' cycleInterval='4' loop='true'/>
    key='0 0.5 1'
    keyValue='0 1 0 0,0 1 0 3.1416, 0 1 0 6.2832'/>
<ROUTE fromNode='Clock' fromField='fraction'
       toNode='Spinner' toField='set_fraction'/>
<ROUTE fromNode='Spinner' fromField='value_changed'
       toNode='TransformExampleUSE' toField='rotation'/>

4.3.12 IMPORT/EXPORT statement syntax

The following XML syntax applies to the IMPORT/EXPORT functionality of X3D.

An IMPORT statement consists of an IMPORT element followed by attributes inlineDEF, importedDEF, exportedDEF, and (optionally) AS.

An EXPORT statement consists of an EXPORT element followed by attributes localDEF and (optionally) AS.

EXAMPLE 15 2 The following depicts the XML encoding of an EXPORT statement within the inlined InlineExport.x3d model:

<!-- file InlineExport.x3d -->
<Transform DEF='T1'> <!-- contained 3D content --> </Transform>
<!-- Hint: EXPORT statement follows node of interest, since localDEF field is similar to USE with type IDREF -->
<EXPORT localDEF='T1' AS='RootTransform'/>

EXAMPLE 16  1 The following depicts the XML encoding of an IMPORT statement within a parent scene that corresponds to a separate Inline model:

<!-- file InlineImport.x3d -->
<Inline DEF='MyInlineModel' url='"InlineExport.x3d"' DEF='I1' url='"someUrl.x3d"'/>
        inlineDEF='MyInlineModel'   inlineDEF='I1'
        importedDEF='RootTransform' exportedDEF='RootTransform'
        AS='MyInlineRootTransform'  AS='I1Root'/>
<OrientationInterpolator DEF='MySpinner' key='0 0.3333 0.6667 1' keyValue='0 1 0 0, 0 1 0 2.094395, 0 1 0 4.18879, 0 1 0 0'/>
        fromNode='MySpinner' fromField='value_changed'
        toNode='MyInlineRootTransform' toNode='I1Root' toField='set_rotation'/>

4.3.13 Encapsulating Script node code

Code for scripts should not be placed so as to be parsed by XML parsers. Therefore, such code should be encapsulated to avoid such parsing. The preferred method to encapsulate source code in a Script node is to wrap it in a child CDATA construct following the <field/> and <IS><connect/></IS> definitions. The CDATA construct (see [XML]) ensures that all contained characters are treated literally without further escaping or modification.

If both a url field and a CDATA clause are encountered, the url field is processed first. Thus, the CDATA construct can also be considered equivalent to one additional value appended to the url MFString array. This ordering allows an online script code url to take priority over fallback default script code in the CDATA construct. This ordering also allows run-time updates if a viewer is connected to the network, if so desired by the originating author.

EXAMPLE 17  The following example demonstrates the use of a CDATA construct within a Script node:

<Script directOutput='true'>
  <field name='ROOT' type='SFNode' accessType='initializeOnly'>
    <Transform USE='ROOT'/>


  function R ()
    return Math.random();

  function initialize()
    for (i=0; i < 10; i++)
      rand1 = 100*R();
      rand2 = 100*R();
      rand3 = 20*R();
      rand4 = 40*R();
      rand5 = 20*R();
      string =
        'Transform {' +
        '  translation ' + rand1 + ' 0 ' + rand2 +
        '  children [' +
        '    Shape {' +
        '      appearance Appearance {' +
        '        material Material {' +
        '          diffuseColor ' + R() + ' ' + R() + ' ' + R() +
        '        }' +
        '      }' +
        '      geometry Box {' +
        '        size ' + rand3 + ' ' + rand4 + ' ' + rand5 +
        '      }' +
        '    }' +
        '  ]' +
        newNode = Browser.createVrmlFromString(string);
        ROOT.children[i] = newNode[0];


cube4.4 X3D files and the World Wide Web

4.4.1 File extension and MIME types

XML-encoded X3D files shall use the file extension “.x3d”. The MIME-type associated with that XML-encoded X3D file is “model/x3d+xml”.

X3D-encoded X3D files that have been “gzipped” shall use a file extension of either “.x3dz” or “.x3d.gz”. The MIME type is “model/x3d+xml”. The content-encoding value is “gzip”.

The concept of MIME types is defined in [RFC2077 MIME].

4.4.2 XML Document Type Definition (DTD)

The X3D XML DTD is defined in Annex A X3D XML Document Type Definition (DTD).

4.4.3 Schema

The X3D XML schema is defined in Annex B X3D XML Schema.

4.4.4 X3D XML Schematron

X3D XML Schematron is defined in Annex C X3D XML Schematron.

--- X3D separator bar ---