Xorn/gEDA XML schematic format

Xorn implements an alternative, XML-based file format for gEDA schematic and symbol files. This is basically a verbose form of the original gEDA file format. For example,

B 0 0 17000 11000 15 0 0 0 -1 -1 0 -1 -1 -1 -1 -1

becomes

<box x="0" y="0" width="170" height="110" color="lock" width="0"/>

However, there are some moderate changes to the format with the intention to make the files more exactly represent what Xorn sees, make the file format more readable, and make working with the files a bit easier:

• Symbols and pixmaps aren't embedded directly into the object but are defined once at the beginning of the file and then referenced by ID. This allows multiple component/picture objects to share the same embedded symbol/pixmap.
• Non-embedded symbols and pixmaps are optionally included in the file, as well. This way, the file can be used without the original dependencies at hand while updates in the library are still propagated to the schematic.
• Coordinates are represented as fixed-point values; a value of “12345” becomes “123.45”. Floating-point values are supported by Xorn but are rounded to the nearest integer when saving to a file. The XML format has an optional hybridnum feature which allows preserving the fractional part; since it can't be represented exactly in base 10, it's appended in hexadecimal notation after the fixed-point part, so a value of “12345.75” would become “123.45:c”.
• Fields which have a default value are optional.
• Pin objects don't have a whichend flag; the first coordinate is always the end which connects to nets. In order to allow an exact SCH->XML->SCH round-trip, there is an additional flag inverted which tells whether the pin should be inverted when stored to a .sch or .sym file but isn't of any relevance otherwise.
• Busses don't have a ripperdir field as this can be deduced from the existing ripper components' orientation.
• Text objects which are considered attributes by libgeda are represented by a special <attribute name="...">...</attribute> element. In the future, this could allow non-attribute texts to contain “=” characters as well as arbitrary attribute names/values without concern for gEDA attribute splitting rules. Also, it makes automatic processing of the attributes easier.

To convert a .sch or .sym file to an XML file, use xorn convert:

$ xorn convert resistor-1.sym resistor-1.sym.xml

and vice versa. Since the format is automatically guessed from the file name, you'll have to specify the format explicitly when reading from stdin or writing to stdout:

$ xorn convert -I sym -O symxml < resistor-1.sym > resistor-1.sym.xml

When converting .sch files to XML files, the symbols and pixmaps referenced by the schematic are included in the XML file by default. In order to make this possible, you'll need to specify the symbol library directories:

$ xorn convert --symbol-library=sym/
               --symbol-library-search=/path/to/library/
    example.sch example.sch.xml

When using the default library included with gEDA, you can't use --symbol-library-search=, unfortunately, because it contains symbol name conflicts.

If you don't want to include referenced symbols and pixmaps in the XML file—for example, because you are keeping everything under version control and want to minimize changes—you can pass the options --omit-symbols and --omit-pixmaps:

$ xorn convert --omit-symbols example.sch example.sch.xml

File format features

Instead of a sequential file format version, this format uses file format features. The names of the features used in a file are specified as a space-separated list in the attribute file-format-features of the root element of the document. Currently, the following file format features are defined:

hybridnum

Coordinates and lengths are specified in a hybrid fixed/floating point number format. For example, the value "400" would be represented as "4.00" which can be abbreviated as "4", and the value "0.75" would be represented as "0.00:c" which can be abbreviated as ":c".

experimental

Indicates that the file format is experimental and should not be relied upon for productive purposes. Non-experimental versions of the package will refuse to parse a file with this feature.

File structure

At the root of the XML document is either a schematic or a symbol element, depending on the file type. It contains a content element which in turn contains all objects in the file. Additionally, for each symbol or pixmap which is referenced or embedded in the file, the root element contains a symbol or pixmap element, respectively.

<?xml version="1.0" encoding="UTF-8"?>
<schematic xmlns="https://hedmen.org/xorn/schematic/"
           file-format-features="experimental hybridnum">
  <content>
    ...
  </content>

  <symbol id="resistor-1" name="resistor-1.sym" mode="referenced">
    <content>
      ...
    </content>
  </symbol>

  ...
</schematic>

Elements

Root element (schematic or symbol)

The format is the same for schematic and symbol files, but gEDA imposes additional restrictions. For example, pin objects are only allowed in symbol files, and net, bus, and component objects are only allowed in schematic files. Therefore, it doesn't make sense for a symbol root element to contain symbol reference elements.

attribute	value
xmlns	https://hedmen.org/xorn/schematic/
file-format-features	space-separated list of feature names

Reference element (symbol or pixmap)

In contrast to the original .sym/.sch file format, symbols and pixmaps aren't directly specified by their file name. Instead, the component or picture element contains a symbol ID or pixmap ID which points to a symbol or pixmap reference element, respectively. The reference element contains the actual file name and/or the embedded file contents.

attribute	description
id	arbitrary unique string which identifies this element
name	file name (optional if mode is embedded)
mode	reference mode

There are three possible reference modes:

mode	description
referenced	The actual symbol or pixmap is found in the referenced file, but the contents of that file are included in case the file is lost, to be able to distribute the schematic as a single file, and to be able to detect and print a warning if the file has been modified.
omitted	Same as referenced, but the contents of the file aren't included (for use with source code management).
embedded	The contents of the symbol or pixmap are embedded. The original file name may or may not be specified for informational purposes.

The way how the contents of the referenced file are included is different for symbols and pixmaps. For symbols, the symbol element contains a content element which in turn contains all objects in the symbol. For pixmaps, the pixmap element contains the base64-encoded pixmap file as character data.

content

Contains an element for each top-level object in the file. Does not have any attributes.

Line attributes

attribute	type	default	valid
linewidth	fixed-point number	0	always
capstyle	cap style value	none	always
dashstyle	dash style value	solid	always
dashlength	fixed-point number	—	dash styles dashed, center, and phantom only
dashspace	fixed-point number	—	dash styles dotted, dashed, center, and phantom only

Fill attributes

attribute	type	default	valid
filltype	fill type value	hollow	always
fillwidth	fixed-point number	—	fill styles mesh and hatch only
angle0	integer	—	fill styles mesh and hatch only
pitch0	fixed-point number	—	fill styles mesh and hatch only
angle1	integer	—	fill style mesh only
pitch1	fixed-point number	—	fill style mesh only

arc

attribute	type	default
x	fixed-point number	—
y	fixed-point number	—
radius	fixed-point number	—
startangle	integer	—
sweepangle	integer	—
color	color value	graphic

+ line attributes

box

attribute	type	default
x	fixed-point number	—
y	fixed-point number	—
width	fixed-point number	—
height	fixed-point number	—
color	color value	graphic

+ line attributes + fill attributes

circle

attribute	type	default
x	fixed-point number	—
y	fixed-point number	—
radius	fixed-point number	—
color	color value	graphic

+ line attributes + fill attributes

component

attribute	type	default
x	fixed-point number	—
y	fixed-point number	—
selectable	boolean value	yes
angle	0, 90, 180 or 270	0
mirror	boolean value	no
symbol	symbol ID	—

Contains a text or attribute child element for each attached object.

line

attribute	type	default
x0	fixed-point number	—
y0	fixed-point number	—
x1	fixed-point number	—
y1	fixed-point number	—
color	color value	graphic

+ line attributes

net and pin

attribute	type	default	applies to
x0	fixed-point number	—	all
y0	fixed-point number	—	all
x1	fixed-point number	—	all
y1	fixed-point number	—	all
color	color value	net, bus, or pin, respectively	all
type	net/pin type value	normal	all
inverted	boolean value	no	pin element only

Contains a text or attribute child element for each attached object.

path

attribute	type	default
color	color value	graphic

+ line attributes + fill attributes

Contains the path data as character data. Preserves whitespace.

br

Represents a line break inside a path element. This has the same effect as any other whitespace but allows preserving the structure of path data in a .sym/.sch file. Does not have any attributes.

picture

attribute	type	default
x	fixed-point number	—
y	fixed-point number	—
width	fixed-point number	—
height	fixed-point number	—
angle	0, 90, 180 or 270	0
mirrored	boolean value	no
pixmap	pixmap ID	—

text and attribute

Text objects which can be interpreted as attributes are represented as attribute elements rather than text elements.

attribute	type	default	applies to
name	string	—	attribute element only
x	fixed-point number	—	all
y	fixed-point number	—	all
color	color value	text or attribute, respectively	all
size	integer	—	all
visible	boolean value	yes (text element only)	all
show	show name/value value	name-value (text element only)	all
angle	0, 90, 180 or 270	0	all
alignment	alignment value	lower-left	all

Contains the text or attribute value, respectively, as character data.

br

Represents a line break inside a text or attribute element. Does not have any attributes.

overbar

Represents a section of text or attribute value which should be rendered with a line over the letters. (This usually indicates an inverted logic level.) Does not have any attributes.

Enumeration values

Boolean

#	value
0	no
1	yes

Line cap style

#	value
0	none
1	square
2	round

Line dash style

#	value
0	solid
1	dotted
2	dashed
3	center
4	phantom

Fill type

#	value
0	hollow
1	fill
2	mesh
3	hatch
4	void

Show attribute name/value

#	value
0	name-value
1	value
2	name

Text alignment

#	value
0	lower-left
1	middle-left
2	upper-left
3	lower-middle
4	middle-middle
5	upper-middle
6	lower-right
7	middle-right
8	upper-right

Net/pin type

#	value
0	normal
1	bus

Color

#	value
0	background
1	pin
2	net-endpoint
3	graphic
4	net
5	attribute
6	logic-bubble
7	dots-grid
8	detached-attribute
9	text
10	bus
11	select
12	boundingbox
13	zoom-box
14	stroke
15	lock
16	output-background
17	freestyle1
18	freestyle2
19	freestyle3
20	freestyle4
21	junction
22	mesh-grid-major
23	mesh-grid-minor

---

Copyright (C) 2013-2016 Roland Lutz

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.