SVG Tiny 1.2 - 20051207

5 Document Structure

Contents

5.1 Defining an SVG document fragment: the 'svg' element

5.1.1 Overview

An SVG document fragment consists of any number of SVG elements contained within an 'svg' element, including the 'svg' element.

An SVG document fragment can range from an empty fragment (i.e., no content inside of the 'svg' element), to a very simple SVG document fragment containing a single SVG graphics element such as a 'rect', to a complex, deeply nested collection of container elements and graphics elements.

An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent XML document.

The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the 'svg' and 'ellipse' elements belong to the SVG namespace:

Example: 05_01.xml
<?xml version="1.0"?>
<parent xmlns="http://example.org"
       xmlns:svg="http://www.w3.org/2000/svg">
   <!-- parent contents here -->
   <svg:svg width="4cm" height="8cm" version="1.2" baseProfile="tiny" viewBox="0 0 100 100">
      <svg:ellipse cx="50" cy="50" rx="40" ry="20" />
   </svg:svg>
   <!-- ... -->
</parent>
    

This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:

Example: 05_02.svg
<?xml version="1.0" encoding="UTF-8"?>
<svg width="5cm" height="4cm" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny" viewBox="0 0 100 100">
  <desc>Four separate rectangles
  </desc>
    <rect x="20" y="20" width="20" height="20"/>
    <rect x="50" y="20" width="30" height="15"/>
    <rect x="20" y="50" width="20" height="20"/>
    <rect x="50" y="50" width="20" height="40"/>
  <!-- Show outline of canvas using 'rect' element -->
  <rect x="1" y="1" width="98" height="98"
        fill="none" stroke="blue" stroke-width="2" />
</svg>
    

An SVG document fragment can only contain one single 'svg' element, this means that 'svg' elements cannot appear in the middle of SVG content.

In all cases, for compliance with the "Namespaces in XML 1.1" Recommendation [XML-NS], an SVG namespace declaration must be in scope for the 'svg' element, so that all SVG elements are identified as belonging to the SVG namespace.

For example, an 'xmlns' attribute without a prefix prefix could be specified on an 'svg' element, which means that SVG is the default namespace for all elements within the scope of the element with the 'xmlns' attribute:

Example: 05_03.svg
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny">
  <desc>Demonstrates use of a default namespace prefix for elements.</desc>
  <rect width="7" height="3"/>
</svg>
    

If a namespace prefix is specified on the 'xmlns' attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"), then the corresponding namespace is not the default namespace, so an explicit namespace prefix must be assigned to the elements:

Example: 05_04.svg
<?xml version="1.0"?>
<s:svg xmlns:s="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny">
  <s:desc>Demonstrates use of a namespace prefix for elements.
    Notice that attributes are not namespaced</s:desc>
  <s:rect width="7" height="3"/>
</s:svg>
    

Namespace declarations can also be specified on ancestor elements (illustrated in the above example). For more information, refer to the "Namespaces in XML 1.1" Recommendation [XML-NS].

5.1.2 The 'svg' element

Schema: svg
  <define name='svg'>
    <element name='svg'>
      <ref name='svg.AT'/>
      <zeroOrMore><ref name='svg.G.group'/></zeroOrMore>
    </element>
  </define>

  <define name='svg.AT' combine='interleave'>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.FocusHighlight.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.AnimateSyncDefault.attr'/>
    <ref name='svg.Core.attr'/>
    <ref name='svg.WH.attr'/>
    <ref name='svg.PAR.attr'/>
    <optional>
      <attribute name='viewBox' svg:animatable='true' svg:inheritable='false'>
        <ref name='ViewBoxSpec.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='zoomAndPan' a:defaultValue='magnify' svg:animatable='false' svg:inheritable='false'>
        <choice>
          <value>disable</value>
          <value>magnify</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='version' a:defaultValue='1.1' svg:animatable='false' svg:inheritable='false'>
        <choice>
          <value type='string'>1.0</value>
          <value type='string'>1.1</value>
          <value type='string'>1.2</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='baseProfile' svg:animatable='false' svg:inheritable='false'>
        <choice>
          <value type='string'>none</value>
          <value type='string'>tiny</value>
          <value type='string'>basic</value>
          <value type='string'>full</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='contentScriptType' a:defaultValue='application/ecmascript' svg:animatable='false' svg:inheritable='false'>
        <ref name='ContentType.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='snapshotTime' svg:animatable='false' svg:inheritable='false'>
         <choice>
           <value type='string'>none</value>
           <ref name='Clock-value.datatype'/>
         </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='timelineBegin' a:defaultValue='onLoad' svg:animatable='false' svg:inheritable='false'>
        <choice>
          <value type='string'>onLoad</value>
          <value type='string'>onStart</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='playbackOrder' a:defaultValue='all' svg:animatable='false' svg:inheritable='false'>
        <choice>
          <value type='string'>all</value>
          <value type='string'>forwardOnly</value>
        </choice>
      </attribute>
    </optional>
  </define>
    

Attribute definitions:

version = "1.0" | "1.1" | "1.2"
Indicates the SVG language version to which this document fragment conforms.

In SVG 1.0 and SVG 1.1 this attribute had the value '1.0' or '1.1' respectively, and SVG 1.2 adds the '1.2'. See rules for version processing for further instructions, notably on handling of unsupported values.

This attribute is read-only and cannot be modified via the uDOM api. Attempt to set the 'version' attribute with the setAttributeNS must result in an NO_MODIFICATION_ALLOWED_ERR being raised.

Animatable: no.
baseProfile = "profile-name"
Describes the minimum SVG language profile that the author believes is necessary to correctly render the content. See rules for baseProfile processing for further instructions.

This specification defines the values 'none' and 'tiny'. The value 'full' corresponds to all features in the SVG language; for SVG 1.1, this corresponds to the language features defined in the SVG 1.1 specification. The value 'basic' was defined in the SVG Mobile 1.1 specification. This specification corresponds to baseProfile="tiny" and version="1.2". A value of 'none' provides no information about the minimum language profile that is necessary to render the content.

If the attribute is not specified, the effect is as if a value of 'none' were specified.

This attribute is read-only and cannot be modified via the uDOM api. Attempt to set the baseProfile attribute with the setAttributeNS must result in an NO_MODIFICATION_ALLOWED_ERR being raised.

Animatable: no.
width = "<length>"
The intrinsic width of the SVG document fragment.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

If the attribute is not specified, the effect is as if a value of "100%" were specified.

Animatable: yes.
height = "<length>"
The intrinsic height of the SVG document fragment.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

If the attribute is not specified, the effect is as if a value of "100%" were specified.

Animatable: yes.
viewBox = "<list of number>" | "none"
See attribute definition for description.

Animatable: yes.
preserveAspectRatio = "[defer] <align> [<meet>]"
See attribute definition for description.

Animatable: yes.
snapshotTime = "<clock-value>" | "none"
Indicates a moment in time which is most relevant for a still-image of the animated SVG content. This time may be used as a hint to the SVG User Agent for rendering a still-image of an animated SVG Document, such as a preview. A value of 'none' means that no 'snapshotTime' is available. See an example of using the 'snapshotTime' attribute.

If the attribute is not specified, the effect is as if a value of 'none' was specified.

Animatable: no.
playbackOrder = "forwardOnly" | "all"
Indicates whether it is possible to seek backwards. In earlier versions of SVG there was no need to put restrictions on the direction of seeking but with the newly introduced facilities for long-running documents (e.g. the 'discard' element) there is sometimes a need to restrict this.

If 'playbackOrder' is set to 'forwardOnly', the content will probably contain 'discard' elements or scripts that destroy resources, thus seeking back in the document's timeline may result in missing content. If 'playbackOrder' is 'forwardOnly', the content should not provide a way, through hyperlinking or script, of seeking backwards in the timeline. Similarly the UA should disable any controls it may provide in the user interface for seeking backwards. Content with 'playbackOrder' = 'forwardOnly' that provides a mechanism for seeking backwards in time may result in undefined behavior or a document that is in error.
'forwardOnly'
This file is intended to be played only in the forward direction, sequentially, therefore seeking backwards should not be allowed.
'all'
Indicates that the document is authored appropriately for seeking in both directions.
The default value is 'all'.

Animatable: no.
timelineBegin = "onLoad" | "onStart"
Controls the initialization of the timeline for the document.

The 'svg' element controls the Document Timeline, which is the timeline of the 'svg' element's time container. For progressively loaded animations, the author would typically set this attribute to 'onStart', thus allowing the timeline to begin as the document loads, rather than waiting until the complete document is loaded.
'onLoad'
The document's timeline starts the moment the load event for the rootmost svg element is triggered.
'onStart'
The document's timeline starts at the moment the rootmost svg element's open tag is fully parsed and processed.
The default value is 'onLoad'.

Animatable: no.
contentScriptType = "content-type"
Identifies the default scripting language for the given document. This attribute sets the default scripting language for all the instances of script in the document fragment. This language must be used for all scripts that do not specify their own scripting language. The value content-type specifies a media type, per Multipurpose Internet Mail Extensions (MIME) PartTwo [RFC2046]. The default value is "application/ecmascript".

Animatable: no.
focusable = "true" | "false" | "auto"
See attribute definition for description.

Animatable: Yes
Navigation Attributes
See definition.


Content produced by illustration programs originally targeted at print often has a fixed width and height, which will prevent it scaling for different display resolutions. The first example below has a fixed width and height in pixels, and no 'viewBox'.

Example: width-height.svg
<?xml version="1.0"?>
<svg width="300px" height="600px" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny">
  <desc>...</desc>
</svg>
    

Normally, SVG content is designed to be scalable. To be scalable, SVG content must include a 'viewBox' attribute on the 'svg' element. This describes the region of world coordinate space (the initial user coordinate system) used by the graphic. This attribute thus provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.

The second example is scalable, using a 'viewBox' rather than a fixed width and height.

Example: viewBox.svg
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" 
     baseProfile="tiny" viewBox="0 0 300 600">
  <desc>...</desc>
</svg>
    

Below is an example of 'snapshotTime'. An SVG User Agent is displaying a number of SVG files in a directory by rendering a thumbnail image. It uses the 'snapshotTime' as the time to render when generating the image, thus giving a more representative static view of the animation. The appearance of the thumbnail for an SVG User Agent that honors the 'snapshotTime' and for an SVG User Agent that does not is shown below the example (UA with snapshot support at the left, without snapshot support at the right).

Example: 05_22.svg
<svg version="1.2" snapshotTime="3" baseProfile="tiny"
         xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" 
         viewBox="0 0 400 300">
  <title>Snapshot time example</title>
  <desc>This example shows the use of snapshotTime on an animation of 
     color
   </desc>
   <rect x="60" y="85" width="256" height="65" fill="none" stroke="rgb(60,126,220)" stroke-width="4"/>
    
   <text x="65" y="140" fill="rgb(60,126,220)" font-size="60">Hello SVG
      <animateColor attributeName="fill" begin="0" dur="3" from="white" to="rgb(60,126,220)"/>  
   </text> 
</svg>
    
Snapshot time thumbnails

5.2 Grouping: the 'g' element

5.2.1 Overview

The 'g' element is a container element for grouping together related graphics elements.

Grouping constructs, when used in conjunction with the 'desc' and 'title' elements, provide information about document structure and semantics. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.

A group of elements, as well as individual objects, can be given a name using the 'xml:id' attribute. Named groups are needed for several purposes such as animation and re-usable objects.

An example:

Example: 05_05.svg
<?xml version="1.0"?>
<svg width="5cm" height="5cm" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny" viewBox="0 0 5 5">
  <desc>Two groups, each of two rectangles
  </desc>
  <g xml:id="group1" fill="red" >
    <desc>First group of two red rectangles</desc>
    <rect x="1" y="1" width="1" height="1" />
    <rect x="3" y="1" width="1" height="1" />
  </g>
  <g xml:id="group2" fill="blue" >
    <desc>Second group of two blue rectangles</desc>
    <rect x="1" y="3" width="1" height="1" />
    <rect x="3" y="3" width="1" height="1" />
  </g>
  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01" y=".01" width="4.98" height="4.98"
        fill="none" stroke="blue" stroke-width=".02" />
</svg>
    

A 'g' element can contain other 'g' elements nested within it, to an arbitrary depth. Thus, the following is possible:

Example: 05_06.svg
<?xml version="1.0"?>
<svg width="5cm" height="5cm" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny">
  <desc>Groups can nest
  </desc>
  <g>
     <g>
       <g>
       </g>
     </g>
   </g>
</svg>
    

Any element that is not contained within a 'g' is treated (at least conceptually) as if it were in its own group.

5.2.2 The 'g' element

Schema: g
  <define name='g'>
    <element name='g'>
      <ref name='g.AT'/>
      <zeroOrMore><ref name='svg.G.group'/></zeroOrMore>
    </element>
  </define>

  <define name='g.AT' combine='interleave'>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.FocusHighlight.attr'/>
    <ref name='svg.Core.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.Transform.attr'/>
  </define>
    

Attribute definitions:

focusable = "true" | "false" | "auto"
See attribute definition for description.

Animatable: Yes
Navigation Attributes
See definition.


5.3 The 'defs' element

The 'defs' element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a 'defs'.

The content model for 'defs' is the same as for the 'g' element; thus, any element that can be a child of a 'g' can also be a child of a 'defs', and vice versa.

Elements that are descendants of a 'defs' are not rendered directly; they are prevented from becoming part of the rendering tree just as if the 'defs' element were a 'g' element and the 'display' property were set to none. Note, however, that the descendants of a 'defs' are always present in the source tree and can be referenced by other elements. The actual value of the 'display' property on the 'defs' element or any of its descendants does not change the rendering of these elements or prevent these elements from being referenced.

Schema: defs
  <define name='defs'>
    <element name='defs'>
      <ref name='defs.AT'/>
      <zeroOrMore><ref name='svg.G.group'/></zeroOrMore>
    </element>
  </define>

  <define name='defs.AT' combine='interleave'>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.Core.attr'/>
  </define>
    


Creators of SVG content are encouraged to place all elements which are targets of local IRI references (except of course for animation targets) within a 'defs' element which is a direct child of one of the ancestors of the referencing element. For example:

Example: 05_10.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny" viewBox="0 0 8 3">     
  <desc>Local URI references within ancestor's 'defs' element.</desc>
  <defs>
    <linearGradient xml:id="Gradient01">
      <stop offset="0.2" stop-color="#39F" />
      <stop offset="0.9" stop-color="#F3F" />
    </linearGradient>
  </defs>
  <rect x="1" y="1" width="6" height="1" 
        fill="url(#Gradient01)"  />
  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01" y=".01" width="7.98" height="2.98"
        fill="none" stroke="blue" stroke-width=".02" />
</svg>
    

In the document above, the linear gradient is defined within a 'defs' element which is the direct child of the 'svg' element, which in turn is an ancestor of the 'rect' element which references the linear gradient. Thus, the above document conforms to the guideline.

5.4 The 'discard' element

The 'discard' element allows authors to specify the time at which particular elements are to be discarded, therefore reducing the resources required by an SVG UA. This is particularly useful for the SVG viewers to handle long-running documents. This element will not be processed by static SVG viewers.

The 'discard' element may occur wherever the animate element may.

Schema: discard
  <define name='discard'>
    <element name='discard'>
      <ref name='discard.AT'/>
      <ref name='discard.CM'/>
    </element>
  </define>

  <define name='discard.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.XLinkRequired.attr'/>
    <ref name='svg.AnimateBegin.attr'/>
  </define>

  <define name='discard.CM'>
    <zeroOrMore>
      <ref name='svg.Desc.group'/>
      <ref name='svg.Handler.group'/>
    </zeroOrMore>
  </define>
    

Attribute definitions:

xlink:href = "<iri>"
An IRI reference to the element to discard. See the definition of target element. If the attribute is not specified, the effect is as if an empty value ("") was specified.

Animatable: no.
begin = "<offset-value>" | "<syncbase-value>" | "<event-value>" | "<accessKey-value>" | "indefinite"
The 'discard' element has an implicit simple duration of 'indefinite'. As soon as the element's active duration starts, the SVG User Agent discards the element identified by the 'xlink:href' attribute. The removal operation acts as if the method removeChild were called on the parent of the target element with the target element as parameter. The SVG User Agent must remove the target node as well as all of of its attributes and descendants.

If the attribute is not specified, the effect is as if a value of "0s" were specified. This indicates that the target element should be discarded immediately.

Animatable: no.

If the target element does not exist when the 'discard' element becomes active, then the 'discard' element must be ignored.

SVG User Agents must discard an element when it is the target of a 'discard' element and the time specified by the value of the 'begin' attribute of this 'discard' element is reached. When an element is discarded, all its descendants must be discarded as well.

After removal of the target element, the 'discard' element is no longer useful. It must also be discarded following the target element removal. If the target element did not exist the 'discard' element must still be removed following activation.

Seeking backwards in the timeline must not re-insert the discarded elements. Discarded elements are intended to be completely removed from memory. So, authors are encouraged to set the 'playbackOrder' attribute to forwardOnly when using the 'discard' element.

The 'discard' element itself can be discarded prior to its activation, in which case it will never trigger the removal of its own target element. UA's must allow the 'discard' element to be the target of another 'discard' element.

The following example shows simple usage of the 'discard' element. The list below describes relevant happenings in the document timeline of this example:

At time = 0:
When the document timeline starts, the blue ellipse starts to move down the page.
At time = 1 second:
The red rectangle starts moving up the page.
At time = 2 seconds:
The aninimateTransform on the ellipse ends. The ellipse and its children are also discarded, as it is the target element of a discard with begin='2'. The green polygon starts to move across the page.
At time = 3 seconds:
The animation on the red rectangle ends. The rectangle and its children are discarded as it is the target of a discard element with begin='3'.
At time = 4 seconds:
The animation on the green triangle ends. The green polygon and its children are discarded as it is the target of a discard element with begin='4'.
Example: discard01.svg
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" 
    width="352" height="240" playbackOrder="forwardOnly">
    
    <ellipse cx="98.5" cy="17.5" rx="20.5" ry="17.5" fill="blue" stroke="black" 
        transform="translate(9 252) translate(3 -296)">
        <animateTransform attributeName="transform" begin="0s" dur="2s" fill="remove"
            calcMode="linear" type="translate" additive="sum" from="0 0" to="-18 305"/>
        <discard begin="2s"/>
    </ellipse>
    
    <rect x="182" y="-39" width="39" height="30" transform="translate(30 301)" fill="red" stroke="black">
        <animateTransform attributeName="transform" begin="1s" dur="2s" fill="remove"
            calcMode="linear" type="translate" additive="sum" from="0 0" to="-26 -304"/>
        <discard begin="3s"/>
    </rect>
    
    <polygon points="-66,83.5814 -43,123.419 -89,123.419" fill="green" stroke="black" 
        transform="matrix(1 0 0 1.1798 0 -18.6096)">
        <animateTransform attributeName="transform" begin="2s" dur="2s"
            fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0"
            to="460 63.5699"/>
        <discard begin="4s"/>
    </polygon>
</svg>
    

5.5 The 'desc' and 'title' elements

Each container element or graphics element in an SVG document may supply a 'desc' and may also supply a 'title' description. The 'desc' element contains a detailed description for the container or graphics element containing it. This description should be usable as replacement content for cases when the user cannot see the rendering of the SVG element for some reason. The 'title' element contains a short title for the container or graphics element containing it. This short title provides information supplementary to the rendering of the element, but is not sufficient to replace it. These are typically text, but can be content in other markup languages (see foreign namespaces). When the current SVG document fragment is rendered as SVG on visual media, 'desc' and 'title' elements are not rendered as part of the graphics. SVG User Agents may, however, for example, display the 'title' element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the 'desc' and 'title' elements but do not display 'path' elements or other graphics elements. For deep hierarchies, and for following use element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.

Schema: desc
  <define name='desc'>
    <element name='desc'>
      <ref name='DTM.AT'/>
      <ref name='DTM.CM'/>
    </element>
  </define>

  <define name='DTM.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
  </define>

  <define name='DTM.CM'>
    <text/>
  </define>
    
Schema: title
  <define name='desc'>
    <element name='desc'>
      <ref name='DTM.AT'/>
      <ref name='DTM.CM'/>
    </element>
  </define>
    

The following is an example. In typical operation, the SVG User Agent would not render the 'desc' and 'title' elements but would render the remaining contents of the 'g' element.

Example: 05_11.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny">
<g>
  <title>
    Company sales by region
  </title>
  <desc>
    This is a bar chart which shows 
    company sales by region.
  </desc>
  <!-- Bar chart defined as vector data -->
</g>
</svg>
    

'desc' and 'title' elements can contain marked-up text from other namespaces. Here is an example:

Example: 05_12.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" 
    version="1.2" baseProfile="tiny">
    <desc xmlns:mydoc="http://example.org/mydoc">
      <mydoc:title>This is an example SVG file</mydoc:title>
      <mydoc:para>The global description uses markup from the 
        <mydoc:emph>mydoc</mydoc:emph> namespace.</mydoc:para>
   </desc>
   <g>
   <!-- the picture goes here -->
   </g>
</svg>
    

Authors should always provide a 'title' child element to the 'svg' element within a stand-alone SVG document. The 'title' child element to an 'svg' element serves the purposes of identifying the content of the given SVG document fragment. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesnt provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, SVG User Agents should always make the content of the 'title' child element to the 'svg' element available to users (See the User Agent Accessibility Guidelines 1.0 [UAAG]). The mechanism for doing so depends on the SVG User Agent (e.g., as a caption, spoken).

It is strongly recommended that at most one 'desc' and at most one 'title' element appear as a child of any particular element, and that these elements appear before any other child elements (except possibly 'metadata' elements) or character data content. If SVG User Agents need to choose among multiple 'desc' or 'title' elements for processing (e.g., to decide which string to use for a tooltip), the user agent shall choose the first one the test attributes of which resolve to true.

5.6 The 'use' element

Any 'g' or graphics element is potentially a template object that can be re-used (i.e. "instantiated") in the SVG Document via a 'use' element, thus creating an instance tree. The 'use' element references another element and indicates that the graphical contents of that element is to be included and drawn at that given point in the document.

Unlike 'animation', the 'use' element cannot reference entire files.

Besides what is described about the 'use' element in this section important restrictions for 'use' can be found in the Reference Section.

The 'use' element has optional attributes 'x' and 'y' which are used to place the referenced element and its contents into the current coordinate system.

The effect of a 'use' element is as if the SVG Element contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the 'use' element as its parent and all of the 'use' element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the 'use' element and its attributes. The SVG DOM does not show the referenced element's contents as children of the 'use' element. The deeply-cloned tree, also refered to as the shadow tree, is then kept in synchronization with the contents of the referenced element, so that any animation or DOM manipulation occurring on the referenced element are also applied to the 'use' element's deeply-cloned tree.

Relative IRIs on nodes in shadow trees are resolved relative to any 'xml:base' on the node itself, then recursively on any 'xml:base' on their parentNode, and finally any 'xml:base' on the ownerDocument if there is no parentNode.

Property inheritance works as if the referenced element had been textually included as a deeply cloned child of the 'use' element. The referenced element inherits properties from the 'use' element and the 'use' element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.

If an event listener is registered on a referenced element, then the actual target for the event will be the SVGElementInstance object within the "instance tree" corresponding to the given referenced element.

The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the 'use' element, except that events are dispatched to the SVGElementInstance objects. The event's target and currentTarget attributes are set to the SVGElementInstance that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going to the target of the event, then bubbling back through non-exposed tree to the 'use' element and then back through regular tree to the rootmost svg element in the bubbling phase.

An element and all its corresponding SVGElementInstance objects share an event listener list. The currentTarget attribute of the event can be used to determine through which object an event listener was invoked.

The behavior of the 'visibility' property conforms to this model of property inheritance. Thus, a computed value of visibility='hidden' on a 'use' element does not guarantee that the referenced content will not be rendered. If the 'use' element has a computed value of visibility='hidden' and the element it references specifies visibility='hidden' or visibility='inherit', then that element will be hidden. However, if the referenced element instead specifies visibility='visible', then that element will be visible even if the 'use' element specifies visibility='hidden'.

Animations on a referenced element will cause the instances to also be animated.

As listed in the Reference Section the 'use' element is not allowed to reference an 'svg' element

A 'use' element has the same visual effect as if the 'use' element were replaced by the following generated content:

When a 'use' references another element which is another 'use' or whose content contains a 'use' element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in the References section.

Schema: use
  <define name='use'>
    <element name='use'>
      <ref name='use.AT'/>
      <ref name='use.CM'/>
    </element>
  </define>

  <define name='use.AT' combine='interleave'>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.FocusHighlight.attr'/>
    <ref name='svg.Core.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.Transform.attr'/>
    <ref name='svg.XLinkEmbed.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.XY.attr'/>
  </define>

  <define name='use.CM'>
    <zeroOrMore>
      <choice>
        <ref name='svg.Desc.group'/>
        <ref name='svg.Animate.group'/>
        <ref name='svg.Handler.group'/>
      </choice>
    </zeroOrMore>
  </define>
    

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the referenced element is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the referenced element is placed.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
xlink:href = "<iri>"
An IRI Reference to an element/fragment within an SVG document. An empty attribute value (xlink:href="") disables rendering of the element. If the attribute is not specified, the effect is as if an empty value ("") was specified.

Animatable: yes.
focusable = "true" | "false" | "auto"
See attribute definition for description.

Animatable: Yes
Navigation Attributes
See definition.

Below are two examples of the 'use' element, for another example see use and animation example.

Example 05_13 below has a simple 'use' on a 'rect'.

Example: 05_13.svg
<?xml version="1.0"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.2" 
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
     baseProfile="tiny">     
  <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc>
  <defs>
    <rect xml:id="MyRect" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="20" y="10" xlink:href="#MyRect" />
</svg>
    
Rendering of 05_13.svg

The visual effect would be equivalent to the following document:

Example: 05_14.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" viewBox="0 0 100 30" version="1.2" 
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
     baseProfile="tiny">
     <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc>
  <!-- 'defs' section left out -->
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,10)">
    <rect width="60" height="10"/>
  </g>
  <!-- End of generated content -->
</svg>
    

Example 05_17 illustrates what happens when a 'use' has a transform attribute.

Example: 05_17.svg
<?xml version="1.0"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.2" 
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
     baseProfile="tiny">
  <desc>Example Use03 - 'use' with a 'transform' attribute</desc>
  <defs>
    <rect xml:id="MyRect" x="0" y="0" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use xlink:href="#MyRect"
       transform="translate(20,2.5) rotate(10)" />
</svg>
    
Rendering of 05_17.svg

The visual effect would be equivalent to the following document:

Example: 05_18.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" viewBox="0 0 100 30" version="1.2" 
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
     baseProfile="tiny">
  <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc>
  <!-- 'defs' section left out -->
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,2.5) rotate(10)">
    <rect x="0" y="0" width="60" height="10"/>
  </g>
  <!-- End of generated content -->
</svg>
    


5.7 The 'image' element

The 'image' element indicates that the contents of a complete document are to be rendered into a given rectangle within the current user coordinate system. In SVG Tiny 1.2, the 'image' must reference content that is a raster image format, such as PNG and JPG. SVG Tiny 1.2 does not allow an SVG document to be referenced by the 'image' element; instead, authors should use the 'animation' element for referencing SVG Documents. Conforming SVG viewers must support PNG and JPEG image file formats. Other image file formats may be supported.

For details of the required JPEG support see the JPEG Support Appendix. PNG support is required as defined the PNG specification [PNG].

The result of processing an 'image' is always a four-channel RGBA result. When an 'image' element references a raster image file such as PNG or JPEG files which only has three channels (RGB), then the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1. For a single-channel raster image, the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

The 'image' element supports the 'opacity' property for controlling the image opacity. The 'fill-opacity' property does not affect the rendering of an image.

An 'image' element establishes a new viewport for the referenced file as described in Establishing a new viewport. The bounds for the new viewport are defined by attributes 'x', 'y', 'width' and 'height'. The placement and scaling of the referenced image are controlled by the 'preserveAspectRatio' attribute on the 'image' element.

The value of the 'viewBox' attribute to use when evaluating the 'preserveAspectRatio' attribute is defined by the referenced content. For content that clearly identifies a 'viewBox' that value should be used. For most raster content (PNG, JPEG) the bounds of the image should be used (i.e. the 'image' element has an implicit 'viewBox' of "0 0 raster-image-width raster-image-height"). Where no value is readily available the 'preserveAspectRatio' attribute is ignored and only the translate due to the 'x' and 'y' attributes of the viewport is used to display the content.

For example, if the 'image' element referenced a PNG or JPEG and preserveAspectRatio="xMinYMin meet", then the aspect ratio of the raster would be preserved (which means that the scale factor from the image's coordinates to the current user space coordinates would be the same for both X and Y), the raster would be sized as large as possible while ensuring that the entire raster fits within the viewport, and the top left of the raster would be aligned with the top left of the viewport as defined by the attributes 'x', 'y', 'width' and 'height' on the 'image' element. If the value of 'preserveAspectRatio' was 'none' then aspect ratio of the image would not be preserved. The image would be fitted such that the top/left corner of the raster exactly aligns with coordinate ('x', 'y') and the bottom/right corner of the raster exactly aligns with coordinate ('x'+'width','y'+'height').



The resource referenced by the 'image' element represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the image.

The SVG specification does not specify when an image that is not being displayed should be loaded. An SVG User Agent is not required to load image data for an image that is not displayed (e.g. is is outside the initial document viewport), except when that image is contained inside a subtree for which 'externalResourcesRequired' is set to true. However, it should be noted that this may cause a delay when an image becomes visible for the first time. In the case where an author wants to suggest that the SVG User Agent loads image data before it is displayed, they should use the 'prefetch' element.

Note that an SVG User Agent may choose to incrementally render an image as it is loading but is not required to do so.

Schema: image
  <define name='image'>
    <element name='image'>
      <ref name='image.AT'/>
      <ref name='image.CM'/>
    </element>
  </define>

  <define name='image.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.FocusHighlight.attr'/>
    <ref name='svg.Media.attr'/>
    <ref name='svg.XLinkEmbed.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.Transform.attr'/>
    <ref name='svg.Opacity.attr'/>
    <ref name='svg.XYWH.attr'/>
    <ref name='svg.PAR.attr'/>
    <ref name='svg.ContentType.attr'/>
  </define>

  <define name='image.CM'>
    <zeroOrMore>
      <choice>
        <ref name='svg.Desc.group'/>
        <ref name='svg.Animate.group'/>
        <ref name='svg.Handler.group'/>
        <ref name='svg.Discard.group'/>
      </choice>
    </zeroOrMore>
  </define>
    

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
width = "<length>"
The width of the rectangular region.

A negative value is an error (see Error processing). A value of zero disables rendering of the element. If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
height = "<length>"
The height of the rectangular region.

A negative value is an error (see Error processing). A value of zero disables rendering of the element. If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
xlink:href = "<iri>"
An IRI Reference . An empty attribute value (xlink:href="") disables rendering of the element. If the attribute is not specified, the effect is as if an empty value ("") was specified.

Animatable: yes.
type = "<media/type>"
A hint about the expected Internet Media Type of the raster image. Implementations may choose to not fetch images of formats that they do not support. Note that if an Internet Media type returned by the server, the server metadata is authoritative over the type attribute. See TAG finding Authoritative Metadata, section 5 Metadata Hints in Specifications.

Animatable: no.
focusable = "true" | "false" | "auto"
See attribute definition for description.

Animatable: Yes
Navigation Attributes
See definition.


An example:

Example: 05_21.svg
<?xml version="1.0"?>
<svg width="100%" height="100%" version="1.2" 
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
     baseProfile="tiny">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width="100" height="100"
         xlink:href="externalImage.png">
    <title>External image</title>
  </image>
</svg>
    

5.8 Conditional processing

5.8.1 Conditional processing overview

SVG contains a 'switch' element along with attributes 'requiredFeatures', 'requiredExtensions', 'systemLanguage', 'requiredFormats' and 'requiredFonts' to provide an ability to specify alternate viewing depending on the capabilities of a given SVG User Agent or the user's language.

Schema: conditional
  <define name='svg.Conditional.attr' combine='interleave'>
    <optional>
      <attribute name='requiredFeatures' svg:animatable='false' svg:inheritable='false'>
        <ref name='FeatureList.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='requiredExtensions' svg:animatable='false' svg:inheritable='false'>
        <ref name='ExtensionList.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='requiredFormats' svg:animatable='false' svg:inheritable='false'>
        <ref name='FormatList.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='requiredFonts' svg:animatable='false' svg:inheritable='false'>
        <ref name='FontList.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='systemLanguage' svg:animatable='false' svg:inheritable='false'>
        <ref name='LanguageCodes.datatype'/>
      </attribute>
    </optional>
  </define>
    

Attributes 'requiredFeatures', 'requiredExtensions', 'systemLanguage', 'requiredFormats' and 'requiredFonts' act as tests and return either true or false results. The 'switch' renders the first of its direct children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.

Example systemLanguage below displays one of three text strings (in Welsh, Greek, or Spanish) if those are the users preferred languages. Otherwise, in this example, it displays nothing.

Example: systemLanguage.svg
<?xml version="1.0" encoding="UTF-8"?>
<svg version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 170 200"
    xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>systemLanguage example</title>
    <switch>
        <g systemLanguage="cy">
            <text x="20" y="220" xml:lang="cy" font-size="20">Pam dydyn nhw ddim yn siarad
            Cymraeg?</text>
        </g>
        <g systemLanguage="el">
            <text x="20" y="220" xml:lang="el-GR" font-size="22">Μα γιατί δεν μπορούν να μιλήσουν
                Ελληνικά ;</text>
        </g>
        <g systemLanguage="es">
            <text x="20" y="220" xml:lang="es-ES" font-size="18">¿Por qué no pueden simplemente
                hablar en castellano ?</text>
        </g>
    </switch>
</svg>
    

Similar to the 'display' property, conditional processing attributes only affect the direct rendering of elements and do not prevent elements from being successfully referenced by other elements (such as via a 'use'). The conditional processing attributes in the shadow tree are processed normally. Conditional properties do not effect evaluation of 'script' elements, whose logic is run independently of conditional properties of any ancestor 'switch' elements.

Furthermore, the following rules must be applied:

5.8.2 The 'switch' element

The 'switch' element evaluates the 'requiredFeatures', 'requiredExtensions', 'systemLanguage', 'requiredFormats' and 'requiredFonts' attributes on its direct child elements in document order, and then processes and renders the first child for which all of these attributes evaluate to true. All other child elements will be bypassed and therefore not rendered. If the child element is a container element then the entire subtree is either processed and rendered or bypassed and not rendered.

Note that the values of properties 'display' and 'visibility' have no effect on 'switch' element processing. In particular, setting 'display' to none on a child of a 'switch' element has no effect on the testing associated with 'switch' element processing.

Schema: switch
  <element name='switch'>
    <ref name='switch.AT'/>
    <!-- the content model for switch is defined as part
         of the element that can contain it -->
  </element>

  <define name='switch.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.FocusHighlight.attr'/>
    <ref name='svg.External.attr'/>
    <ref name='svg.Transform.attr'/>
    <ref name='svg.Focus.attr'/>
  </define>

    

For more information and an example, see Embedding foreign object types.

Attribute definitions:

requiredFeatures = "list-of-features"
See attribute definition for description.

Animatable: no.
requiredExtensions = "list-of-extentions"
See attribute definition for description.

Animatable: no.
systemLanguage = "list-of-languages"
See attribute definition for description.

Animatable: no.
requiredFormats = "list-of-format-definitions"
See attribute definition for description.

Animatable: no.
requiredFonts = "list-of-font-names"
See attribute definition for description.

Animatable: no.
focusable = "true" | "false" | "auto"
See attribute definition for description.

Animatable: Yes
Navigation Attributes
See definition.


5.8.3 The 'requiredFeatures' attribute

Definition of 'requiredFeatures':

requiredFeatures = "list-of-features"
The value is a list of feature strings, with the individual values separated by white space. Determines whether all of the named features are supported by the SVG User Agent. Only feature strings defined in an existing version of the SVG specification at the time the document is authored (such as the current Feature String appendix) should be used, while third party extension features that are not part of an SVG standard should be indicated using the 'requiredExtensions' attribute instead. If all of the given features are supported, then the attribute evaluates to "true"; otherwise, the current element and its children are skipped and thus will not be rendered.

Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredFeatures, the attribute returns "false".

'requiredFeatures' is often used in conjunction with the 'switch' element. If the 'requiredFeatures' is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.4 The 'requiredExtensions' attribute

The 'requiredExtensions' attribute defines a list of required language extensions. Language extensions are capabilities within an SVG User Agent that go beyond the feature set defined in this specification. Each extension is identified by a IRI Reference.

Definition of requiredExtensions:

requiredExtensions = "list-of-extensions"
The value is a list of IRI References which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to "true"; otherwise, the current element and its children are skipped and thus will not be rendered.

Animatable: no.

If a given IRI Reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute 'requiredExtensions', the attribute returns "false".

'requiredExtensions' is often used in conjunction with the 'switch' element. If the 'requiredExtensions' is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.5 The 'systemLanguage' attribute

Definition of 'systemLanguage':

systemLanguage = "list-of-languages"
The value is a comma-separated list of language names as defined in [RFC3066]

Animatable: no.

Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

Multiple languages may be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within the object on which the 'systemLanguage' test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the 'systemLanguage' test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a 'switch', and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a 'switch' which is acceptable in all cases.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute "en", the attribute returns "false".

'systemLanguage' is often used in conjunction with the 'switch' element. If the "en" is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.6 The 'requiredFormats' attribute

Many resources, especially media such as audio and video, have a wide range of formats. As it is often not possible to require support for a particular format, due to legal or platform restrictions, it is often necessary to provide alternatives so that SVG User Agents can choose the format they support.

The 'requiredFormats' attribute is a generic conditional processing attribute that can be used to enable or disable particular branches in the SVG document. It defines a list of resource formats. Each format is defined by the format definition with the syntax varied according to the specific type of resource. The SVG User Agent must support all of the resource types for the attribute to evaluate to "true".

Definition of 'requiredFormats':

requiredFormats = "list-of-format-definitions"

Each format definition is separated by whitespace. A format definition can be a MIME-type beginning "image/", "video/" or "audio/", or must use one of the following formats:

image(<mime-type>):
Test the MIME-type as an image format.
video(<mime-type>):
Test the MIME-type as a video format.
audio(<mime-type>):
Test the MIME-type as an audio format.
font(<mime-type>):
Test the MIME-type as a font format.
script(<mime-type>):
Test the MIME-type as scripting language type.
foreignObject(namespaceIRI):
Test if the namespace is understood in the SVG foreignObject element.

For a list of MIME types for audio/video codecs, see the IANA registry and RFC2361.

Given that several important file formats are still not registered or not specific enough, the following format definitions are also understood:

  • font(truetype)
  • font(type1)
  • font(opentype)

The following 'requiredFormats' must always evaluate to "true" in compliant SVG viewers:

  • font(image/svg+xml)
  • image/png
  • image/jpeg
  • image/svg+xml,


Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute 'requiredFormats', the attribute returns "false". Format definitions that are not understood by the SVG User Agent return "false".

'requiredFormats' is often used in conjunction with the 'switch' element. If the 'requiredFormats' is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.7 The 'requiredFonts' attribute

If the author wishes to have complete control over the appearance and location of text in the document then they must ensure that the correct font is used when rendering the text. This can be achieved by using SVG Fonts and embedding the font in the document. However, this is not practical in all cases, especially when the number of glyphs used is very large or if the licensing of the font forbids such embedding.

Definition of 'requiredFonts':

requiredFonts = "list-of-font-names"
The 'requiredFonts' attribute is a generic conditional processing attribute that can be used to enable or disable particular branches in the SVG document. It defines a list of fonts, separated by commas. The SVG User Agent must have access to all of the fonts, either installed on the system or as an SVG font defined or embedded within the document, for the attribute to evaluate to "true". 'requiredFonts' uses same syntax as the 'font-family' property, for example when processing quoted strings, multiple, leading and trailing spaces, and case sensitivity.

Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute 'requiredFonts', the attribute returns "false".

'requiredFonts' is often used in conjunction with the 'switch' element. If the 'requiredFonts' is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.9 External Resources

5.9.1 The 'externalResourcesRequired' attribute

Documents often reference and use the contents of other document and other web resources as part of their rendering or processing. In some cases, authors want to specify that particular resources are required for a document to be considered correct.

Attribute 'externalResourcesRequired' is available on all container elements except 'defs' and on all elements which potentially can reference external resources. It specifies whether referenced resources that are not part of the current document are required for proper rendering of the given element.

Attribute definition:

externalResourcesRequired = "false" | "true"
false
(The default value.) Indicates that resources external to the current document are optional. Document rendering can proceed even if external resources are unavailable to the current element and its descendants.
true
Indicates that resources external to the current document are required. If an external resource is not available (the request for the required resource times out), progressive rendering is suspended, the document's load event is not fired and the document goes into an error state (see Error processing). The document remains in an error state until all required resources become available.

Attribute 'externalResourcesRequired' is not inheritable (from a sense of attribute value inheritance), but if set on a container element, its value will apply to all elements within the container.

Because setting externalResourcesRequired="true" on a container element can have the effect of disabling progressive display of the contents of that container, tools that generate SVG content should normally not just set externalResourcesRequired="true" on the 'svg' element on a universal basis. Instead, it is better to specify externalResourcesRequired="true" on those particular elements which specifically need the availability of external resources in order to render properly.

For externalResourcesRequired: Animatable: no.

5.9.2 Progressive Rendering

When progressively downloading a document, an SVG User Agent conceptually builds a tree of nodes in various states. The possible states for these nodes are unresolved, resolved and error.

This description uses two conceptual parsing events to simplify the prose in explaining the intended behaviour of progressive rendering. The events referred to in the following prose are the 'start element' and 'end element' events. The 'start element' event is considered to be triggered when the Start-Tag or an Empty-Element Tag is read. The 'end element' event occurs either immediately following the 'start element' event in the case of an Empty-Element Tag or when the End-Tag is read.

When loading a document following the 'start element' event on a node, that node becomes part of the document tree in the unresolved state. If the node's dependencies are successfully resolved, then the node enters the resolved state or if the node's dependencies are found to be in error, then the node enters the error state.

Node dependencies include both children content (like the child elements on a 'g') and resources (e.g. images referenced by an 'image') referenced from that node or from its children. Children become resolved when the 'end element' event occurs on an element. Resources become resolved (or found in error) by an SVG User Agent specific mechanism.

SVG User Agents must implement progressive rendering although there is no minimum rendering update frequency required for conformance. Implementations should find their own balance between processing the changes in the document tree and rendering the tree to produce a smooth rendering avoiding significant pauses. The following rules apply to progressive rendering:

Note that even if the SVG User Agent has the opportunity to update the rendering after each start/end element event there are situations where such an update shouldn't be done. E.g. 'font' element children ('font-face', 'hkern', 'missing-glyph', 'glyph') should not cause an update of the document rendering, only the 'end element' event on the 'font' element should cause a document rendering as for other node types.

Example

Example: progRend01.svg
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2"
         baseProfile="tiny" xml:id="svg-root" width="100%" height="100%" viewBox="0 0 480 360">
      <desc>externalResourcesRequired example.</desc>
      <g externalResourcesRequired="true">
         <rect xml:id="rect_1" width="5" height="7"/>
          ...
         <rect xml:id="rect_1000" width="5" height="7"/>

         <image xlink:href="myImage.png" width="5" height="7"
            externalResourcesRequired="true"/>
         <rect xml:id="rect_1001" width="5" height="7"/>
      </g>
    </svg>
    

In this example, the 'g' element rendering will start when the 'g' End-Tag has been parsed and processed and when all the resources needed by its children have been resolved. This means that the group's rendering will start when the group has been fully parsed and myImage.png has been successfully retrieved.

Forward reference of use element

Example: progRend02.svg
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2"
         baseProfile="tiny" xml:id="svg-root" width="100%" height="100%" viewBox="0 0 480 360">
      <desc>Forward reference of use element</desc>
      <use xlink:href="#myRect" x="200" fill="green"/>
      <circle cx="450" cy="50" r="50" fill="yellow" />

      <g fill="red">
         <rect xml:id="myRect" width="100" height="100" />
      </g>
    </svg>    

In this example, the various renderings will be (the rendering state follows the semi-colon):

  1. 'use'.'start element' : empty
  2. 'circle'.'start element': yellow circle
  3. 'g'.'start element': no update
  4. 'rect'.'start element' (use reference becomes resolved): green rect, yellow circle, red rect

Forward reference on 'use' with externalResourcesRequired="true"

Example: progRend03.svg
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2"
         baseProfile="tiny" xml:id="svg-root" width="100%" height="100%" viewBox="0 0 480 360">
      <desc>Forward reference on use with eRR=true</desc>
      <use xlink:href="#myGroup" x="200" fill="green"
           externalResourcesRequired="true"/>
        <circle cx="450" cy="50" r="50" fill="yellow" />

        <g fill="red">
            <g xml:id="myGroup">
                <rect xml:id="myRect" width="100" height="100" />
                <use xlink:href="#myRect" x="50" fill="purple"/>
            </g>
        </g>

    </svg>    
  1. 'use'.'start element' : empty
  2. 'circle'.'start element': empty 'use' is unresolved, externalResourcesRequired="true", rendering is stopped at the 'use')
  3. 'g'.'start element': no update
  4. g.myGroup.'start element': no update (use is resolved but externalResourcesRequired="true" so rendering will not proceed until that reference enters the resolved state)
  5. 'rect'.'start element': no update
  6. 'use'.'start element': no update
  7. g.myGroup.'end element' (#myGroup reference becomes resolved, rendering can proceed): green rect, purple rect, yellow circle, red rect, purple rect.

Forward reference with 'use' to an element under a container with externalResourcesRequired="true"

Example: progRend04.svg
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" xml:id="svg-root" width="100%" height="100%" viewBox="0 0 480 360">
      <desc>Forward Reference to a use under a container with eRR=true</desc>
      <use xlink:href="#myRect" x="200" fill="green"/>
        <circle cx="250" cy="50" r="50" fill="pink" />
        <g fill="red" externalResourcesRequired="true">
            <circle cx="450" cy="50" r="50" fill="yellow" />
            <rect xml:id="myRect" width="100" height="100" />

        </g>
</svg>
    
  1. 'use'.'start element' : empty
  2. pink.circle.'start element': pink circle
  3. 'g'.'start element': no update (rendering is suspendend because of externalResourcesRequired="true" on the 'g' element, i.e. because the children of 'g' are not resolved at the time of parsing of the start tag of 'g').
  4. yellow.circle.'start element': no update (rendering suspended because of 'g')
  5. myRect.rect.'start element': no update
  6. 'g'.'end element'. Resources referenced by 'use' become resolved and can be rendered. Rendering can proceed: green rect, pink circle, yellow circle, red rect

Font Resolution Example

Example: progRend05.svg
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2"
         baseProfile="tiny" xml:id="svg-root" width="100%" height="100%" viewBox="0 0 480 360">
     <desc>Font Resolution Example</desc>
     <text x="240" y="230" text-anchor="middle" font-size="120"
        font-family="fontC, fontB, fontA">A</text>

     <defs>
       <font xml:id="fontA" horiz-adv-x="224" >
         <font-face
            font-family="fontA"
            units-per-em="1000"
            panose-1="0 0 0 0 0 0 0 0 0 0"
            ascent="917"
            descent="-250"
            alphabetic="0" />
       <missing-glyph horiz-adv-x="800" d="..." />
        <glyph unicode="A" glyph-name="A"  d="..."/>
     </font>

     <font xml:id="fontB" horiz-adv-x="224">
       <font-face
           font-family="fontB"
           units-per-em="1000"
           panose-1="0 0 0 0 0 0 0 0 0 0"
           ascent="917"
           descent="-250"
           alphabetic="0" />

       <missing-glyph horiz-adv-x="800" d="..."/>
       <glyph unicode="A" glyph-name="B" d="..." />

     </font>

     <font xml:id="fontC" horiz-adv-x="224" >
       <font-face
           font-family="fontC"
           units-per-em="1000"
           panose-1="0 0 0 0 0 0 0 0 0 0"
           ascent="917"
           descent="-250"
           alphabetic="0" />
       <missing-glyph d="..." />
       <glyph unicode="A" glyph-name="C" d="..."/>
       </font>
     </defs>

</svg>
    

Progressive rendering:

  1. 'text'.'start element': 'A' rendered with the default font
  2. 'defs'.'start element': no update
  3. fontA.font.'start element': no update
  4. fontA.font-face.'start element': no update
  5. fontA.missingGlyph.'start element': no update
  6. fontA.glyphA.'start element': no update
  7. fontA.font.'end element': 'A' rendered with fontA (represents current document state rendering)
  8. fontB.font.'start element': no update
  9. fontB.font-face.'start element': no update
  10. fontB.missingGlyph.'start element': no update
  11. fontB.glyphA.'start element': no update
  12. fontB.font.'end element': 'A' rendered with fontB (represents current document state rendering)
  13. fontC.font.'start element': no update
  14. fontC.font-face.'start element': no update
  15. fontC.missingGlyph.'start element': no update
  16. fontC.glyphA.'start element':
  17. fontC.font.'end element': 'A' rendered with fontC (represents current document state rendering)

5.9.3 The 'prefetch' element

SVG 1.1 did not specify when an SVG User Agent should begin download referenced media. This lead to implementation differences particularly when the media was not used in the initial document state (e.g. it was offscreen or hidden). SVG 1.2 does not require SVG User Agents to download referenced media that is not visual at the time the document is loaded, unless those media are contained inside a subtree for which 'externalResourcesRequired' is set to true. This means there may be a pause to download the file the first time a piece of media is displayed. More advanced SVG User Agents may wish to predict that particular media streams will be needed and therefore download them in anticipation.

SVG 1.2 therefore adds functionality to allow content developers to suggest prefetching content from the server before it is needed to improve the rendering performance of the document. The 'prefetch' element has been reused from Section 4.4 of SMIL 2.0 (The PrefetchControl Module) with the following modifications:

The 'prefetch' element will give a suggestion or hint to a SVG User Agent that media will be used in the future and the author would like part or all of it fetched ahead of time to make the document playback smoother. As it is a hint, user-agents may ignore 'prefetch' elements, though doing so may cause an interruption in the document playback when the resource is needed. It gives authoring tools and authors the ability to schedule retrieval of resources when they think that there is available bandwidth or time to do it.

When instead of referring to external media, 'prefetch' refers to the same document it occurs in, then it can only reference a top level 'g' element. A 'top level' 'g' element is a 'g' element that is a direct child of the 'svg' element.

To enable smooth playback during progressive downloading in this scenario, it is recommended that each adjacent top level 'g' element contain adjacent chronological scenes in the animation. In this case the 'prefetch' element must appear in a 'defs' block before all defined 'g' elements in the document. In such cases, 'prefetch' is used to tell the SVG User Agent how much it needs to buffer in order to be able to play content back in a smooth and predictable manner.

Schema: prefetch
  <define name='prefetch'>
    <element name='prefetch'>
      <ref name='prefetch.AT'/>
      <ref name='prefetch.CM'/>
    </element>
  </define>

  <define name='prefetch.AT' combine='interleave'>
    <ref name='svg.Core.attr'/>
    <ref name='svg.XLinkRequired.attr'/>
    <optional>
      <attribute name='mediaSize' svg:animatable='false' svg:inheritable='false'>
        <ref name='NumberOrPercentage.datatype'/>
      </attribute>
    </optional>
    <optional>
      <attribute name='mediaTime' svg:animatable='false' svg:inheritable='false'><text/></attribute>
    </optional>
    <optional>
      <attribute name='mediaCharacterEncoding' svg:animatable='false' svg:inheritable='false'><text/></attribute>
    </optional>
    <optional>
      <attribute name='mediaContentEncodings' svg:animatable='false' svg:inheritable='false'><text/></attribute>
    </optional>
    <optional>
      <attribute name='bandwidth' svg:animatable='false' svg:inheritable='false'>
        <ref name='NumberOrPercentage.datatype'/>
      </attribute>
    </optional>
  </define>

  <define name='prefetch.CM'>
    <zeroOrMore>
      <ref name='svg.Desc.group'/>
    </zeroOrMore>
  </define>
    

Attribute definitions:

mediaSize = "<number>"
Defines how much of the media to fetch in bytes as a function of the file size of the media.

When 'prefetch' refers to a resource in the same document (i.e. a top level 'g' element), the mediaSize attribute indicates the size in bytes of the 'g' element and its children. That size corresponds to the encodings used when transmitting the document. If the document is encoded in UTF-8 [RFC 3629]and gzipped, then the size of the gzipped UTF-8 fragment applies. If that same document were decompressed and transcoded to UTF-16 [RFC 2781] the hints will become stale. Since streaming hints are to be used primarily in streaming scenarios, it is not expected that hint staleness will occur frequently.

If the attribute is not specified, the behavior is that the entire media should be fetched.

Animatable: no.
mediaTime = "<time>"
Defines how much of the media to fetch as a function of the duration of the media. For discrete media (non-time based media like image/png) using this attribute causes the entire resource to be fetched.

When 'prefetch' refers to a resource in the same document (i.e. a top level 'g' element), this is the active duration of the referenced element. In cases where the exact active duration can not be calculated before hand (e.g. end of an animation depends on user interaction), it is suggested that the content author estimate the minimum active duration for the referenced element. This estimate, even if zero, will allow the SVG User Agent to calculate how much of the overall document to download before beginning playback in a streaming scenario.

If the attribute is not specified, the behavior is that the entire media should be fetched.

Animatable: no.
bandwidth = "<number>"
Defines how much network bandwidth, in bits per second, the SVG User Agent should use when doing the prefetch. If the attribute is not specified, all available bandwidth should be used.

Animatable: no.
mediaCharacterEncoding = "<string>"
Indicates the XML character set encoding (UTF-8, ISO-8859-1, etc.) that the 'mediaSize' attribute applies to. Tools that produce SVG should include this attribute if they specify the 'mediaSize' attribute. The main use of this attribute is to know what character encoding was used when measuring 'mediaSize' so that staleness of the hints may be easily detected. If the attribute is not specified, the encoding used is that returned by the server.

Animatable: no.
mediaContentEncodings = "<list of content encodings>"
The 'mediaContentEncodings' attribute is a white space separated list of the content encodings as defined in section 3.5 of [HTTP/1.1] (gzip, compress, etc.) that the 'mediaSize' attribute applies to. The order of the list is the order in which the content encodings were applied to encode the data. Note that while situations in which multiple content codings are applied are currently rare, they are allowed by HTTP/1.1 and thus that functionality is supported by SVG. Tools that produce SVG must include this attribute if they specify the 'mediaSize' attribute and the Content-Encoding is other than the identity encoding. The main use of this attribute is to know what parameters were used when measuring 'mediaSize' so that staleness of the hints may be easily detected. If the 'mediaContentEncodings' attribute is not specified it is as if the 'identity' encoding value from HTTP/1.1 has been specified. This indicates that no transformation (i.e. encodings) at all has been used.

Animatable: no.
xlink:href = "<iri>"
An IRI reference to the resource to prefetch. An empty attribute value (xlink:href="") means that no prefetching will occur. If the attribute is not specified, the effect is as if an empty value ("") was specified.

Animatable: no.

When 'prefetch' refers to external media, if both 'mediaSize' and 'mediaTime' are specified, then 'mediaSize' is used and 'mediaTime' is ignored.

When 'prefetch' refers to a resource in the same document (i.e. a top level 'g' element), both the 'mediaSize' and 'mediaTime' attributes can be used together by a more advanced SVG User Agent to determine how much it needs to buffer in order to be able to play content back in a smooth manner.

Below is an example of the 'prefetch' element when it refers to external media:

Example: prefetch01.svg
<svg width="400" height="300" version="1.2"
        xmlns="http://www.w3.org/2000/svg" baseProfile="tiny"
        xmlns:xlink="http://www.w3.org/1999/xlink">

     <desc>
        Prefetch the large images before starting the animation
        if possible.
     </desc>

     <defs>
       <prefetch xlink:href="http://www.example.com/images/huge1.png"/>
       <prefetch xlink:href="http://www.example.com/images/huge2.png"/>
       <prefetch xlink:href="http://www.example.com/images/huge3.png"/>
     </defs>

     <image x="0" y="0" width="400" height="300"
        xlink:href="http://www.example.com/images/huge1.png"
        display="none">

        <set attributeName="display" to="inline" begin="10s"/>
 
        <animate attributeName="xlink:href" values="
               http://www.example.com/images/huge1.png;
               http://www.example.com/images/huge2.png;
               http://www.example.com/images/huge3.png"
            begin="15s" dur="30s"/>
     </image>

   </svg>    

Below is an example of the 'prefetch' element when it refers to a resource (i.e. a top level 'g' element in the same document):

Example: prefetch02.svg
<?xml version="1.0" encoding="utf-16"?>
<svg width="400" height="300" version="1.2"
        xmlns="http://www.w3.org/2000/svg" baseProfile="tiny"
        xmlns:xlink="http://www.w3.org/1999/xlink"
        timelineBegin="onStart"
        playbackOrder="forwardOnly">

     <desc>
        Example of using SVGT 1.2 features for smooth playback
        during progressive downloading.
     </desc>

     <defs>

       <prefetch xlink:href="#scene1"
                 mediaCharacterEncoding="UTF-16"
                 mediaTime="5s" mediaSize="94230" />

       <prefetch xlink:href="#scene2"
                 mediaCharacterEncoding="UTF-16"
                 mediaTime="10s" mediaSize="283474" />

       <prefetch xlink:href="#scene3"
                 mediaCharacterEncoding="UTF-16"
                 mediaTime="5s" mediaSize="62763" />

     </defs>

     <g id="scene1">
       <discard begin="6s"/>
       <!-- graphics for scene 1 go here -->
     </g>

     <g id="scene2">
       <discard begin="16s"/>
       <!-- graphics for scene 2 go here -->
     </g>

     <g id="scene3">
       <discard begin="21s"/>
       <!-- graphics for scene 3 go here -->
     </g>

</svg>
    

5.10 Common attributes

5.10.1 Attributes common to all elements: 'class', 'id', 'xml:id' and 'xml:base'

The 'class', 'id', 'xml:id' and 'xml:base' attributes are available on all elements required by SVG Tiny 1.2:

Attribute definitions:

class = "list"
This attribute indicates membership in one or more sets. Multiple set names must be separated by white space characters.

Animatable: yes.
id = "name"
XML attribute for assigning a unique name to an element. Refer to the "Extensible Markup Language (XML) 1.1" Recommendation [XML11]. It is recommended that new content should use 'xml:id' instead.

Animatable: no.
xml:id = "name"
Standard XML attribute for assigning a unique name to an element. Refer to the "xml:id Version 1.0" [xml:id]. Recommended for new content.

Animatable: no.
xml:base = "<iri>"
Specifies a base IRI other than the base IRI of the document or external entity. Refer to the "XML Base" specification [XML-BASE].

Animatable: no.

It is strongly recommended that SVG Generators only use 'xml:id' to assign identity to elements. For backwards compatibility purposes, one may also specify the 'id' attribute but such an approach is not without issues:

5.10.2 The 'xml:lang' and 'xml:space' attributes

Elements that might contain character data content have attributes 'xml:lang' and 'xml:space':

Schema: langspace
<attribute name='xml:space' svg:animatable='false' svg:inheritable='false'>
   <choice>
      <value>default</value>
      <value>preserve</value>
   </choice>
</attribute>

<attribute name='xml:lang' svg:animatable='false' svg:inheritable='false'>
  <choice>
     <ref name='LanguageCode.datatype'/>
     <empty/>
  </choice>
</attribute>
    

Attribute definitions:

xml:lang = "<languageID>"
Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. The value is either a language tag as defined in IETF Best Current Practice 47 [BCP 47] or the empty string, "". Refer to the "Extensible Markup Language (XML) 1.1" Recommendation [XML11].

Animatable: no.
xml:space = "default" | "preserve"
Standard XML attribute to specify whether white space is preserved in character data. The only possible values are default and preserve. Refer to the "Extensible Markup Language (XML) 1.1" Recommendation [XML11] and to the discussion White space handling in SVG.

Animatable: no.


5.11 Core Attribute Module

The Core Attribute Module contains the following attributes:

[RNG] [Feature String]

5.12 Structure Module

The Structure Module contains the following elements:

[RNG] [Feature String]

5.13 Conditional Processing Module

The Conditional Processing Module contains the following element:

[RNG] [Feature String]

5.14 Conditional Processing Attribute Module

The Conditional Processing Attribute Module contains the following attributes:

[RNG] [Feature String]

5.15 Image Module

The Image Module contains the following element:

[RNG] [Feature String]

5.16 Prefetch Module

The Prefetch Module contains the following element:

[RNG] [Feature String]

5.17 Discard Module

The Discard Module contains the following element:

[RNG] [Feature String]

5.18 ExternalResourcesRequired Attribute Module

The ExternalResourcesRequired Attribute Module contains the following attributes:

[RNG] [Feature String]