Sieve Email Filtering:
Sieves and display directives in XML
Sun Microsystems800 Royal OaksMonroviaCA91016-6347USA+1 909 457 4293ned.freed@mrochek.comSun Microsystems+91 80669 27577Srinivas.Sv@Sun.COM
Applications
RFCRequest for CommentsSMTPESMTPSieveI-DInternet-Draft
This document describes a way to represent Sieve email filtering language
scripts in XML. Representing sieves in XML is intended not as an alternate
storage format for Sieve but rather as a means to facilitate manipulation of
scripts using XML tools.
The XML representation also defines additional elements that have no
counterparts in the regular Sieve language. These elements are intended for
use by graphical user interfaces and provide facilities for labeling or
grouping sections of a script so they can be displayed more conveniently.
These elements are represented as specially structured comments in regular
Sieve format.
Changed representation of comments in XML to use a comment element.
Update references.
Added an IANA registration of a URN for the Sieve namespace.
Updated XML Schema to allow largely unrestricted use of material in
other namespaces.
Add compact Relax NG schema.
Updated example stylesheet to handle material in other namespaces.
Corrected stylesheet handling of <comment> elements.
Added a section defining the structured comment convention.
Moved the examples section to an appendix.
Added text to clarify that the examples in the various appendices are in fact
code components and may therefore be reused.
Added a section on validation requirements.
Clarified various editor requirements and trust issues, restricted the
use of "*/" in non-Sieve XML content.
Added XML reference.
Sieve is a language for filtering email
messages at or around the time of final delivery. It is designed to be
implementable on either a mail client or mail server. It is meant to be
extensible, simple, and independent of access protocol, mail architecture,
and operating system and it is intended to be manipulated by
a variety of different user interfaces.
Some user interface environments have extensive existing facilities
for manipulating material represented in XML.
While adding support for
alternate data syntaxes may be possible in most if not all of these
environments, it may not be particularly convenient to do so. The obvious
way to deal with this issue is to map sieves into XML, possibly on a separate
backend system, manipulate the XML, and convert it back to normal Sieve
format.
The fact that conversion into and out of XML may be done as a separate
operation on a different system argues strongly for defining a common XML
representation for Sieve. This way different front end user interfaces can be
used with different back end mapping and storage facilities.
Another issue with the creation and manipulation of sieve scripts by
user interfaces is that the language is strictly focused on
describing email filtering operations. The language contains no mechanisms for
indicating how a given script should be presented in a user interface. Such
information can be represented in XML very easily so it makes sense to define a
framework to do this as part of the XML format. A structured comment convention
is then used to retain this information when the script is converted to normal
Sieve format.
Various sieve extensions have already been defined, e.g.,
,
and more are planned. The set of extensions available varies
from one implementation to the next and may even change as a result of
configuration choices. It is therefore essential that the XML
representation of Sieve be able to accommodate Sieve extensions without
requiring schema changes. It is also desirable that Sieve extensions not
require changes to the code that converts to and from the XML representation.
This specification defines an XML representation for sieve scripts and
explains how the conversion process to and from XML works. The XML representation
is capable of accommodating any future Sieve extension as long as the underlying
Sieve grammar remains unchanged. Furthermore, code that converts from
XML to the normal Sieve format requires no changes to accommodate extensions,
while code used to convert from normal Sieve format to XML only requires
changes when new control commands are added - a rare event.
An XML Schema, Relax NG Schema, and a sample stylesheet to convert
from XML format are also provided in the appendices.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC 2119.
The Sieve language is designed to be highly extensible without making any
changes to the basic language syntax. Accordingly the syntax of Sieve,
defined in section 8 of , is
entirely structural in nature and employs no reserved words of any
sort.
Structurally a sieve script consists of a series of commands. Each command
in turn consists of an identifier, zero or more arguments, a optional
test or test-list, and finally an optional block containing another
series of commands. Commands are further broken down into controls
and actions, although this distinction cannot be determined from the
grammar.
Some example Sieve controls are:
Some examples of Sieve actions are:
At the time of this writing there are no controls defined that accept
both arguments and a test. Similarly, there are currently no defined
actions that allow either a test or a command block. Nevertheless, the
Sieve grammar allows such constructs to be defined by some future extension.
A test consists of an identifier followed by zero or more arguments, then
another test or test-list. Unlike commands, tests cannot be followed
by a command block.
Here are some examples of Sieve tests. Note that such tests have to appear
as part of a command in order to be syntactically valid:
Command or test arguments can be either string lists, whole numbers or tags.
(Tags are simply identifiers preceded by a colon.) Note that although the
Sieve grammar treats single strings as a degenerate case of a string
list, some tests or actions have arguments that can only be individual
strings, not lists.
Here is an example showing the use of both a test-list and a string list:
Extensions can add new controls, actions,
tests, or new arguments to existing controls or actions. Extensions have
also changed how string content is interpreted, although this is not
relevant to this specification. However, it is especially important to note
that so far no Sieve extension has added a new control to the language and it
seems safe to assume that due to their nature future addition of controls will
be rare.
Finally, comments are allowed between lexical elements in a Sieve script.
Finally, comments are allowed between lexical elements in a Sieve
script. One important use case for comments is encoding meta-data
about the script, a facility which is lacking in the Sieve language.
Therefore comments need to be preserved in the XML representation.
Sieve controls and actions are represented in XML as "control" or
"action" elements respectively. The command's identifier appears as a
name attribute on the element itself. This is the only attribute
allowed on controls and actions - arguments, tests, test-lists,
and nested command blocks are all represented as nested elements. While
naming the element after the control or action itself may seem like a
better choice, doing so would result in extensions requiring
corresponding schema changes.
The example Sieve controls shown in the previous section would be
represented in XML as:
The example Sieve actions shown above would appear in XML as:
The separation of controls from actions in the XML representation
means that conversion from normal Sieve format to XML has to be able to
distinguish between controls and actions. This is easily done by maintaining
a list of all known controls since experience indicates new controls are
rarely added.
Tests are represented in the same basic way as controls and actions, that is,
as a "test" element with a name attribute giving the test identifier. For
example:
String, number, and tag arguments are represented as "str", "num", and "tag"
elements respectively. The actual string, number, or tag identifier appears
as text inside the element. None of these elements have any defined attributes.
Several examples of arguments have already appeared in the preceding control,
action and test examples. Any whitespace in the str body content MUST be
preserved by the processor.
String list arguments are represented as a "list" element which in turn contains
one or more str elements. Note that this allows the distinction between a single
string and a string list containing a single string to be preserved. This is
not essential since a list containing a single string could simply be mapped
to a string, but it seems prudent to maintain the distinction when mapping to
and from XML.
Nested command blocks appear as a series of control or action elements
inside of an outer control or action element. No block element is needed
since an inner command block can only appear once and only after any
arguments, tests, or test-lists. For example:
Finally, Sieve comments are mapped to a special "comment" element in XML.
Both hash and bracketed comments are mapped to the same construct so
the distinction between the two is lost in XML.
XML comments are not used because some XML tools do not make it convenient
to access comment nodes.
Sometimes graphical user interfaces are a convenient way to provide
sieve management functions to users. These interfaces typically
summarize/annotate/group/display sieve script(s) in an intuitive way
for end users.
To do this effectively, the graphical user interface may require additional
information about the sieve script itself. That information or "meta-data"
might include, but is not limited to - a sieve name (identifying the current
sieve), whether the sieve is enabled or disabled, the order in which the
part of the sieve are presented to the user. The graphical user interface may
also choose to provide mechanisms to allow the user to modify the script.
It is often useful for a graphical user interface to group
related sieve script elements and provide an interface that display these
groups separately so they can be managed as a single object. Some examples
include Sieve statements that together provide vacation responders,
blacklists/whitelists and other types of filtering controls.
Some advanced graphical user interfaces may even provide a natural
language representation of a sieve script and/or an advanced interface
to present sieve statements directly to the user.
A graphical user interface may also choose to support only a
subset of action commands in the Sieve language (and its extensions)
and so a mechanism to indicate the extent of support and characterize
the relationships between those supported action commands and test
(with its arguments) is immensely useful and probably required for
clients that may not have complete knowledge of sieve grammar and semantics.
The Sieve language contains no mechanisms for indicating how a
given script should be presented in a user interface. The language
also does not contain any specific mechanisms to represent other sorts of
meta-data about the script. Providing support for such meta-data as part of a
sieve script is currently totally implementation specific and is usually done by
imposing some type of structure on comments.
However, such information can be represented in XML very easily so
it makes sense to define a framework to do this as part of the XML
format. Implementations MAY choose to use structured comments to
retain this information when the script is converted to normal Sieve
format.
The sample schemata for the XML representation of Sieve allows XML in foreign
namespaces to be inserted in most places in Sieve scripts. This is
the preferred means of including additional information.
Alternately, the schema defines two display directives -
displayblock and displaydata - as containers for meta-data needed by
graphical user interfaces.
Editors MAY use displayblock, displaydata and foreign namespaces to associate
meta-data. Some editors find it inconvenient to preserve this
additional data during an editing session. Editors MAY preserve this data
during an editing session for compatibility with other editors.
The displayblock element can be used to enclose any number of sieve
statements at any level. It is semantically meaningless to the sieve
script itself. It allows an arbitrary set of attributes.
Implementations MAY use this to provide many simple, display related
meta-data for the sieve such as sieve identifier, group identifier,
order of processing, etc.
The displaydata element supports any number of arbitrary child elements.
Implementations MAY use this to represent complex data about that sieve
such as a natural language representation of sieve or a way to provide
the sieve script directly.
Since the XML representation is not intended as a storage format there
needs to be a way to preserve the additional information that can
be included in the XML representation in the normal Sieve syntax. This
is done through the use of three structured comment conventions:
XML content in other namespaces is placed in Sieve
bracketed comments beginning with the string "/* [/" and ending
with the string "/] */".
The content of displaydata elements is placed in Sieve bracketed comments
beginning with the string "/* [|" and ending with the string "|] */".
The beginning of a displayblock element is mapped to a bracketed
Sieve comment beginning with the string "/* [*" which then lists any
displayblock attribute names and values in XML format. The end
of a displayblock element is mapped to a comment of the form
"/* *] */".
Processors MUST preserve the additional information allowed in the
XML format and SHOULD use the structured comment format shown above.
Note: If "*/" is found in the XML content, when mapped into a comment it
would prematurely terminate that comment. Escaping of this sequence
would often be inconvenient for processors. Editors SHALL NOT include
"*/" within displayblock, displaydata or foreign markup. Processors MAY
regard documents containing "*/" in foreign markup, displayblock
or displaydata as invalid.
A processor MAY validate documents against a schema and MAY
reject any which do not conform. For any document that a processor does
not reject as invalid, any markup that the processor cannot understand
by reference to this specification MAY be discarded.
Note that example Relax NG and XML Schema are given in the appendices below.
Any syntactically valid sieve script can be represented in XML. Accordingly,
all security considerations applicable to Sieve and any extensions used also
apply to the XML representation.
The use of XML carries its own security risks. Section 7 of
RFC 3470 discusses these risks.
It is axiomatic that a Sieve editor must be trusted to do what the user
specifies. If XML formats are used this trust necessarily must extent to
the components involved in converting to and from XML format.
Arbitrary data can be included using other namespaces or
placed in the extensible displayblock and displaydata
constructs defined in this specification, possibly including entire scripts
and other executable content in languages other than Sieve.
Appropriate security precautions should be
taken when using these facilities.
This section registers a new XML namespace per
the procedures in RFC 3688.
RELAX NG Compact SyntaxOASISExtensible Markup Language (XML) 1.0 (Fifth Edition)Textuality and Netscapetbray@textuality.comMicrosoftjeanpa@microsoft.comW3Ccmsmcq@w3.orgSun Microsystemseve.maler@east.sun.com
The example sieve script given in section 9 of
would be represented in
XML as the following code component:
The same script could be annotated with graphical display hints in a variety of
ways. Three possible code components that do this are:
Note that since displayblock elements are semantically null as far as the
script itself is concerned they can be used to group structures like
elsif and else that are tied to statements in other groups.
The representation of this script in regular Sieve syntax uses structured
comments:
A separate namespace can be used to embed text or structured information:
Alternately, displaydata elements can be used to accomplish the same
thing:
Again, structured comments are used to represent this in regular
Sieve syntax:
This appendix is informative. The following code component
is an XML Schema for the
XML representation of Sieve scripts. Most of the elements employing
a complex content model allow use of elements in other namespaces,
subject to lax XML Schema validation rules. Additionally, displaydata
elements can be used to encapsulate arbitrary XML content. Finally,
displayblock elements can be used as a general-purpose grouping
mechanism - arbitrary attributes are allowed on displayblock elements.
This appendix is informative. The following code component
defines a Relax NG schema using
compact notation OASISRNC for the XML
representation of Sieve scripts. Most of the elements employing
a complex content model allow unrestricted use of elements in other namespaces.
Additionally, displaydata elements can be used to encapsulate arbitrary XML
content. Finally, displayblock elements can be used as a general-purpose grouping
mechanism - arbitrary attributes are allowed on displayblock elements.
This appendix is informative. The following code component is a stylesheet
that can be used to
convert the Sieve in XML representation to regular Sieve format. Content
in other namespaces, displaydata, and displayblock elements are converted
to structured comments as appropriate.
The stylesheet copy mode code is loosely based on a sample code
posted to the xsl-list list by Americo Albuquerque. Robert Burrell Donkin,
Andrew McKeon, Alexey Melnikov, and Aaron Stone provided
useful comments on the document.