4.1 Introduction and topics

4.1.1 Introduction

This clause describes key concepts in this part of ISO/IEC 19776. This includes the manner in which X3D constructs defined in ISO/IEC 19775-1 are encoded.

4.1.2 Topics

See Table 4.1 for the topics in this clause.

4.1.3 Conventions used

The following conventions are used throughout this part of ISO/IEC 19776:

Italics are used for event and field names, and are also used when new terms are introduced and equation variables are referenced.

A fixed-space font is used for URL addresses and source code examples. ISO/IEC 19776 Classic VRML encoding examples appear in bold, fixed-space font.

Node type names are appropriately capitalized (e.g., “The Billboard node is a grouping node...”). However, the concept of the node is often referred to in lower case in order to refer to the semantics of the node, not the node itself (e.g., “To rotate the billboard...”).

The form "0xhh" expresses a byte as a hexadecimal number representing the bit configuration for that byte.

With the exception of International Standards, throughout this part of ISO/IEC 19776, references to external documents are denoted using the “x.[ABCD]” notation, where "x" denotes in which clause or annex the reference is described and “[ABCD]” is an abbreviation of the reference title. References without the "x." are references to the bibliography. International Standards are referenced by their number and link to the appropriate entry in 2 Normative references.

EXAMPLE 2.[ABCD] refers to a reference described in Clause 2 and [ABCD] refers to a reference described in the Bibliography.

4.2 Overview

An X3D file is structured as defined in 7.2.5 Abstract X3D structure of ISO/IEC 19775-1. This part of ISO/IEC 19776 specifies a syntax that satisfies the requirements specified by ISO/IEC 19775-1.

4.3 Classic VRML encoding file syntax

4.3.1 Classic VRML encoding

This clause describes the syntax of Classic VRML-encoded, human-readable X3D files. A more formal description of the syntax may be found in Annex A Grammar. The syntax of X3D in terms of the Classic VRML encoding are presented in this part of ISO/IEC 19776. The semantics of X3D are as defined in ISO/IEC 19775-1.

For the Classic VRML encoding, the # character begins a comment. The first line of the file, the header, also starts with a # character. Two forms of comment are allowed, a single line comment and a block comment. A single line comment starts with a # and continues until the next line or file terminator, whichever comes first. A block comment starts with #/* and continues until */#. Line terminators are ignored. An unterminated block comment is an error.

Within either a single line comment or a block comment, all characters are ignored except as described above. A single line or block comment cannot start within a double-quoted SFString or within MFString fields. Within an SFString or MFString field, the # character or #/* character sequence is considered part of the SFString or MFString field.

Commas, spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of string fields. Separator characters and comments are collectively termed whitespace.

An X3D document server may strip comments and extra separators including the comment portion of the header line from an X3D file before transmitting it. Metadata, as defined in 7.2.4 of ISO/IEC 19775-1, should be used for persistent information such as copyrights or author information.

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.

EXAMPLE  “Sphere” is different from “sphere” and “BEGIN” is different from “begin.”

The following reserved keywords shall not be used for field, event, PROTO, EXTERNPROTO, or node names:

• AS
• COMPONENT
• DEF
• EXPORT
• EXTERNPROTO
• FALSE and false
• head
• IMPORT
• initializeOnly
• inputOnly
• outputOnly
• inputOutput
• IS
• META
• NULL
• PROFILE
• PROTO
• ROUTE
• Scene
• TO
• TRUE and true
• UNIT
• USE
• X3D

4.3.2 Statements

4.3.2.1 Organization of statements

After the required Header statement as defined in 4.3.2.2 Header statement syntax, an X3D file shall contain one PROFILE statement as defined in 4.3.2.3 PROFILE statement syntax, followed by zero or more COMPONENT statements as defined in 4.3.2.4 COMPONENT statement syntax, followed by zero or more UNIT statements as defined in 4.3.2.5 UNIT statement syntax, followed by zero or more META statements as defined in 4.3.2.6 META statement syntax.

After the configuration information defined by the preceding paragraph, an X3D file may contain any combination of the following:

1. Any number of PROTO or EXTERNPROTO statements as defined in 4.4.4 Prototype semantics, and 4.4.5 External prototype semantics of ISO/IEC 19775-1;
2. Any number of root node statements as specified in 4.3.2 Root nodes of ISO/IEC 19775-1;
3. Any number of USE statements as specified in 4.4.3 DEF/USE semantics of ISO/IEC 19775-1;
4. Any number of ROUTE statements as specified in 4.4.8.2 Routes of ISO/IEC 19775-1.

4.3.2.2 Header statement syntax

Every Classic VRML-encoded X3D file shall begin with:

#X3D V3.3 <character encoding type> [optional comment]<line terminator>

The header is a single line of UTF-8 text identifying the file as an X3D file and identifying the version of X3D encoded and character encoding type of the file. It may also contain an optional comment following the character encoding type specification.

There shall be exactly one space separating “#X3D” from “V3.3” and “V3.3” from “<character encoding type>”. Also, the “<character encoding type>” shall be followed by a linefeed (0x0a) or carriage-return (0x0d) character, or by one or more space (0x20) or tab (0x09) characters followed by any other characters, which are treated as a comment, and terminated by a linefeed or carriage-return character.

This part of ISO/IEC 19776 specifies a single character encoding type, “utf8”, that indicates a clear text character encoding allowing for international characters to be displayed using the UTF-8 encoding defined in ISO/IEC 10646 (otherwise known as Unicode). The usage of UTF-8 is specified in 15 Text component of ISO/IEC 19775-1.

4.3.2.3 PROFILE statement syntax

A PROFILE statement consists of the word PROFILE followed by the name of any of the profiles specified in ISO/IEC 19775-1:

PROFILE <profileName>

Profiles are discussed in 4.6 Profiles of ISO/IEC 19775-1.

See A.2 General for details on PROFILE statement grammar rules.

4.3.2.4 COMPONENT statement syntax

A COMPONENT statement consists of the COMPONENT followed by a component support indication as follows:

COMPONENT <componentName>:<supportLevel>

The support level is an integer identifying one of the available support levels specified in the various component clauses of ISO/IEC 19775-1 or new clauses specified in additional parts of ISO/IEC 19775. Components are discussed in 4.5 Components of ISO/IEC 19775-1.

See A.2 General for details on COMPONENT statement grammar rules.

4.3.2.5 UNIT statement syntax

A UNIT statement consists of the UNIT keyword followed by a unit specification as follows:

UNIT <category> <name> <conversion_factor>

The <category> is one of the four base unit categories specified in 4.3.6 of ISO/IEC 19775-1. The <name> and <conversion_factor> fields are described in 7.2.5.5 of ISO/IEC 19775-1.

See A.2 General for details on UNIT statement grammar rules.

4.3.2.6 META statement syntax

A META statement consists of META followed by a string identifier for the metadata and a string containing the value of the metadata as follows:

META <key> <value>

The three parts of the META statement shall be separated by white space. Both <key> and <value> are quoted strings that may contain any character in the set specified by “<character encoding type>”.

See A.2 General for details on META statement grammar rules.

4.3.2.7 Node statement syntax

A node statement consists of an optional name for the node followed by the node's type and then the body of the node. A node is given a name using the keyword DEF followed by the name of the node. The node's body is enclosed in matching braces ("{ }"). Whitespace shall separate the DEF, name of the node, and node type, but is not required before or after the curly braces that enclose the node's body. See A.3 Nodes, for details on node grammar rules.

[DEF <name>] <nodeType> { <body> }

A node's body consists of any number of field statements, IS statements, ROUTE statements, PROTO statements or EXTERNPROTO statements, in any order.

4.3.2.8 Field statement syntax

A field statement consists of the name of the field followed by the field's value(s). The following illustrates the syntax for a single-valued field:

<fieldName> <fieldValue>

The following illustrates the syntax for a multiple-valued field:

<fieldName> [ <fieldValues> ]

See A.4 Fields for details on field statement grammar rules.

Each node type defines the names and types of the fields that each node of that type contains. The same field name may be used by multiple node types. See 5 Field type reference of ISO/IEC 19775-1, for the specification of field types.

4.3.2.9 PROTO statement syntax

A PROTO statement consists of the PROTO keyword, followed in order by the prototype name, prototype interface declaration, and prototype definition:

PROTO <name> [ <declaration> ] { <definition> }

See A.2 General for details on prototype statement grammar rules.

A prototype interface declaration consists of field declarations (see 4.3.2.8 Field statement syntax) enclosed in square brackets. Whitespace is not required before or after the brackets.

Field declarations consist of the keyword “field” followed by a field type, a name, and an initial field value of the given field type.

field <fieldType> <name> <initial field value>

4.3.2.10 IS statement syntax

The body of a node statement that is inside a prototype definition may contain IS statements. An IS statement consists of the name of a field from the node's public interface followed by the keyword IS followed by the name of a field from the prototype's interface declaration:

<fieldName> IS <fieldName>

See A.3 Nodes for details on prototype node body grammar rules.

4.3.2.11 EXTERNPROTO statement syntax

An EXTERNPROTO statement consists of the EXTERNPROTO keyword followed in order by the prototype's name, its interface declaration, and a list (possibly empty) of double-quoted strings enclosed in square brackets. If there is only one member of the list, the brackets are optional.

EXTERNPROTO <name> [ <external interface declarations> ] URL or [ URLs ]

An external prototype interface declaration consists of field declarations (see 4.3.2.8 Field statement syntax) enclosed in square brackets. Whitespace is not required before or after the brackets.

 See A.2 General for details on external prototype statement grammar rules.

4.3.2.12 USE statement syntax

A USE statement consists of the USE keyword followed by a node name:

USE <name>

See A.2 General for details on USE statement grammar rules.

4.3.2.13 ROUTE statement syntax

A ROUTE statement consists of the ROUTE keyword followed in order by a node name, a period character, a field name, the TO keyword, a node name, a period character, and a field name. Whitespace is allowed but not required before or after the period characters:

ROUTE <name>.<field/eventName> TO <name>.<field/eventName>

See A.2 General for details on ROUTE statement grammar rules.

4.3.2.14 IMPORT statement syntax

An IMPORT statement consists of the IMPORT keyword followed by a the name of an Inline node, a period character, name of node to import, followed optionally by a space, the AS keyword, a space, and an alias for the imported node:

IMPORT <inlineNodeName>.<nodeToImport> [AS <alias>]

See A.2 General for details on IMPORT statement grammar rules.

4.3.2.15 EXPORT statement syntax

An EXPORT statement consists of the EXPORT keyword followed by a the name of the node to be exported, followed optionally by a space, the AS keyword, a space, and an alias for the exported node:

 EXPORT <nodeToExport> [AS <alias>]

See A.2 General for details on EXPORT statement grammar rules.

4.4 File extension and MIME types

The file extension for UTF-8 encoded X3D files is “.x3dv”. The MIME type (see 2.[RFC2077]) for X3D files encoded in the Classic VRML encoding is “model/x3d+vrml”.

For Classic VRML encoded X3D files that are compressed using gzip (see 2.[RFC1952]), the file extension shall be either “.x3dvz” or “.x3dv.gz”. The MIME type for such files is “model/x3d+vrml”. The content-encoding value is “gzip”.