1 Introduction

This document describes the OASIS Election Mark-up Language (EML) version 5.0 schemas.

The messages that form part of EML are intended for transfer between systems. It is not intended that all outputs of a registration or election system will have a corresponding schema.

This document and its accompanying set of schemas do not claim to satisfy the final requirements of a registration or election system. It is incumbent on the users of this document to identify any mistakes, inconsistencies or missing data and to propose corrections to the OASIS Election and Voter Services Technical Committee.

1.1 Terminology

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 [RFC2119].

1.2 Normative References

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

1.3 Non-Normative References

[MIME PART 2] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types IETF http://www.ietf.org/rfc/rfc2046.txt

[MIME] MIME Media Types IANA http://www.iana.org/assignments/media-types/

[XMLDSig] XML-Signature Syntax and Processing W3C http://www.w3.org/TR/xmldsig-core/

[XPATH] XML Path Language (XPath) Version 1.0 W3C http://www.w3.org/TR/xpath

2 The EML Schemas

2.1 Background

The following is the Executive Summary of the “EML Process and Data Requirements”:

OASIS, the XML interoperability consortium, formed the Election and Voter Services Technical Committee in the spring of 2001 to develop standards for election and voter services information using XML. The committee’s mission statement is, in part, to:

“Develop a standard for the structured interchange among hardware, software, and service providers who engage in any aspect of providing election or voter services to public or private organizations...”

The objective is to introduce a uniform and reliable way to allow systems involved in the election process to interact. The overall effort attempts to address the challenges of developing a standard that is:

· Multinational: Our aim is to have these standards adopted globally.

· Flexible: Effective across the different voting regimes (e.g. proportional representation or 'first past the post') and voting channels (e.g. Internet, SMS, postal or traditional paper ballot).

· Multilingual: Flexible enough to accommodate the various languages and dialects and vocabularies.

· Adaptable: Resilient enough to support elections in both the private and public sectors.

· Secure: Able to secure the relevant data and interfaces from any attempt at corruption, as appropriate to the different requirements of varying election rules.

The primary deliverable of the committee is the Election Markup Language (EML). This is a set of data and message definitions described as XML schemas. At present EML includes specifications for:

· Candidate Nomination, Response to Nomination and Approved Candidate Lists

· Referendum Options Nomination, Response to Nomination and Approved Options Lists

· Voter Registration information, including eligible voter lists

· Various communications between voters and election officials, such as polling information, election notices, etc.

· Ballot information (races, contests, candidates, etc.)

· Voter Authentication

· Vote Casting and Vote Confirmation

· Election counts and results

· Audit information pertinent to some of the other defined data and interfaces

· EML is flexible enough to be used for elections and referendums that are primarily paper-based or that are fully e-enabled.

As an international specification, EML is generic in nature, and so needs to be tailored for specific scenarios. Some aspects of the language are indicated in EML as required for all scenarios and so can be used unchanged. Some aspects (such as the ability to identify a voter easily from their vote) are required in some scenarios but prohibited in others, so EML defines them as optional. Where they are prohibited, their use must be changed from an optional to prohibited classification, and where they are mandatory, their use must be changed from an optional to required classification.

2.2 Viewing Schemas

EML schemas are supplied as text documents. For viewing the structure of the schemas, we recommend use of one of the many schema development tools available. Many of these provide graphical displays.

The Schematron schemas are mainly short and simple to understand as text documents for those with a working knowledge of Xpath.

2.3 Schema Diagrams in this Document

The schema diagrams in this document were created using XML Spy 2007. The following is a guide to their interpretation.

In this section, terms with specific meanings in XML or XML Schema are shown in italics, e.g. sequence.

Note that the diagrams in this document do not use the default diagramming options of XML Spy, but have additional information. The additional information to be shown can be set using the menu selections Schema Design | View Config.

In this section, and throughout this document, the prefix "xs" denotes the XML schema namespace http://www.w3.org/2001/XMLSchema.

The diagram below represents a simple schema. The root element of an instance described by this schema is the element A. The content model of this element is a sequence of the elements B, D and E. The element B is of complex data type Bstructure. This contains a choice of either element C or element F. Element C is a restriction of another complex data type Cstructure. In this case, the restriction is to forbid the use of the element G (which is defined in Cstructure as optional). The other elements allowed are H, which can appear any number of times (but must appear at least once), and I, which can appear up to three times (or not at all). Element D is optional, and of data type Dstructure. This has a content model requiring all of elements J and K, which are both of type xs:string. Finally, element E is of simple data type Etype, which is restricted from the xs:NMTOKEN data type by only allowing the values ‘yes’ and ‘no’.

It is important to remember that these diagrams do not include any attributes. In this document, these are shown in tables below the diagrams.

The full schema is shown below the diagram.

the element is crossed out as the restriction is to forbid its occurrence

indicates that this is a sequence

dotted box around element indicates that element is optional

The yellow box represents the content model of the complex data type (in this case, Bstructure)

the data type is in blue, so this is a derivation. The derivation is to allow only the values ‘yes’ or ‘no’

a data type in blue shows a derivation, in this case, a restriction

indicates that this is a choice

indicates that this is an ‘all’

shows the data type

indicates zero to three occurrences

indicates one to many occurrences

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:element name="A">

<xs:complexType>

<xs:sequence>

<xs:element name="B" type="Bstructure"/>

<xs:element name="D" type="Dstructure" minOccurs="0"/>

<xs:element name="E">

<xs:simpleType>

<xs:restriction base="xs:NMTOKEN">

<xs:enumeration value="no"/>

<xs:enumeration value="yes"/>

</xs:restriction>

</xs:simpleType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name="Bstructure">

<xs:choice>

<xs:element name="C">

<xs:complexType>

<xs:complexContent>

<xs:restriction base="Cstructure">

<xs:sequence>

<xs:element name="G" type="xs:positiveInteger" minOccurs="0" maxOccurs="0"/>

<xs:element name="H" type="xs:string" maxOccurs="unbounded"/>

<xs:element name="I" type="xs:date" minOccurs="0" maxOccurs="3"/>

</xs:sequence>

</xs:restriction>

</xs:complexContent>

</xs:complexType>

</xs:element>

<xs:element ref="F"/>

</xs:choice>

</xs:complexType>

<xs:complexType name="Cstructure">

<xs:sequence>

<xs:element name="G" type="xs:positiveInteger" minOccurs="0"/>

<xs:element name="H" type="xs:string" maxOccurs="unbounded"/>

<xs:element name="I" type="xs:date" minOccurs="0" maxOccurs="3"/>

</xs:sequence>

</xs:complexType>

<xs:complexType name="Dstructure">

<xs:all>

<xs:element name="J" type="xs:string"/>

<xs:element name="K" type="xs:string"/>

</xs:all>

</xs:complexType>

<xs:element name="F" type="xs:string"/>

</xs:schema>

2.4 EML Message Validation

It is up to each specific system implementation whether it uses these schemas for validation of EML messages for either testing or live use. The recommended approach is to validate incoming messages against the EML schemas (with the application-specific EML externals schema), then further validate against the relevant Schematron schema. The first stage requires the use of an XML processor (parser) that conforms to W3C XML Schema. The second stage requires either an XSLT processor or a dedicated Schematron processor.

However, an implementation may choose to:

· modify the EML schemas to incorporate those application-specific constraints that can be represented in W3C XML Schema;

· not validate the rules that are encoded as Schematron schemas;

· not perform any validation; or

· develop some alternative validation.

2.5 Namespaces

The message schemas and the core schema are associated with the namespace urn:oasis:names:tc:evs:schema:eml. This is defined using the prefix eml. The XML Schema namespace http://www.w3c.org/2001/XMLSchema is identified by the prefix xs and the XML Schema Instance namespace http://www.w3.org/2001/XMLSchema-instance by the prefix xsi.

Use is also made of namespaces for the Extensible Name and Address Language (xNAL). The Extensible Name Language namespace urn:oasis:tc:ciq:xsdschema:xNL:2.0 is identified by the prefix xNL, and the Extensible Language namespace urn:oasis:names:tc:ciq:xsdschema:xAL:2.0 by the prefix xAL.

2.6 Extensibility

Various elements allow extensibility through the use of the xs:any element. This is used both for display information (for example, allowing the sending of HTML in a message) and for local extensibility. Note that careless use of this extensibility mechanism could reduce interoperability.

2.7 Additional Constraints

The EML schemas provide a set of constraints common to most types of elections worldwide. Each specific election type will require additional constraints, for example, to enforce the use of a seal or to ensure that a cast vote is anonymous. It is recommended that these additional constraints be expressed using the Schematron language although other validators, eg OASIS CAM, can be used. This allows additional constraints to be described without altering or interacting with the EML schemas. Any document that is valid to a localization expressed in Schematron must also be a valid EML document.

2.8 Conventions

Within this specification, the following conventions are used throughout:

· Diagrams are shown as generated by XML Spy 2007 which was also used to generate the schemas and samples. These diagrams show element content, but not attributes

· Elements and attributes in schemas are identified by partial XPath expressions. Enough of a path is used to identify the item without putting in a full path.

2.9 Metadata

Some messages need information relating to the issuing of them, such as the issue date, who issued them etc. This is most likely to be a requirement for the 330 message but is equally applicable to 120, 130, 230, 350a and several others. For that reason, it is useful to make this optional information available in the header. The information usually consists of: managing authority, date of issue, start of list period (used for changes to the list to indicate the start of the period for which changes are being shown), end of list period (i.e. the date of the snapshot of the list).

3 Processing using Schematron

This section gives a short introduction to how validation can be achieved using Schematron schemas and an XSLT processor. Alternatively, direct validation using the Schematron schemas can be achieved using a dedicated Schematron processor.

3.1 Validation using Schematron Schemas

A Schematron schema is an XML document that can be converted to XSLT using an XSLT stylesheet. There is a published stylesheet (skeleton1-5.xslt) that can be used to achieve this. This produces an HTML output from the validation. A separate stylesheet can be produced that will create an output to the specification below. This stylesheet can import the skeleton and just over-ride those aspects where changes are required.

This stylesheet can be used once on each Schematron schema to produce the XSLT file that will be used for validating a specific message type. This stylesheet is then used to transform the incoming EML message into an error report based on the additional constraints.

The process is shown in the diagram below.

4 Splitting of Messages

There is sometimes a need to split long messages into several parts. By their nature, each of these messages will contain a small amount of background information and a single element type that is repeated many times. For example, the 330-electionlist message can have many VoterDetails elements.

When a message is split, each part must be a complete, valid EML document. This will contain all the elements required by EML and the specific application. Those parts outside the repeated element that relate to the message as a whole, such as the TransactionId, must have the same values in each part message. The values of those elements and attributes that relate to an individual part message, such as the SequenceNumber, may vary between the individual part messages. Information in the EML element indicates the sequence number of the message and the number of messages in the sequence. Each message in the sequence must contain the same TransactionId, and must indicate the repeated element according to the table below. Only the messages shown in the table may be split in this way.\