X3D XML encoding — ISO/IEC 19776-1:202x

There are two general classes of fields: fields that contain a single value (where a value may be a single number, a vector, or even an image), and fields that contain an ordered list of multiple values. Single-valued fields have names that begin with SF. Multiple-valued fields have names that begin with MF.

Multiple-valued fields are written as an ordered list of values enclosed in quotations and separated by whitespace. If the field has zero values, only the quotes are written. The last value may optionally be followed by whitespace.

EXAMPLE 1 All of the following are valid for a multiple-valued MFColor field color in the ColorNode containing a single color triplet:

Within MF arrays, commas may only be used as whitespace between values of individual base datatypes. Further, an integral number of tuple values shall be provided for 2-tuple, 3-tuple and 4-tuple datatypes.

Validation of individual values can be performed using XML Document Type Definition (DTD) (also known as DOCTYPE), X3D XML Schema, X3D Regular Expressions (regexes) [X3DREGEX], and X3D Schematron [SCHEMATRON.1] [SCHEMATRON.2] [X3DSCHEMATRON].

NOTE The precise expressive power for each of these validation tools can vary.

XML DTD/DOCTYPE validation can confirm well-formed XML, correct spelling of element and attribute names, legal parent-child node relationships, and correct enumeration values,
XML Schema validation can additionally validate correctness of most attribute values, including floating-point values,
X3D Regular Expressions (regexes) can detect malformed floating-point values and incorrect counts of values in SFVec/MFVec and SFMatrix/MFMatrix numeric arrays,
X3D Schematron validation provides a wide range of rules that check for ordering and logical consistency of values (e.g. a DEF node appearing before corresponding USE nodes).

5.2 SFBool and MFBool

The SFBool field specifies a single boolean value encoded as either the string true or the string false. MFBool specifies zero or more SFBool string values. Lower-case strings for true and false are used in order to maximize interoperability with other XML languages.

5.3 SFColor and MFColor

The SFColor field specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples. Each colour is encoded as an RGB triple of floating point numbers in ISO C floating point format (see ISO/IEC 9899) in the range 0.0 to 1.0. Comma characters that are used as whitespace within an SFColor value will fail XML validation. Comma characters that are used as whitespace between SFColor values in an MFColor array will pass XML validation.

is an MFColor field, color, containing the three primary colours red, green, and blue.

5.4 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour 4-tuple. MFColorRGBA specifies zero or more RGBA 4-tuples. Each colour is encoded as an RGBA 4-tuple of floating point numbers in ISO C floating point format (see ISO/IEC 9899) in the range 0.0 to 1.0. Comma characters that are used as whitespace within an SFColorRGBA value will fail XML validation. Comma characters that are used as whitespace between SFColorRGBA values in an MFColorRGBA array will pass XML validation.

is an MFColorRGBA field, color, containing the three partially transparent primary colours red, green, blue.

5.5 SFDouble and MFDouble

The SFDouble field specifies one high-precision floating point number. MFDouble specifies zero or more high-precision floating point numbers. SFDoubles and MFDoubles are encoded as ISO C floating point format (see ISO/IEC 9899).

is an MFDouble field, knot, containing three high-precision floating point values.

5.6 SFFloat and MFFloat

The SFFloat field specifies one single-precision floating point number. MFFloat specifies zero or more single-precision floating point numbers. SFFloats and MFFloats are encoded as ISO C floating point format (see ISO/IEC 9899).

5.7 SFImage

The SFImage field specifies a single uncompressed 2-dimensional pixel image. SFImage fields are encoded as three integers representing the width, height and number of components in the image, followed by width×height hexadecimal or integer values representing the pixels in the image, separated by whitespace. Comma characters that are used as whitespace within an SFImage value will fail XML validation.

Pixel values are limited to 256 levels of intensity (i.e., 0-255 decimal or 0x00-0xFF hexadecimal). A one-component image specifies one-byte hexadecimal or integer values representing the intensity of the image. For example, 0xFF is full intensity in hexadecimal (255 in decimal), 0x00 is no intensity (0 in decimal). A two-component image specifies the intensity in the first (high) byte and the alpha opacity in the second (low) byte. Pixels in a three-component image specify the red component in the first (high) byte, followed by the green and blue components (e.g., 0xFF0000 is red, 0x00FF00 is green, 0x0000FF is blue). Four-component images specify the alpha opacity byte after red/green/blue (e.g., 0x0000FF80 is semi-transparent blue). A value of 0x00 is completely transparent, 0xFF is completely opaque. Note that alpha equals (1.0 - transparency), if alpha and transparency range from 0.0 to 1.0.

Each pixel is read as a single unsigned number. For example, a 3-component pixel with value 0x0000FF may also be written as 0xFF (hexadecimal) or 255 (decimal). Pixels are specified from left to right, bottom to top. The first hexadecimal value is the lower left pixel and the last value is the upper right pixel.

is a 1 pixel wide by 2 pixel high one-component (i.e., greyscale) image, with the bottom pixel white and the top pixel black.

is a 2 pixel wide by 4 pixel high RGB image, with the bottom left pixel red, the bottom right pixel green, the two middle rows of pixels black, the top left pixel white, and the top right pixel yellow.

5.8 SFInt32 and MFInt32

The SFInt32 field specifies one 32-bit integer. The MFInt32 field specifies zero or more 32-bit integers. SFInt32 and MFInt32 fields are encoded as an integer in decimal or hexadecimal (beginning with '0x') format.

The IndexedLineSet in this example contains an MFInt32 field, coordIndex, containing three integer values.

5.9 SFMatrix3d and MFMatrix3d

The SFMatrix3d field specifies a 3×3 matrix of double-precision float elements. An MFMatrix3d field specifies zero or more 3×3 double-precision matrices. Each SFMatrix3d field is encoded as nine ISO C double-precision floating point values (see ISO/IEC 9899) separated by whitespace. The first three double-precision floating point numbers represent the top row of the matrix. The second three double-precision floating point numbers represent second row of the matrix. The last three double precision floating point numbers represent the bottom row of the matrix. Comma characters that are used as whitespace within an SFMatrix3d value will fail XML validation. Comma characters that are used as whitespace between SFMatrix3d values in an MFMatrix3d array will pass XML validation.

5.10 SFMatrix3f and MFMatrix3f

The SFMatrix3f SFMatrix3d field specifies a 3×3 matrix of single-precision float values. An MFMatrix3f MFMatrix3d field specifies zero or more 3×3 single-precision matrices. Each SFMatrix3f SFMatrix3d field is encoded as nine ISO C single-precision floating point values (see ISO/IEC 9899) separated by whitespace. The first three single-precision floating point numbers represent the top row of the matrix. The second three single-precision floating point numbers represent second row of the matrix. The last three single-precision floating point numbers represent the bottom row of the matrix. Comma characters that are used as whitespace within an SFMatrix3f value will fail XML validation. Comma characters that are used as whitespace between SFMatrix3f values in an MFMatrix3f array will pass XML validation.

5.11 SFMatrix4d and MFMatrix4d

The SFMatrix4d SFMatrix3d field specifies a 4×4 matrix of double-precision float elements. An MFMatrix4d MFMatrix3d field specifies zero or more 4×4 double-precision matrices. Each SFMatrix4d SFMatrix3d field is encoded as sixteen ISO C double-precision floating point values (see ISO/IEC 9899) separated by whitespace. The first four double-precision floating point numbers represent the top row of the matrix. The second four double-precision floating point numbers represent second row of the matrix. The third four double-precision floating point numbers represent the third row of the matrix. The last four double-precision floating point numbers represent the bottom row of the matrix. Comma characters that are used as whitespace within an SFMatrix4d value will fail XML validation. Comma characters that are used as whitespace between SFMatrix4d values in an MFMatrix4d array will pass XML validation.

5.12 SFMatrix4f and MFMatrix4f

The SFMatrix4f SFMatrix3d field specifies a 4×4 matrix of single-precision float values. An MFMatrix4f MFMatrix3d field specifies zero or more 4×4 single-precision matrices. Each SFMatrix4f SFMatrix3d field is encoded as sixteen ISO C single-precision floating point values (see ISO/IEC 9899) separated by whitespace. The first four single-precision floating point numbers represent the top row of the matrix. The second four single-precision floating point numbers represent second row of the matrix. The third four single-precision floating point numbers represent the third row of the matrix. The last four single-precision floating point numbers represent the bottom row of the matrix. Comma characters that are used as whitespace within an SFMatrix4f value will fail XML validation. Comma characters that are used as whitespace between SFMatrix4f values in an MFMatrix4f array will pass XML validation.

5.13 SFNode and MFNode

The SFNode field specifies a single X3D node. The MFNode field specifies an array of zero or more nodes.

EXAMPLE 1 The following illustrates initialization of a user-defined prototype field, named PositioningNodes, having type MFNode:

Definition of an SFNode field may contain the USE name of a previously defined node for initialization.

Definition of an SFNode field may contain the keyword NULL as the initialization value to indicate that it is empty. However, care is recommended nevertheless since NULL may be overridden as a DEF name earlier in the scene. , however.

EXAMPLE 3 Assuming that no node instance has a DEF="NULL", the following two definitions are equivalent:

5.14 SFRotation and MFRotation

The SFRotation field specifies one arbitrary rotation. The MFRotation field specifies zero or more arbitrary rotations. An SFRotation is encoded as four ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFRotation value will fail XML validation. Comma characters that are used as whitespace between SFRotation values in an MFRotation array will pass XML validation.

EXAMPLE An SFRotation containing a π/4 radians rotation of a Box about the Y axis is:

5.15 SFString and MFString

The SFString and MFString fields contain strings formatted with the UTF-8 universal character set (see [ISO/IEC 10646-1]). SFString specifies a single string encoded as a sequence of UTF-8 octets enclosed in double quotes (e.g., "string"). The MFString specifies zero or more SFStrings enclosed in single quotes (e.g., '"string1" "string2"').

The SFString and MFString fields contain strings formatted with the UTF-8 universal character set that are further subject to XML encoding rules (see [ISO/IEC 10646-1] and [XML]).

SFString specifies a single string encoded as a sequence of UTF-8 octets. SFString attributes shall be enclosed in either single quotes or double quotes (e.g., value='string' or value="string").

EXAMPLE 1 A node with an SFString attribute:

<WorldInfo title='MyModel.x3d'/>
<WorldInfo title="MyModel.x3d"/>

An MFString attribute is a sequence of zero or more SFString values. As with any XML attribute, each MFString attribute is similarly enclosed by single quotes or double quotes in the XML encoding. The delimiters for the overall MFString XML attribute shall match. The XML delimiter for the MFString attribute shall be different from the delimiter for the contained SFString values. Each pair of quoted SFString values within an MFString is separated by whitespace. It is recommended that when the interior SFString delimiters are double quotes, typically the exterior XML delimiters are single quotes.

EXAMPLE 2 EXAMPLE 1 A node with an MFString attribute containing two SFString values:

Any characters (including linefeeds and '#') are allowed to appear within SFString values. may appear within the quotes. Special characters as defined by XML (e.g., apostrophe and quotation mark), or any other individual character, can be individually replaced by any of the various are specified using XML character entity encodings (see [XML]).

Editors note: the next two sentences are adapted from ClassicVRML encoding, and were not previously included in XML encoding version 3.3. They may cause a change in existing implementations, and also result in erroneous examples 6c and 6d. Should we include them for consistency? If not, the specification needs to explicitly say that they are not required. Literal quotation-mark characters included as part of SFString content are preceded by a backslash character (e.g. \"). Similarly, literal backslash characters included as part of SFString content are preceded by a backslash character.

EXAMPLE 3 EXAMPLE 2 Two instances of a literal quotation mark the double quote are contained in the following MFString SFString field string,: which delimits a single SFString, which in turn contains two literal quotation marks within the string content, which are each escaped for proper parsing by using a backslash character (i.e. \").

Editors note on proposed change: special-case option for MFString attribute containing a single SFString value.

Resolution of this option is deferred until XML syntax for SFString and MFString is acceptably defined.

For an MFString list containing a single SFString value, the following relaxation of quoting that duplicates XML delimiters has historically been controversial. When draft prose and corresponding Mantis justifications are ready, we will need to again confirm consensus. We will consider computational simplicity, and also confidence that the author's intent is being respected correctly. Multiple testable examples, continuing implementation experience, and improved specification prose can all help.

Allowing this revised syntax (shown in EXAMPLE 4) does not affect the correctness or validation of any prior X3D3 content. Parsing changes to existing implementations are expected to be fairly simple, as illustrated by the following example pseudocode:

    // test MFString field for singleton unquoted SFString value, if found then adjust it

    if (isFieldMFString and (string-length(value) > 0) and
          (not(contains(value, '”') or (count(value,'\\”') equals count(value,'”'))))
     
    then value = '”' + value + '”'; // string catenation restores value as quoted SFString

    // continue with prior parsing code for MFString

Of relevance in this context: this relaxation (of duplicative exterior quotes surrounding a single SFString value within an MFString attribute) avoids a common error mode in content creation, which significantly hampers X3D usability provided by Text nodes if the defined string is not successfully rendered and visible for end users. Thus this relaxation of duplicative quoting (solely for a singleton SFString value within an MFString attribute) reduces unnecessary errors in content creation and improves run-time correctness of X3D models.

As referenced in Mantis 488, the 19776-2 ClassicVRML Grammar points out a similar relaxation for ClassicVRML encoding mfstringValue grammar that allows optionally omitting the [ "square bracket" ] delimiters, as an allowed alternative for an MFString list that only contains a single SFString. That corresponding rule also reinforces the assessment for this special case that implementations can be computationally efficient, and that author clarity is maintained, when a duplicative outer delimiter is omitted.

Explanatory prose and EXAMPLE 4 show how multiple equivalent variations are possible. Sometimes these variations occur during workflow processing by XML tools, at some point following initial author (or tool) completion of an X3D XML model. Such character substitutions are allowed, and indeed equivalent, because XML Information Set (Infoset) rules specifically exclude "Whether characters are represented by character references."

Consideration of alternatives: if the complete strictness of the following proposedDeletion NOTE is insisted upon, then it is reasonable to expect frequent occurrences of author-provided text not being rendered to guide end users. 3D text is frequently provided as navigation guidance, or as Anchor links to other models and viewpoints. Absence of such text indicators in a scene can impose a significant cost in content usability. Thus forbidding some text expressions, which might be silently omitted without warning or visible context, means that this issue is still not fully resolved if the revision is rejected. X3D browsers still have the option to accept such unambiguous content and nevertheless render the Text string for the user, without being required to report an error or warning. However, even then the consequence is to encourage "runs best in browser X" inconsistencies and non-interoperability. Encouraging such mixed outcomes for an essential capability is undesirable for multiple reasons. Thus this specification refinement (illustrated in EXAMPLE 4) is important in multiple ways.

NOTE 1, NOTE 2, and EXAMPLE 6 further illustrate incorrect variations which violate production rules in the W3C XML Recommendation for Well-Formed XML Documents.

Proposed revisions follow.

An MFString field that contains only a single SFString value is a special case that can optionally be represented without requiring the usual exterior quotation marks found on an SFString value. Thus the second entry in the following example is equivalent to EXAMPLE 3.

EXAMPLE 4 Nodes with MFString attribute containing a single unquoted SFString:

<Text string='Who did it?'/>

<Text string='He said, \"Immel did it!\"'/>

Similar to HTML and other XML string values, individual SFString values can have numerous equivalent variations by substituting character entities for individual characters (see [ISO/IEC 10646-1] and [XML]). Each character entity substitution can be expressed in decimal form, hexadecimal form, or as an abbreviation (if predefined). EXAMPLE 5 shows a number of equivalent examples in tabular form, with several cases having many more equivalent representations possible.

EXAMPLE 5 X3D XML syntax examples: (TODO double-check every example)

	Examples with equivalent values	Resulting text
5a	`<-- escaped character entities for single quotation mark -->` `\"` `\"` `\"` `\"`	"
5b	`<-- SFString examples including quotation-mark characters -->` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>`	"MyModel.x3d"
5c	`<-- MFString examples containing single SFString -->` `<Text string='"Hello world!"'/>` `<Text string='Hello world!'/>` `<Text string="Hello world!"/>`	Hello world!
5d	`<-- MFString examples showing character entities for quotes -->` `<Text string=' "Hello" "World" '/>` `<Text string=' "Hello" "World" '/>` `<Text string=" "Hello" "World" "/>` `<Text string=" &Hello" "World" "/>` `<Text string=" "Hello" "World" "/>`	Hello World
5e	`<-- EXAMPLE 3 and alternatives -->` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<-- EXAMPLE 4 and alternatives -->` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` (plus numerous additional permutations and variations)	He said, "Immel did it!"
5f	`<-- SFString as empty string, i.e. default value -->` `<WorldInfo/>` `<WorldInfo title=''/>` `<WorldInfo title=""/>`	(no text)
5g	`<-- MFString as empty list, i.e. default value -->` `<Text/>` `<Text string=''/>` `<Text string=""/>`	(no text)
5h	`<-- MFString contains single empty SFString -->` `<Text string='""'/>`	(no text)

NOTE 1. A quotation mark character (i.e. ") can be replaced by a character entity (\" or \" or \") within an MFString attribute that is itself delimited by quotation mark characters, since such an attribute meets the requirements for well-formed XML.

NOTE 2. SFString content containing a quotation mark that is not preceded by a backslash \ escape character results in an incorrectly formed SFString value.

As shown above, EXAMPLE 5 illustrates a number of correctly formed examples that have multiple possible representations. To clearly illustrate common errors, EXAMPLE 6 below shows a number of similar but invalid SFString and MFString expressions. These examples each fail to follow XML attribute-quoting rules described in NOTE 1, fail to escape X3D backslash prerequisites for literal quotation marks described in NOTE 2, or fail to meet XML and X3D rules simultaneously.

EXAMPLE 6 Common errors:

6a. erroneous SFString:    <WorldInfo DEF="NotWellFormedXML1" title=" \"MyModel.x3d\" "/>

6b. erroneous MFString:           <Text DEF="NotWellFormedXML2"   string=" "Hello" "World" "/>

6c. erroneous SFString:    <WorldInfo DEF="IncorrectX3dQuotes1" title=' "MyModel.x3d" '/>

6d. erroneous MFString:           <Text DEF="IncorrectX3dQuotes2" string=' He said "Immel did it." '/>

6e. erroneous MFString: <NavigationInfo DEF="IncorrectX3dQuotes3" type=" 'WALK' 'ANY' "/>

5.16 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values.

A time value is encoded as a double-precision floating point number in ISO C floating point format (see ISO/IEC 9899).

where cycleInterval is an SFTime field , cycleInterval, representing a time of 5.0 seconds for the duration period interval of the TimeSensor node.

5.17 SFVec2d and MFVec2d

The SFVec2d field specifies a two-dimensional (2D) high-precision vector. An MFVec2d field specifies zero or more 2D high-precision vectors. SFVec2d and MFVec2d values SFVec2d's and MFVec2d's are encoded as a pair of ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec2d value will fail XML validation. Comma characters that are used as whitespace between SFVec2d values in an MFVec2d array will pass XML validation.

5.18 SFVec2f and MFVec2f

The SFVec2f field specifies a two-dimensional (2D) vector. An MFVec2f field specifies zero or more 2D vectors. SFVec2f and MFVec2f values SFVec2f's and MFVec2f's are encoded as a pair of ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec2f value will fail XML validation. Comma characters that are used as whitespace between SFVec2f values in an MFVec2f array will pass XML validation.

5.19 SFVec3d and MFVec3d

The SFVec3d field specifies a three-dimensional (3D) high-precision vector. An MFVec3d field specifies zero or more 3D high-precision vectors. SFVec3d and MFVec3d values SFVec2d's and MFVec2d's are encoded as three ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec3d value will fail XML validation. Comma characters that are used as whitespace between SFVec3d values in an MFVec3d array will pass XML validation.

5.20 SFVec3f and MFVec3f

The SFVec3f field specifies a three-dimensional (3D) vector. An MFVec3f field specifies zero or more 3D vectors. SFVec3f and MFVec3f values SFVec2f's and MFVec2f's are encoded as three ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec3f value will fail XML validation. Comma characters that are used as whitespace between SFVec3f values in an MFVec3f array will pass XML validation.

5.21 SFVec4d and MFVec4d

The SFVec4d field specifies a four-dimensional (4D) double-precision vector (or a three-dimensional homogeneous vector). An MFVec4d field specifies zero or more 4D double-precision vectors. SFVec4d and MFVec4d values SFVec4d's and MFVec4d's are encoded as four ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec4d value will fail XML validation. Comma characters that are used as whitespace between SFVec4d values in an MFVec4d array will pass XML validation.

5.22 SFVec4f and MFVec4f

The SFVec4f field specifies a four-dimensional (4D) single-precision vector (or a three-dimensional homogeneous vector). An MFVec4f field specifies zero or more 4D single-precision vectors. SFVec4f and MFVec4f values SFVec4f's and MFVec4f's are encoded as four ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec4f value will fail XML validation. Comma characters that are used as whitespace between SFVec4f values in an MFVec4f array will pass XML validation.

5.1 Introduction

5.1.1 Topics

5.1.2 Description