4.2.1 Introduction

The Extensible Markup Language (XML) (see 2.[XML]) is used for a self-validating encoding of Extensible 3D (X3D) Graphics. This encoding provides a Web-compatible format that maximizes interoperatibilty 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 correspondence between the elements of the abstract X3D scene graph and constructs in the XML encoding. 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 ISO/IEC 19775 (see 2.[I19775]).

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 2.[XML]).

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

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

The X3D DOCTYPE declaration is as follows:

Next comes the required X3D document root tag, which optionally specifies schema validation and profile information.

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 defined in 2.[SCHEMA].

Within the root X3D tag is the optional header section, and the required scene body.

This example header indicates that the content is XML encoded, follows the Extensibility Profile, and explicitly lists additional expected components. The X3D header may also contain further semantic information, via meta tags for name="value" pairs.

Browsers can support the specification of a different set of urls corresponding to the content written for different profiles. This allows players supporting higher level profiles to pick the content version for the higher level profile.

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 2.[I19775]. Rules for parsing and handling XML-encoded documents are defined in 2.[XML].

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

The only exceptions are within XML CDATA sections, which are ignored during XML parsing and typically only used for embedded script code. Comment exceptions also within double-quoted SFString and MFString fields, where the comment characters are escaped (using < for < and > 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 types of paired delimiting characters is encountered since XML processors are allowed to independently choose either form. These rules are described in  2.[XML] and 2.[INFOSET].

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

Spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of XML attribute values. Commas are not ignorable whitespace when mixed between or among XML 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 translatability between the different encodings of X3D scenes, the following reserved keywords shall not be used for field, event, Protytype or node names:

• AS
• component
• DEF
• EXPORT
• EXTERNPROTO
• FALSE
• head
• IMPORT
• initializeOnly
• inputOnly
• outputOnly
• inputOutput
• IS
• meta
• NULL
• PROTO
• ROUTE
• Scene
• TO
• TRUE
• USE
• X3D

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 and metadata information (as described 4.3.1 XML encoding);
2. A single required Scene element, which serves as a root node and contains one or more scene-graph elements (see 4.4.1 Root nodes in 2.[I19775]);
3. Any number of ProtoDeclare or ExternProtoDeclare statements (see 4.8 Prototype semantics in 2.[I19775]);
4. Any number of node elements (see 4.3.3 Scene graph hierarchy in 2.[I19775]);
5. Any number of USE statements (see 4.6.2 DEF/USE semantics in 2.[I19775]);
6. Any number of ROUTE statements (see 4.10.2 Route semantics in 2.[I19775]).
7. Any number of IMPORT or EXPORT statements (see 4.4.5 IMPORT/EXPORT semantics in 2.[I19775]).

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, i.e. name="value" pairs.

Nodes which serve as fields to other X3D nodes are expressed as contained XML elements, i.e. additional tagged names.

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.

The following example illustrates the use of node and field syntax:

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

A node element contains zero or more field attributes, as appropriate for each node type. When nested inside a ProtoDeclare ProtoBody, a node's body 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 Schema or X3D Document Type Definition (DTD). The Schema and DTD 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 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 limitation of XML that requires each XML DTD and Schema to have a single namespace for ID types.

Continuing the previous example statements:

Nodes containing a USE="someName" attribute can include no other attributes except containerField and class.

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 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. For example:

4.3.6 class attribute syntax

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

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).

Prototype declaration examples (without and with field declarations, respectively) follow.

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'). Node (or node array) values are contained as child nodes within the field declaration. For example, the <Group DEF='DefaultNodeValue'/> below provides a default initialization for the children field in the ProtoDeclare body:

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

See 5 Encoding of fields, for the specification of the 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.

The type and accessType of each field must 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 preceding Prototype declaration for example use of IS/connect constructs.

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

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.)

External prototype declaration example follows.

See 4.4.5 External prototype semantics in Part 1 of 2.[I19775] 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 must 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.

Examples follow.

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.

Important semantic restrictions:

• ROUTE elements are not scene-graph nodes
• DEFed nodes within each ProtoDeclare form a separate namespace. It is an error to ROUTE into (or out of) a ProtoDeclare body.

The following example illustrates ROUTE statement syntax:

The complete X3dHeaderPrototypeSyntaxExamples.x3d example presented in this clause is available in Annex C Examples.

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, exportedDEF, and AS.

An EXPORT statement consists of an EXPORT element followed by attributes localDEF and rootTransform.

Example encoding of IMPORT statement:

<Inline DEF='I1' url='"someUrl.x3d"'/> 
<IMPORT InlineDEF='I1' exportedDEF='rootTransform' AS='I1Root'/> 
<PositionInterpolator DEF='PI'/> 
<ROUTE fromNode='PI' fromField='value_changed' toNode='I1Root' toField='set_translation'/> 

Example encoding of EXPORT statement:

<Transform DEF='T1'/> 
<EXPORT localDEF='T1' AS='rootTransform'/>

4.4 X3D files and the World Wide Web

4.4.1 File extension and MIME types

The file extension for XML-encoded X3D files is .x3d (for Extensible 3D).

Multipart Internet Mail Extensions [MIME] were originally designed to distinguish email attachments. The MIME type tells the client what kind of data is contained in the file so that it can decode and handle it appropriately. For files on a local machine, this delegation can be accomplished simply by the file extension. In a web server context however, the MIME type is sent first as a single line and does not appear in the document source. Each web server is configured to associate a document MIME type with a file extension and deliver it to the client. Web browsers also maintain such a list which determines what plug-in or application will display the content.

4.4.2 Scripting language protocols

The Script node's url field may also support custom protocols for the various scripting languages. For example, a script url prefixed with ecmascript: shall contain ECMAScript source, with line terminators allowed in the string. The details of each language protocol are defined in the annex for each language. The following example illustrates the use of mixing custom protocols and standard protocols in a single url field. The order of appearance determines script-version precedence.

4.4.3 X3D XML Schema

The X3D Schema is defined in Annex A—X3D XML Schmea.

4.4.4 X3D XML Document Type Definition (DTD)

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