Syntax rules for COLLADA Extensions

This page describes the rules and guidelines for COLLADA syntax that is helpful while defining extensions.

Data conventions

Use the following conventions for the order of values and preferred constraints within a single element, for example:

<color>0 0 1 0</color>

Values	Order
Colors/channels	RGB or RGBA
Arrays and matrices	Matrices in COLLADA are column matrices in the mathematical sense. Matrices are written in row at a time to aid the human reader. [ Sx 0 0 X 0 Sy 0 Y 0 0 Sz Z 0 0 0 1 ]
Radii	Major (u direction) followed by minor (v direction)
Spatial info (translate, rotate, scale, etc.)	Column vector [ X, Y, Z ], followed by a fourth value if appropriate. Only <translate> is a true column vector. The others are simply vectors of values that satisfy their respective designs. <scale> is the diagonal of a matrix. <skew> is an angle plus two column vectors as-in the Renderman notation. Prefer graphics industry over other conventions or local practices.
Translation/rotation combined	Possible using either a matrix or a lookat element. Not recommended. Always allow discrete access to transforms.
Matrices	Use only invertible matrices.
Tokens	Text values that comprise a set of enumerants should be grouped as such.

Tokens

The COLLADA schema, and therefore an extension schema, has a few things that are comparable to API tokens:

• public element names (e.g. <asset>)
• public attribute names (e.g. <extra type="">)
• public enumerations (e.g. <effect> profiles)
• public text values (e.g. "X_AXIS", "LINEAR", "POSITION")

Enumeration elements that appear in a schema should have their values included and documented in the extension specification where appropriate. If the XML Schema language data type that expresses the enumeration's values is purely an implementation detail of the schema, its schema type name can be omitted from the specification.

Naming conventions

Abbreviations in element names

Spell out words fully (for example, vertices, not verts), except for the following existing COLLADA conventions:

• Some names follow the problem domain conventions like OpenGL.
• Some names follow the XML Schema naming conventions (e.g. IDREF).
• Most names follow the COLLADA 1.5 Schema conventions (e.g. lowercase with underscores).
  • As a rule, follow the COLLADA 1.5 naming conventions.

Abbrev	Word	Example	Note
2d, 3d	2-dimensional, 3-dimensional	<create_2d>	Exception like <sampler2D> follow a shading language conventions like Cg and OpenGL
brep	boundary representation	<brep>
coord	coordinate(s)	<fog_coord_src>
dest	destination	<dest_rgb>
env	environment	<texture_env_color>
fov	field of view	<xfov>
func	function	<alpha_func>
hex	hexadecimal	<hex>
id	identifier	<IDREF_array>	id has specific meaning within XML and COLLADA
info	information	<axis_info>
init	initialize	<init_from>
int	integer	<int_array>
mag	magnification	<magfilter>	This follows OpenGL conventions.
min, max	minimum, maximum	<minfilter>, <max>
mip	MIPmap	<mip_bias>
op	operation, operator	<color_logic_op_enable>	In attribute names, spell out ("operator")
param	parameter	<connect_param>
RECT	rectangle	<samplerRECT>	These follow OpenGL conventions.
ref	reference	<ref>, <ref_attachment>	ref used as reference to id, sid, or URI.
RGB	red/green/blue	<RGB>	This follows OpenGL conventions.
src	source	<fog_coord_src>	The latter follows OpenGL conventions.
sid	scoped identifier	<SIDREF_array>	sid has specific meaning within COLLADA
tex	texture	<texcombiner>, <texenv>	The latter follows OpenGL conventions.

Following apply only when specifying indices (primitive values) for constructing polygons or vertices. The reason they are abbreviated (terse) is because they can be high frequency markup in the document:

Abbrev	Word	Example	Note
p	primitive - indices/vertex attributes for a polygon/etc.	<p>, <pcurves>
ph	primitive/hole - indices/vertex attributes for polygon with a hole	<ph>
h	hole - indices/vertex attributes for the hole within a polygon	<h>
v	vertices - indices for a vertex	<v>

Attribute names

COLLADA uses the following names for attributes. Extensions should use the same names for equivalent functionality.

Note: This is not a complete list. Attributes that appear in only one or two elements aren't usually listed unless they might be of obvious future use.

Identifiers and references

Name	Type(s)	Meaning/Notes
axis	xs:token (should be sidref_type)	reference to a sid of an axis (in articulated_system/kinematics) or of an axis_info (in articulated_system/motion)
joint	xs:token (should be sidref_type)	reference to a sid of a joint or instance_joint
link	xs:token (should be sidref_type)	reference to a sid of a link
node	xs:token (should be sidref_type)	reference to a sid of a node
body	sidref_type	reference to sid of rigid body
id	xs:ID	unique identifier for element within instance document
material	xs:NCName	declares a symbol for a material that is bound at instantiation
name	xs:token	name for an element; not used by COLLADA, so application-defined usage. For names of anything else, qualify the attribute's name; for example, type_name. Exception is that <usertype> typename follows Cg/OpenGL conventions.
parent	xs:anyURI	reference to id
proxy	xs:anyURI	reference to the id of a node that is a proxy to the url node.
ref	xs:token or xs:NCName	refers to the sid of an existing element (in <param>, <setparam>)
rigid_body	xs:anyURI	reference to sid of rigid body
sid	sid_type	scoped identifer, unique within scope of parent element
source	urifragment_type or xs:anyURI	URI reference to some kind of input in the same or another document
target	sidref_type or xs:anyURI or xs:string or xs:token	where fragment identifier is id of element
url	xs:anyURI or xs:anyURL	reference to another resource that may include a fragment identifier

Measurements, counts, numeric values

Name	Type(s)	Meaning
array_index	xs:unsignedInt	index into an array
count	uint_type or xs:unsignedLong	quantity of values within the element, such as number of elements in array, number of edges, and so on
depth	xs:unsignedInt	depth value for a 3D image
digits	xs:unsignedByte	significant decimal digits in a float_array
height	xs:unsignedInt or float_type	second dimension of an area or image
index	xs:nonNegativeInteger	generic index
length	xs:positiveInteger	number of elements in array that uses a shading language convention. Also a spatial dimension.
magnitude	xs:short	largest exponent for values in a float_array
offset	uint_type	index of the first value to sample from an array
scale	float_type	generic scalar
value	float4_type	generic vector
width	xs:unsignedInt or float_type	first dimension of an area or image

Other values

Name	Type(s)	Meaning
enable	xs:boolean	generic flag
end	xs:double	end time
entry	xs:token	name of entry point into referenced program
face	enumeration	indicates a cube map face
format	xs:token	indicates the format of a binary encoded shader or image
mip	xs:nonNegativeInteger	MIP level
mode	enumeration	geo-spatial altitude mode
operator	enumeration	texture combiner operators
param	xs:NCName	SID of a shader value
platform	xs:NCName or xs:string	vendor-defined platform
profile	xs:NMTOKEN or xs:NCName	vendor or standard defined scope for a technique (i.e. extension).
semantic	xs:NMTOKEN or xs:NCName	shader, kinematic, or input semantic
set	uint_type	input set identifier
source	enumeration	texture combiner sources
source	xs:anyURI or xs:NCName	reference to a data source
start	xs:double	start time
stride	uint_type	sample size for a data source
symbol	xs:NCName	identifier that will be bound
type	xs:NMTOKEN or enumeration	meta data hint
typename	xs:token	shader data type
xmlns	xs:anyURI	points to XML Namespace

Constructing names and choosing terms

Note: Whereas some of the other rules in this document are intended to be strictly adhered to, this section is intended as a set of guidelines to assist in name decisions. The guidelines should be considered, and then accepted or rejected, for each case.

Terms used in COLLADA should have a consistent meaning. When new functionality is introduced, it is desired to use terms that are previously established in COLLADA. If no term exists that fits with the new functionality, a new term may be used. Whenever a new term is used, the precise meaning of that term should be specified and added to this text so that future functionality has the option of reusing the term with a consistent meaning.

A term in COLLADA should encompass more then the meaning of the word found in a dictionary. It should encompass limitations and usages and give the reader a broader sense of the usage of the word in the context of COLLADA.

When choosing new words, always name the item for what it does or what it describes or stores, not for the intended usage of the data and preferably not for its name in any one specific DCC tool.

General naming conventions

• Always use specified abbreviations if one is given; otherwise, spell out words if possible for clarity. Never abbreviate terms that are already in the COLLADA schema and are not abbreviated. If you add terms to your extensions, abbreviate consistently, maintaining a local version of additions to the list of abbreviations.
• Element and attribute names are singular and use all lowercase, separating words with underscores, with the following exceptions:
  • The <COLLADA> element matches the trademarked name in uppercase.
  • Profile names, second part all uppercase (<profile_COMMON>, <profile_GLES>...)
  • Certain FX names, no underscores and second part all uppercase (<sampler3D>, <samplerCUBE>, <texture3D...)
  • Plural only when necessary (<control_vertices>, <edges>,...).
• COLLADA reserves UPPERCASE for text values (such as semantic values) in the common profile. For example, use "TEMPERATURE" not "temperature" or "Temperature". This is to ease migration from extension to standard schema specification.
• Refer to "Naming in parameters" section.

Enums, groups, and common

Names follow all other naming conventions and:

• Enumerations: end in _enum. Use the element or attribute name as the prefix when possible; for example, version_type defines values for the version attribute.
• Groups: end in _group.
• Common Profile Types: end in _common.

Naming in parameters

The COLLADA common profile uses the following naming conventions for canonical names:

• Parameter names are uppercase. For example, the values for the <param> element’s name attribute are all uppercase letters:

 <param name="X" type="float"/> 

• Parameter types are lowercase when they correspond to a primitive type in the COLLADA schema, in the XML Schema, or in the C/C++ languages. Type names are otherwise intercapitalized. For example, the values for the <param> element’s type attribute follow this rule:

 <param name="X" type="float"/> 

• Input and parameter semantic names are uppercase. For example, the values for the <input> and <newparam> elements’ semantic attribute are all uppercase letters:

 <input semantic="POSITION" source="#grid-Position"/> 
 <newparam sid="blah">
   <semantic>DOUBLE_SIDED</semantic>
   <float>1.0</float>
 </newparam>

Canonical terms in the schema

The following terms have specific meanings in COLLADA or are used by convention in the same way throughout the COLLADA schema:

Term	Examples	Convention
array	<IDEF_array>, <bool_array>	Array type prepended
id	<element id=xxx>	ID attribute always
instance	<instance_animation>	Instances are always singular
library	<library_animations>	Libraries are always plural
name	<element name=xxx>	User-defined Name attribute always
profile	<profile_GLES>, <profile_BRIDGE>, <technique profile="xxx">	Profiles include the profile name
sid	<element sid=xxx>	SID attribute always
url	<element url=xxx>	URL attribute always

Schema Internal Types

• Simple and Complex Types are used to define elements and attributes in the COLLADA schema. The types do not appear in the Specification and are not intended for use in COLLADA documents.

Naming: Names follow all other naming conventions and:

• types: end in _type. If it makes sense to do so, the name prefix is the same as the element that it defines; for example, instance_kinematics_scene_type describes the <instance_kinematics_scene> element.
• Abstract types and/or substitution groups, for a specific area or product can be prefixed with an appropriate domain name (namespace name); for example, fx_sampler3D_type for use within COLLADA FX.

Numbers: To make the underlying format of numbers more flexible, COLLADA uses the following types:

• float_type (floating point)
• int_type (integer)
• uint_type (unsigned integer)

Lists and matrices: User-visible (Spec-level) names include numbers indicating required quantity of values:

• example:

<xs:simpleType name="bool3_type">
   <xs:restriction base="list_of_bools_type">
      <xs:minLength value="3"/>
      <xs:maxLength value="3"/>
   </xs:restriction>
</xs:simpleType>

• example:

<xs:simpleType name="bool2x2_type">
   <xs:restriction base="list_of_bools_type">
      <xs:minLength value="4"/>
      <xs:maxLength value="4"/>
   </xs:restriction>
</xs:simpleType>

References: Attributes or element values that reference other elements that have id or sid attributes:

• xs:IDREF (XML Schema type for an ID reference)
• xs:anyURI (XML Schema type for a URI, typically a URL to another document with an ID fragment)
• urifragment_type (COLLADA URI that is just an ID fragment)
• sidref_type (COLLADA Scoped ID reference)