3 SVG Document Structure


Contents


 

3.1 Defining an SVG document: the <svg> element

3.1.1 Overview

An SVG document is contained within an <svg> element, which is required to be the outermost element in an SVG document.

An SVG "document" can range from a single SVG graphics element such as a <rect> to a complex, deeply nested collection of container elements and graphics elements. Also, an SVG document can be embedded inline as a fragment within a parent document (an expectedly common situation within XML Web pages) or it can stand by itself as a self-contained graphics file.

The following example shows a simple SVG document embedded 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:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://someplace.org"
       xmlns:svg="http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
   <!-- parent stuff here -->
   <svg:svg width="5cm" height="8cm">
      <svg:ellipse rx="200" ry="130" />
   </svg:svg>
   <!-- ... -->
</parent>

Download this example

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

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Four separate rectangles
  </desc>
    <rect width="20" height="60"/>
    <rect width="30" height="70"/>
    <rect width="40" height="80"/>
    <rect width="50" height="90"/>
</svg>

Download this example

<svg> elements can appear in the middle of SVG documents. This is the mechanism by which SVG documents can be embedded within other SVG documents.

Another use for <svg> elements within the middle of SVG documents is to establish a new viewport and alter the meaning of CSS unit specifiers. See Establishing a New Viewport: the <svg> element within an SVG document and Redefining the meaning of CSS unit specifiers.

3.1.2 The <svg> element

<!ELEMENT svg (defs?,desc?,title?,
                  (path|text|rect|circle|ellipse|line|polyline|polygon|
                   use|image|svg|g|switch|a)*)>
<!ATTLIST svg
  xmlns CDATA #FIXED 'http://www.w3.org/Graphics/SVG/SVG-19990812.dtd'
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  %graphicsElementEvents;
  %documentEvents;
  system-required CDATA #IMPLIED
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #REQUIRED
  height CDATA #REQUIRED
  refX CDATA #IMPLIED
  refY CDATA #IMPLIED
  viewBox CDATA #IMPLIED
  preserveAspectRatio CDATA 'xMidYMid meet'
  allowZoomAndPan (true | false) "true" 
  contentScriptType CDATA #IMPLIED >

Attribute definitions:

xmlns [:prefix] = "resource-name"
Standard XML attribute for identifying an XML namespace. Refer to the "Namespaces in XML" Recommendation [XML-NS].
id = "name"
Standard XML attribute for assigning a unique name to an element. Refer to the the "Extensible Markup Language (XML) 1.0" Recommendation [XML10].
xml:lang = "languageID"
Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. Refer to the "Extensible Markup Language (XML) 1.0" Recommendation [XML10].
xml:space = "{default | preserve}"
Standard XML attribute to specify whether white space should be preserved in character data. The only possible values are default and preserve. Refer to the "Extensible Markup Language (XML) 1.0" Recommendation [XML10] and to the discussion white space handling in SVG.
x = "x-coordinate"
(Ignored for outermost <svg> elements.) The x-coordinate of one corner of the rectangular region into which an embedded <svg> element should be placed. The default x-coordinate is zero. See Coordinate Systems, Transformations and Units.
y = "y-coordinate"
(Ignored for outermost <svg> elements.) The y-coordinate of one corner of the rectangular region into which an embedded <svg> element should be placed. The default y-coordinate is zero. See Coordinate Systems, Transformations and Units.
width = "length"
For outermost <svg> elements, the intrinsic width of the SVG document, with length being any valid expression for a length in SVG. For embedded <svg> elements, the width of the rectangular region into which the <svg> element should be placed.
height = "length"
For outermost <svg> elements, the intrinsic height of the SVG document, with length being any valid expression for a length in SVG. For embedded <svg> elements, the height of the rectangular region into which the <svg> element should be placed.
refX = "x-coordinate"
When referenced in the context that requires a reference point (e.g., a motion path animation), the x-coordinate of the reference point.
refY = "y-coordinate"
When referenced in the context that requires a reference point (e.g., a motion path animation), the y-coordinate of the reference point.

Attributes defined elsewhere:
class, style, %graphicsElementEvents;, %documentEvents;, system-required, viewBox, preserveAspectRatio, allowZoomAndPan, contentScriptType.

 

3.2 Grouping and Naming Collections of Drawing Elements: the <g> element

3.2.1 Overview

The <g> element is the element for grouping and naming collections of drawing elements. If several drawing elements share similar attributes, they can be collected together using a <g> element. For example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Two groups, each of two rectangles
  </desc>
  <g style="fillcolor:red">
    <rect x="100" y="100" width="100" height="100" />
    <rect x="300" y="100" width="100" height="100" />
  </g>
  <g style="fillcolor:blue">
    <rect x="100" y="300" width="100" height="100" />
    <rect x="300" y="300" width="100" height="100" />
  </g>
</svg>

Download this example

A group of drawing elements, as well as individual objects, can be given a name. Named groups are needed for several purposes such as animation and re-usable objects. The following example organizes the drawing elements into two groups and assigns a name to each group:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Two named groups
  </desc>
  <g id="OBJECT1">
    <rect x="100" y="100" width="100" height="100" />
  </g>
  <g id="OBJECT2">
    <circle cx="150" cy="300" r="25" />
  </g>
</svg>

Download this example

A <g> element can contain other <g> elements nested within it, to an arbitrary depth. Thus, the following is valid SVG:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Groups can nest
  </desc>
  <g>
     <g>
       <g>
       </g>
     </g>
   </g>
</svg>

Download this example

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

3.2.2 The <g> element

<!ELEMENT g (defs?,desc?,title?,
                  (path|text|rect|circle|ellipse|line|polyline|polygon|
                   use|image|svg|g|switch|a|
                   animate|animateTransform|animateColor)*)>
<!ATTLIST g
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  transform CDATA #IMPLIED
  %graphicsElementEvents;
  system-required CDATA #IMPLIED>

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, transform, %graphicsElementEvents;, system-required.

3.3 References and the <defs> element

3.3.1 Overview

SVG makes extensive use of URI references [URI] to other objects. For example, to fill a rectangle with a linear gradient, you first define a <linearGradient> element and give it an ID, as in:

<linearGradient id="MyGradient">...</linearGradient>

You then reference the linear gradient as the value of the 'fill' property for the rectangle, as in:

<rect style="fill:url(#MyGradient)"/>

In SVG, among the facilities that allow URI references are:

URI references are defined in either of the following forms:

<URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#" <elementID> ]    -or-
<URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#xptr(id(" <elementID> "))" ]

where <elementID> is the ID of the referenced element.

(Note that the two forms above (i.e., #<elementID> and #xptr(id(<elementID>))) are formulated in syntaxes compatible with "XML Pointer Language (XPointer)" [XPTR]. These two formulations of URI references are the only XPointer formulations that are required in SVG 1.0 user agents.)

SVG supports two types of URI references:

The following rules apply to the processing of URI references:

Invalid references should be treated as if no value were provided for the referencing attribute or property. For example, if there is no element with ID "BogusReference" in the current document, then fill="url(#BogusReference)" would represent an invalid reference. In cases like this, the element should be processed as if no 'fill' property were provided. In those cases where a list of property values are possible and one of the property values is an undefined reference, then the list will be processed as if the invalid reference were removed from the list.

3.3.2 URI reference attributes


 
  xmlns:xlink CDATA #FIXED "http://www.w3.org/XML/XLink/0.9"
  xlink:type (simple|extended|locator|arc) #FIXED "simple" 
  xlink:role CDATA #IMPLIED
  xlink:title CDATA #IMPLIED
  xlink:show (new|parsed|replace) #FIXED 'parsed'
  xlink:actuate (user|auto) #FIXED 'auto'
  xlink:href CDATA #REQUIRED
xmlns [:prefix] = "resource-name"
Standard XML attribute for identifying an XML namespace. This attribute makes the XLink [XLink] namespace available to the current element. Refer to the "Namespaces in XML" Recommendation [XML-NS].
xlink:type = 'simple'
Identifies the type of XLink being used. For hyperlinks in SVG, only simple links are available. Refer to the "XML Linking Language (XLink)" [XLink].
xlink:role = '<string>'
A generic string used to describe the function of the link's content. Refer to the "XML Linking Language (XLink)" [XLink].
xlink:title = '<string>'
Human-readable text describing the link. Refer to the "XML Linking Language (XLink)" [XLink].
xlink:show = 'parsed'
Indicates that upon activation of the link the contents of the referenced object are incorporated appropriately into the current SVG document. Refer to the "XML Linking Language (XLink)" [XLink].
xlink:actuate = 'auto'
Indicates that the contents of the referenced object are incorporated into the current document automatically (i.e., without user action). Refer to the "XML Linking Language (XLink)" [XLink].
xlink:href = "<URI-reference>"
The location of the referenced object, expressed as a <URI-reference>. Refer to the "XML Linking Language (XLink)" [XLink].

3.3.3 The <defs> element

The <defs> element is used to identify those objects which will be referenced by other objects later in the document. It is a requirement that all referenced objects be defined within a <defs> element. (See References and the <defs> element.)

The child elements within a <defs> element are not drawn.

<!ELEMENT defs (script|style|symbol|marker|clipPath|mask|
                linearGradient|radialGradient|pattern|filter|cursor|font|
                animate|animateMotion|animateTransform|animateColor|animateFlipbook|
                path|text|rect|circle|ellipse|line|polyline|polygon|
                use|image|svg|g|switch)* >
<!ATTLIST defs
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED>

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style.

To provide some SVG user agents with an opportunity to implement efficient implementations in streaming environments, creators of SVG documents are encouraged to place all elements which are targets of local URI references within a <defs> element which is a direct child of one of the ancestors of the referencing element. For example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Local URI references within ancestor's <defs> element.</desc>
  <defs>
    <linearGradient id="Gradient01">
      <stop offset="30%" style="color:#39F"/>
    </linearGradient>
  </defs>
  <g>
    <g>
      <rect x="0%" y="0%" width="100%" height="100%" 
            style="fill:url(#Gradient01)" />
    </g>
  </g>
</svg>

Download this example

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.

3.4 The <desc> and <title> elements

Each container element or graphics element in an SVG drawing can supply a <desc> and/or a <title> description string where the description is text-only. These description strings provide information about the graphics to visually impaired users. User agents which can process SVG in most cases will ignore the description strings (except that the <title> might be used to provide a tooltip).

The following is an example. In typical operation, the SVG user agent would ignore (i.e., not display) the <desc> element and the <title> elements and would render the remaining contents of the <g> element.

If this file were processed by an older browser (i.e., a browser that doesn't have SVG support), then the browser would treat the file as HTML. All SVG elements would not be recognized and therefore ignored. The browser would render all character data (including any character data within <desc> and <title> elements) within the current text region using current text styling parameters.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg SYSTEM "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
<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>

Download this example

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

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in" 
 xmlns="http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
   <desc xmlns:mydoc="http://foo.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>

Download this example


3.5 The <symbol> element

The <symbol> element is used to define graphical objects which are meant for any of the following uses:

Closely related to the <symbol> element are the <marker> and <pattern> elements.
 
<!ELEMENT symbol (defs?,desc?,title?,
                  (path|text|rect|circle|ellipse|line|polyline|polygon|
                   use|image|svg|g|switch|a|
                   animate|animateTransform|animateColor)*)>
<!ATTLIST symbol
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  refX CDATA #IMPLIED
  refY CDATA #IMPLIED
  viewBox CDATA #IMPLIED
  preserveAspectRatio CDATA 'xMidYMid meet' >


Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, refX, refY, viewBox, preserveAspectRatio.

3.6 The <use> element

Any <svg>, <symbol>, <g>, or graphics element that is a child of a <defs> element and has been assigned an ID is potentially a template object that can be re-used (i.e., "instanced") anywhere in the SVG document via a <use> element. The <use> element references another element and indicates that the graphical contents of that element should be included/drawn at that given point in the document.

The <use> element can reference either:

Unlike <image>, the <use> element cannot reference entire files.

In the example below, the first <g> element has inline content. After this comes a <use> element whose href value indicates which graphics element should be included/rendered at that point in the document. Finally, the second <g> element has both inline and referenced content. In this case, the referenced content will draw first, followed by the inline content.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs>
    <symbol id="TemplateObject01">
      <!-- symbol definition here -->
    </symbol>
  </defs>

  <desc>Examples of inline and referenced content
  </desc>
  
  <!-- <g> with inline content -->
  <g>
    <!-- Inline content goes here -->
  </g>

  <!-- referenced content -->
  <use xlink:href="#TemplateObject01" />

  <!-- <g> with both referenced and inline content -->
  <g>
    <use xlink:href="#TemplateObject01" />
    <!-- Inline content goes here -->
  </g>
</svg>

Download this example

The <use> element has optional attributes x, y, width and height which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.

The effect of a <use> element is as if the 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 <use> element.

Property inheritance, however, 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 its original parents.

The following example illustrates property inheritance with the <use> element:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs style="stroke:green">
    <!-- Note that parent's stroke:green will be ignored below -->
    <circle id="TemplateObject02" cx="50" cy="50" r="30" style="fill:red" />
  </defs>

  <desc>Examples of <use> property inheritance
  </desc>
  
  <g style="fill:yellow;stroke:blue" >
    <!-- Draws a circle with fill:red and stroke:blue. -->
    <!-- Note that the referenced element specifies fill:red,
         which takes precedence over the inherited fill:yellow. -->
    <use xlink:href="#TemplateObject02" />
  </g>
</svg>

Download this example

In the example above, property inheritance for <use> element shown above is as if the <use> element were replaced a container object which contents are the referenced element:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs style="stroke:green">
    <!-- Note that parent's stroke:green will be ignored below -->
    <circle id="TemplateObject02" cx="50" cy="50" r="30" style="fill:red" />
  </defs>

  <desc>Examples of <use> property inheritance
  </desc>
  
  <g style="fill:yellow;stroke:blue" >
    <!-- Draws a circle with fill:red and stroke:blue. -->
    <!-- Note that the referenced element specifies fill:red,
         which takes precedence over the inherited fill:yellow. -->
    <g>
      <circle cx="50" cy="50" r="30" style="fill:red" />
    </g>
  </g>
</svg>

Download this example


 
<!ELEMENT use (desc?,title?,(animate|animateTransform|animateColor)*) >
<!ATTLIST use
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  transform CDATA #IMPLIED
  %graphicsElementEvents;
  system-required CDATA #IMPLIED
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #IMPLIED
  height CDATA #IMPLIED
  xmlns:xlink CDATA #FIXED "http://www.w3.org/XML/XLink/0.9"
  xlink:type (simple|extended|locator|arc) #FIXED "simple" 
  xlink:role CDATA #IMPLIED
  xlink:title CDATA #IMPLIED
  xlink:show (new|parsed|replace) #FIXED 'parsed'
  xlink:actuate (user|auto) #FIXED 'auto'
  xlink:href CDATA #REQUIRED >

Attribute definitions:

x = "x-coordinate"
The x-coordinate of one corner of the rectangular region into which the referenced element should be placed. The default x-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
y = "y-coordinate"
The y-coordinate of one corner of the rectangular region into which the referenced element should be placed. The default y-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
width = "length"
The width of the rectangular region into which the referenced element should be placed. (??? Default value?) (??? Needs to be expanded to take care of referencing graphics elements.)
height = "length"
The height of the rectangular region into which the referenced element should be placed. (??? Default value?) (??? Needs to be expanded to take care of referencing graphics elements.)
href = "uri-reference"
A URI reference to an element/fragment within an SVG document.

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, transform, %graphicsElementEvents;, system-required, xmlns:xlink, xlink:type, xlink:role, xlink:title, xlink:show, xlink:actuate.

3.7 The <image> element

The <image> element indicates that the contents of a complete file should be rendered into a given rectangle within the current user coordinate system. The <image> element can refer to raster image files such as PNG or JPEG or to files with MIME type of "image/svg". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files.

Unlike <use>, the <image> element cannot reference elements within an SVG file.
 
<!ELEMENT image (desc?,title?,(animate|animateTransform)*) >
<!ATTLIST image
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  transform CDATA #IMPLIED
  %graphicsElementEvents;
  system-required CDATA #IMPLIED
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #REQUIRED
  height CDATA #REQUIRED
  xmlns:xlink CDATA #FIXED "http://www.w3.org/XML/XLink/0.9"
  xlink:type (simple|extended|locator|arc) #FIXED "simple" 
  xlink:role CDATA #IMPLIED
  xlink:title CDATA #IMPLIED
  xlink:show (new|parsed|replace) #FIXED 'parsed'
  xlink:actuate (user|auto) #FIXED 'auto'
  xlink:href CDATA #REQUIRED >

Attribute definitions:

x = "x-coordinate"
The x-coordinate of one corner of the rectangular region into which the referenced document should be placed. The default x-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
y = "y-coordinate"
The y-coordinate of one corner of the rectangular region into which the referenced document should be placed. The default y-coordinate is zero. See Coordinate Systems, Transformations and Units. (??? Needs to be expanded to take care of referencing graphics elements.)
width = "length"
The width of the rectangular region into which the referenced document should be placed.
height = "length"
The height of the rectangular region into which the referenced document should be placed.
href = "uri-reference"
A URI reference.

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, transform, %graphicsElementEvents;, xmlns:xlink, xlink:type, xlink:role, xlink:title, xlink:show, xlink:actuate.

A valid example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width"100px" height="100px"
         xlink:href="myimage.png">
    <title>My image</title>
  </image>
</svg>

Download this example

A well-formed example:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
 xmlns='http://www.w3.org/Graphics/SVG/SVG-19990812.dtd'>
  <desc>This links to an external image
  </desc>
  <image x="200" y="200" width"100px" height="100px"
         xlink:type="simple" xlink:show="replace" xlink:actuate="user" 
         xlink:href="myimage.png">
    <title>My image</title>
  </image>
</svg>

Download this example