X3D Metadata Information

Table of Contents

1. What this chapter covers
2. Concepts
2.1. Purpose and common functionality
2.2. Comments
2.3. Abstract node types
3. Node descriptions
3.1. WorldInfo node
3.2. MetadataBoolean node
3.3. MetadataDouble node
3.4. MetadataFloat node
3.5. MetadataInteger node
3.6. MetadataString node
3.7. MetadataSet node
4. Summary
4.1. Key ideas
4.2. Related nodes and concepts

Metadata defined: in general, "data about data;" functionally, "structured data about data." Metadata includes data associated with either an information system or an information object for purposes of description, administration, legal requirements, technical functionality, use and usage, and preservation.

--Dublin Core Metadata Initiative (DCMI)

1. What this chapter covers

Metadata is the use of data to explain other data. In other words, the information provided in a document might have further descriptions that explain the origin or context of the information itself.

An X3D metadata node can be used to provide such information about any node in an X3D scene graph, and is placed as a child of the node that it describes. Metadata nodes are persistent, meaning that their values remain available and accessible after loading. Metadata nodes do not affect the visible rendering of a scene.

Other mechanisms to place information in a scene include <meta> tags placed in the <head> section of a document, the WorldInfo node, and comments.

X3D documents are a growing and important part of the World Wide Web. Metadata strategies become important when X3D scenes might get reused, repurposed or improved. Since authoring good content takes time, and since one X3D motto states "content is king," it is often worth documenting the relevant resources that are used to construct the many details presented in an X3D scene. Meta references and meta values are an excellent way to save such information archivally.

2. Concepts

2.1. Purpose and common functionality

There are four general mechanisms for adding metadata information in an X3D scene, listed as follows.

  1. Meta tags are contained in the document (meaning X3D scene) header and provide attribute-value pairs of information about the overall scene. The document <meta> tags are not available after a scene is loaded.

  2. A metadata node can be provided as the metadata field of any other X3D node.

  3. A WorldInfo node contains a simple unstructured string of persistent information, but the values of these fields cannot be updated at run time.

  4. Comments are unstructured text that can provide helpful information to authors. They are not retained when an X3D scene is parsed, and are not presentable to users when a scene is loaded.

Document <head> and <meta> tag rules are simple: these references identically match the syntax and semantics of HTML. Meta tags are discussed in Chapter 1 Technical Introduction section 1.2.5.5.

The WorldInfo node was originally defined in the original Virtual Reality Modeling Language (VRML97) specification, and for many years the only way to persistently save metadata in scenes. Because each WorldInfo node was able to include an array of arbitrary string values, it might seem that any type of metadata information might be included. This is literally correct. However, without internal structure, and without the ability to change such strings at run time, WorldInfo has limited practical use from a metadata standpoint and is infrequently used. This led to the definition of the typed Metadata nodes.

The X3D metadata nodes include MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString and MetadataSet. Each node can contain an array of named values, along with an optional reference that governs naming and semantic conventions. In each case, the data value is strongly typed to match the name of the node. In other words, MetadataBoolean contains a boolean array of MFBool values, MetadataFloat contains a floating-point array of MFFloat values, MetadataDouble contains a double-precision array of MFDouble values, and so on.

Comment syntax and considerations appear in the next section. Abstract node type definitions and detailed node definitions follow.

2.2. Comments

Comments are typically included by authors to explain the rationale for constructs of interest in a scene. Purpose, design decisions, relevant sources of information and any other kind of relevant information might be included. Comments are a great way to keep track of what you are thinking! In fact, you might even think of them as a "message into the future" for follow-on scene authors.

Commenting styles vary widely among scene authors and authoring tools. In general, it is good to be brief and factual. Adding motivation can help explain why something is done a certain way, or describing what objective you are trying to accomplish. Comments ought to be helpful for any author who looks at the source for the scene later. That author might be you, perhaps six or twelve months from now when you might remember the general flow of what you created but not all of the specific details. Thinking about what comments you might want to find when reviewing other people's work provides a good guideline for how much detail to put in your own work.

When identifying unfinished work, putting the phrase TODO at the beginning of a comment is a good authoring convention. TODO comments can either document unresolved problems or keep track of upcoming work. Some authoring tools look for such labels and flag them for authors, making it easier to later find the parts that need further work.

For example: <!-- TODO: add the missing parts of the model here. -->

If the comments in a scene are documenting the details of a significant problem, then another good practice is to put a <meta name="error" description="..."/> (or warning or info) tag in the scene header. In this way, authors can immediately be aware of showstopper difficulties that might appear deep within the scene.

Warning: comments do not persist after loading a scene in memory, and so may be lost if writing a scene back out again. Depending on the tool setting, comments may also be omitted when compressing a binary scene. Authors can use meta tags or metadata nodes to guarantee persistence of information.

2.3. Abstract node types

2.3.1. X3DMetadataObject

The X3DMetadataObject abstract node type defines the minimum required fields for metadata nodes. This node type is part of the Core profile, meaning that metadata structures are integral to all versions and profiles of X3D.

The six nodes of abstract type X3DMetadataObject also include a value field, either as a typed array of simple values or else (for MetadataSet) as contained nodes. Field definitions are listed in Table 15.1.

Table 15.1. Field definitions for X3DMetadataObject

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
2.3.1.1. name

The name field lists the name of the metadata being provided. Metadata information is provided as name-value pairs so that each value is uniquely identified. The default value is an empty string array.

2.3.1.2. value

The value field is not listed in abstract node type X3DMetadataObject, but is used (with varying types) by each of the Metadata nodes. For example, MetadataBoolean includes MFBool values.

2.3.1.3. reference

The reference field is optional and the default value is an empty string array. When used, it identifies the reference or standard defining the allowed values and semantic meaning of the metadata being provided.

2.3.1.4. Hints and warnings

If the reference field is not provided, authors are expected to deduce the meaning of the metadata from the name field.

A meta tag can be used to identify a metadata reference that is globally applicable to a scene.

2.3.1.5. containerField Considerations

Interestingly, while Metadata nodes usually provide scene-related information about their parent X3D node, they can also provide both values and metadata for a parent MetadataSet.

Warning: this approach somewhat counterintuitive. Usually Metadata nodes are blank (the default value) or use containerField="metadata" when a single node is used by itself. Otherwise include containerField="value" when the parent is a MetadataSet node.

These relationships are illustrated in Table 15.2.

Table 15.2. containerField Considerations for Metadata Nodes

Case containerField Parent node
Provide metadata values for parent node containerField="metadata" (default) Any node except MetadataSet
Provide metadata value nodes in a set containerField="value" MetadataSet
Provide metadata information about parent containerField="metadata" (default) MetadataSet

2.3.2. X3DInfoNode

The X3DInfoNode type implements the X3DChildNode interface, meaning that it can appear as a child node under a grouping node. Only the WorldInfo node implements the X3DInfoNode interface. Field definitions are listed in Table 15.3.

Table 15.3. Field Definitions for X3DInfoNode Type

type accessType name default range profile
SFNode inputOutput metadata NULL [X3DMetadataObject] Core
2.3.2.1. metadata

The metadata field simply matches the requirements of the X3DNode interface, allowing such nodes to themselves include a single metadata node.

3. Node descriptions

3.1. WorldInfo node

The WorldInfo node can provide a title for a scene as well as a simple string array providing arbitrary information. WorldInfo implements the X3DInfoObject type.

WorldInfo title information is helpful. A good authoring practice is to put a WorldInfo node with title information near the top of a scene so that it is easily found by an author.

The WorldInfo node is in the Interchange Profile. The Interchange Profile provides full support for all fields. The WorldInfo node has the fields defined in Table 15.4. Node syntax is shown in Table 15.5.

Table 15.4. Field Definitions for WorldInfo Node

type accessType name default range profile
MFString initializeOnly info [ ] Core
SFString initializeOnly title "" Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.5. Node Syntax for WorldInfo Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<WorldInfo DEF="MyWorldInfo"
      info=' "String1" "String2" '
      title="Example World"/>
                        
DEF MyWorldInfo WorldInfo {
      info ["String1" "String2"]
      title "Example World"
}
                        

WorldInfo nodes can appear at the top level of the scene graph, and as a child under a grouping node.

WorldInfo is not an X3DMetadataObject and cannot appear as a child of other nodes where only metadata nodes are allowed.

3.1.1. info

The info field allows multi-element strings to be specified. Because info has accessType initializeOnly, it cannot be set or read during run time. This string array is not processed by X3D and exists to allow the creator to save human-readable information about the content in a scene file.

3.1.2. title

The title field allows a single-element string to be provided as the title for the model, possibly displayed in the browser's title bar.

3.1.3. Hints and warnings

Browsers and viewers are allowed to present scene titles in any way that they want. Typically it is in a window frame border, or at the top border of the Web browser. Sometimes it is located as part of a navigation bar, which may or may not be displayed. The X3D specification does not legislate such behavior in order to allow browsers to "do the right thing" depending on their design and current context. As a result, a user may (or may not) notice the author-provided scene title.

No rules are defined for cases when multiple titles are provided by multiple WorldInfo nodes. Presumably a WorldInfo title in a parent scene will take precedence over child scenes loaded via the Inline node.

The Browser class in the Scene Authoring Interface (SAI) can be used by Script nodes to set the title of a scene programmatically. Use of the SAI is beyond the scope of this work.

Setting the scene title using WorldInfo is a good authoring practice. Otherwise use a metadata node instead of a WorldInfo node to save information about the scene.

3.2. MetadataBoolean node

The MetadataBoolean node holds an array of boolean (true false) values. MetadataBoolean implements the X3DMetadataObject type.

MetadataBoolean is in the Core Profile. The node has the fields defined in Table 15.6. Node syntax is shown in Table 15.7.

Table 15.6. Field Definitions for MetadataBoolean Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFBool inputOutput value [ ] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.7. Node Syntax for MetadataBoolean Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataBoolean DEF="MyMetadataBoolean"
      name="Metadata_name"
      reference="Standard 1.2.3c"
      value='true false true'
</MetadataBoolean>
                        
DEF MyMetadataBoolean MetadataBoolean {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value [TRUE, FALSE, TRUE]
}
                        

3.2.1. value

The value of this metadata. MetadataBoolean supports multiple-element array of MFBool values. Each element may be any valid boolean value(true or false).

3.2.2. Hints and warnings

Do not include quote marks around individual values.

Warning: use lower-case values ("true false") for .x3d XML encoding, and upper-case values ("TRUE FALSE") for .x3dv ClassicVRML encoding.

3.3. MetadataDouble node

The MetadataDouble node holds a value array of double-precision floating-point numbers. MetadataDouble implements the X3DMetadataObject type.

MetadataDouble is in the Core Profile. The node has the fields defined in Table 15.8. Node syntax is shown in Table 15.9.

Table 15.8. Field Definitions for MetadataDouble Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFDouble inputOutput value [ ] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.9. Node Syntax for MetadataDouble Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataDouble DEF="MyMetadataDouble"
      name="Metadata_name"
      reference="Standard 1.2.3c"
      value='3.141592658, 2.71812181'
</MetadataDouble>
                        
DEF MyMetadataDouble MetadataDouble {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value [3.141592658, 2.71812181]
}
                        

3.3.1. value

The value of this metadata. MetadataDouble supports multiple-element array of double-precision numbers. Each element may be any valid double-precision value.

3.3.2. Hints and warnings

Do not include quote marks around individual values.

The choice of MetadataDouble versus MetadataFloat usually depends on the relevant tool utilizing the value, or else the relevant metadata reference defining the value.

3.4. MetadataFloat node

The MetadataFloat node holds a value array of single-precision floating-point numbers. MetadataFloat implements the X3DMetadataObject type.

MetadataFloat is in the Core Profile. The node has the fields defined in Table 15.10. Node syntax is shown in Table 15.11.

Table 15.10. Field Definitions for MetadataDouble Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFFloat inputOutput value [ ] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.11. Node Syntax for MetadataFloat Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataFloat DEF="MyMetadataFloat"
      name="Metadata_name"
      reference="Standard 1.2.3c"
      value='9.8 6.023e+23'
</MetadataString>
                        
DEF MyMetadataFloat MetadataFloat {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value [9.8 6.023e+23]
}
                        

3.4.1. value

The value of this metadata. MetadataFloat supports multiple-element array of floats. Each element may be any valid floating-point value.

3.4.2. Hints and warnings

Do not include quote marks around individual values.

The choice of MetadataDouble versus MetadataFloat usually depends on the relevant tool utilizing the value, or else the relevant metadata reference defining the value.

3.5. MetadataInteger node

The MetadataInteger node holds a value array of integer values. MetadataInteger implements the X3DMetadataObject type.

MetadataInteger is in the Core Profile. The node has the fields defined in Table 15.12. Node syntax is shown in Table 15.13.

Table 15.12. Field Definitions for MetadataInteger Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFInt32 inputOutput value [ ] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.13. Node Syntax for MetadataInteger Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataInteger DEF="MyMetadataInteger"
      name="Metadata_name"
      reference="Standard 1.2.3c"
      value='6, 28, 496'
</MetadataString>
                        
DEF MyMetadataInteger MetadataInteger {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value [6, 28, 496]
}
                        

3.5.1. value

The value of this metadata. MetadataInteger supports multiple-element array of integer. Each element may be any valid integer value.

3.5.2. Hints and warnings

Do not include quote marks around individual values.

3.6. MetadataString node

The MetadataString node holds a value array of string values. MetadataString implements the X3DMetadataObject type.

As discussed above, the various Metadata nodes each allow the storage of relevant information within the scene graph. While the WorldInfo node does support the general issue of a "storage" node, its fields are not accessible outside of the node, and WorldInfo does not support non-string data types. The other Metadata nodes do support data type-specific information that is accessible in a structured manner.

The MetadataString node holds a value array string of information. It is possible to use this node to hold all information as a string, but using the other datatype-specific nodes is generally recommended for non-string data.

MetadataString is in the Core Profile. The node has the fields defined in Table 15.14. Node syntax is shown in Table 15.15.

Table 15.14. Field Definitions for MetadataString Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFString inputOutput value [ ] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.15. Node Syntax for MetadataString Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataString DEF="MyMetadataString"
      name="Metadata_name"
      reference="Standard 1.2.3c"
      value=' "Part 27", "P27", "p27" '
</MetadataString>
                        
DEF MyMetadataString MetadataString {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value ["Part 27", "P27", "p27"]
}
                        

3.6.1. value

The value of this metadata. MetadataString supports multiple-element array of strings. Each element may be any valid string value.

3.6.2. Hints and warnings

Be careful to escape embedded quotes in the same manner as other MFString data, such as that found in a Text node's string field.

Depending on the metadata reference involved, MetadataString can sometimes be used to hold specially typed data such as enumerations or boolean values.

3.7. MetadataSet node

The MetadataSet node holds zero or more metadata nodes. This allows more complex structures than the simple parent-child relationship available when using only the basic metadata nodes.

MetadataSet implements the X3DMetadataObject type.

MetadataSet is in the Core Profile. The node has the fields defined in Table 15.16. Node syntax is shown in Table 15.17.

MetadataSet can contain structured metadata values in multiple nodes that directly correspond to other metadata standards.

Table 15.16. Field Definitions for MetadataSet Node

type accessType name default range profile
SFString inputOutput name "" Core
SFString inputOutput reference "" Core
MFNode inputOutput value [ ] [X3DMetadataObject] Core
SFNode inputOutput metadata NULL [X3DMetadataObject] Core

Table 15.17. Node Syntax for MetadataSet Node

XML syntax (.x3d) ClassicVRML syntax (.x3dv)
<MetadataSet DEF="MyMetadataSet"
      name="Metadata_name"
      reference="Standard 1.2.3c">
        <MetadataString  USE="MyMetadataString" containerField="value"/>
        <MetadataInteger USE="MyMetadataInteger" containerField="value"/>
        <MetadataFloat    USE="MyMetadataFloat" containerField="value"/>
        <MetadataFloat    name="coefficients" value="3.141592653 2.7128 1 0" containerField="value"/>
</MetadataSet>
                        
DEF MyMetadataSet MetadataSet {
      name "Metadata_name"
      reference "Standard 1.2.3c"
      value [
          use MyMetadataString
          use MyMetadataInteger
          use MyMetadataFloat
          MetadataFloat {
         name="coefficients"
         value [ 3.141592653 2.7128 1 0 ]
          }
      ]
}
                        

3.7.1. value

Unlike the other metadata nodes which contain simple-type values, the value field of the MetadataSet node can contain multiple additional metadata nodes, including nested MetadataSet nodes. This is useful when a variety of metadata is needed to fully describe the significance of the parent node.

3.7.2. Hints and warnings

Warning: do not include a value attribute since only other Metadata nodes are allowed as values.

Observe the containerField considerations listed above. Apply containerField="value" for each contained immediate-child metadata node that is contained within the MetadataSet node.

MetadataSet nodes can contain other MetadataSet nodes in order to create sophisticated metadata structures.

In addition to value-related child nodes, a MetadataSet node can contain a single metadata node describing it. Set the default containerField="metadata" for that special case.

4. Summary

4.1. Key ideas

Meta tags provide information about a scene. Metadata nodes provided arrays of strongly typed data that is paired with a name and (optionally) a semantic reference. A WorldInfo node can provide a scene title and additional unstructured information. Comments let authors document scene construction, but are not available at run time and not necessarily persistent after processing by some tools.

4.2. Related nodes and concepts

Chapter 1 Technical Introduction section 1.2.5.5 describes meta tags and a number of other scene-construction issues that are relevant to metadata structures in a scene.