usnistgov / voterrecordsinterchange

Common data format specification for voter records interchange data

Voting - NIST Special Publication 1500-102 Voter Records Interchange Common Data Format Specification Version 1

This repository holds the NIST Special Publication 1500-102 Voter Records Interchange (VRI) Common Data Format Specification Version 1 and supporting files. Besides the PDF and Word versions of the specification located in this repository, there is an HTML version at

https://pages.nist.gov/VoterRecordsInterchange

The VRI specification is also available using the following Digital Object Identifier (DOI):

https://doi.org/10.6028/NIST.SP.1500-102

The VRI specification supports the following use cases:

1. OVR Submission: Digital VR applications forms transmitted within state OVR systems or to state OVR systems by third-party OVR systems, following the formats of the NVRA and FPCA voter registration application forms, including state-specific additions to these forms.
2. VR Update Submission: Similar application forms including: voter registration update (change of name, change of address), change of voter status, and absentee ballot request.
3. OVR Transfer: Subsets of such applications used for third-party OVR assistant organizations to transfer users and user data to state OVR systems.
4. Voter Records Lookup: Requests for information regarding voter records within a VR system, or between a VR system and a third party.

There is a "flattened" version of the XML schema included in this repository; the .zip includes the other XML schemas that are normally referenced by URL or DOI.

Please contact John Wack or John Dziurlaj for more information.

Repo Structure

Name	Description
NVRA-PDF-examples	Examples of VRI CDF using OH VR form
VA-examples	Examples of absentee use-case in VA
VRI_UML_Documentation_files	Images of UML classes
Flattened VRI XML schema.zip	Flattened version of the XML schema and external schemas
NIST.SP.1500-102-rev.docm	Word version of VRI specification
NIST.SP.1500-102-rev.pdf	PDF version of VRI specification
NIST_V0_voter_records_interchange.json	VRI JSON schema
NIST_V0_voter_records_interchange.xsd	VRI XML schema
VRI Implementation.xml	MagicDraw UML Model
VRI_UML_Documentation.md	UML Documentation
VoterRecordsRequest.png	Image of Voter Records Request model
VoterRecordsResponse.png	Image of Voter Records Response model

voterrecordsinterchange's Issues

Support for Voter Registration Lookups

Voter Lookup Proposal

A consequence of the streamlined structure proposed in issue #6 (Ballot Requests) is voter information is now independent of a particular form used by a voter . A major advantage of this revised structure is that the same Voter class can be used in different contexts, such as registration, ballot request or lookup.

Prior versions of VRI did not explicitly support a lookup use-case. It was assumed that the response to such a VRI request would be in an implementation dependent format.

Proposed Changes

Add a new VoterRecordsResponse subtype, VoterRecords. Each VoterRecords object may contain zero or more VoterRecord instances. This structure is to handle a situation where a voter has multiple records, as well as where the lookup whose criteria was insufficiently precise to return a single voter.
VoterRecord is a subtype of Voter with additional attributes to convey informational normally stored in a voter registration system, as:

• Districts that voter belongs (e.g. congressional districts, city wards, etc.)
• Locality of the voter
• Polling Location for the Voter
• Election Administration for the Voter
• Voter participation history

Note: There is no voter status. It is assumed any record that comes back will be an eligible voter.

xmldsig imported but unused in XSD

NIST_V0_voter_records_interchange.xsd imports the schema given by namespace http://www.w3.org/2000/09/xmldsig#, but xmldsig is otherwise unused.

broken links in UML documentation

There are several broken links in the UML documentation, usually related to "other type". the attribute description will have what appears to be a link back to the relevant enumeration, but when you click the link it doesn't go anywhere. Examples are VoterRecord:OtherVoterStatus, VoterRecordRequest:OtherType, VoterID:OtherType, VoterClassification:OtherType

Need MailedBallotPrecinct status, qualification on poll location

Organization Name: Carl Hage

Organization Type: 4

Document: VoterRecordsInterchange

Reference: 3.1.6.18 The VoterRegistration Element, 3.1.6.12 The ReportingUnit Element

Comment: For a specific election, a precinct (split-precinct) could be assigned to use mail ballots only (while others have a poll location), or all precincts in an election might vote by mail (or use a dropoff location or vote center). This is independent of the <BallotReceiptPreference>. In the <VoterRecordsInterchange> a poll location (ReportingUnit) can be specified, but there is no way to indicate mail-ballot only for that voter in an election. Sometimes a message is stored as a fake address, but this is not machine readable, so an explicit machine-readable tag is needed.

Note the schema definition for <ReportingUnit> has a <Location> but the spec does not show this in the table above. The note at the <ElectionAdmininstration> definition, it says that it can be used in a <ReportingUnit> but the ReportingUnit xsd doesn't say that.

Is the intent with a VRI retreival to be able to include Poll Locations (the actual address)?
<ContactInformation> is allowed in a ReportingUnit of SP1500-100 election results but not SP-1500-103. (A Location is allowed apparently, but Contact isn't.)

A number of online "VR/poll locator" look apps are in use-- a voter registration query form has name, birth date, and some other information (like street address or house number), then the voter registration status, poll location for an upcoming election, and sometimes district list is returned. SP1500-103 provides a basis for an interoperable API for these systems. Is that an intent?

Sometimes poll locations are To-Be-Determined. Rather than put in a fake address, it is better to qualify the address with a status. An enumerated type could be used. Also, an address might be present, but locations have not been finalized. When there is a last minute change, it could be useful to note that to highlight to a user there has been a change, e.g. from prior mailed information.

Suggested Change: Add <PollLocationStatus> to the members of <VoterRegistration>, a new enumerated type. (also applicable to a specified election date). Values could be not-in-election (for a selected date), mail-ballot-election, mail-ballot-precinct, not-yet-assigned, not-yet-final, final, changed (after it became final).

Record Voter Participation

This issue describes proposed modifications to the VRI specification to support Voter Participation data. What constitute voter participation will be jurisdiction dependent, some jurisdictions will only consider voters who voted a countable ballot in an election, while others may include any attempt to vote, for example voting a provisional ballot that was determined to be uncountable, et cetra.

Changes

A VoterRecord (i.e. from a lookup request) may contain 0..* VoterParticipation objects, each representing an Election that voter participated in, and optionally the BallotStyle (and possibly the Party, in closed primaries) they were issued. The VoterParticipation class optionally supports association with a ReportingUnit, i.e. for reporting the actual Polling Location used.

PhoneContactMethod problematic

An issue was raised that this could result in nonsensical usage, e.g., type=email. This could be addressed with a schematron rule that requires used of PhoneContactMethod if type=phone and flagged as an error for any use of PhoneContactMethod combined with type=anything other than phone. This is what I recommend - we will need schematron rules for other items as well, which we are developing currently.

New version of schema

I added a new version of the schema, UML model, and Word/PDF docs. The docs are ready to submit to NIST internal review and publishing pending any comments, the schema and UML model were updated to remove the digital signature elements.

pre-WERB changes

Placeholder for pre-WERB changes

Update publications with final version

Update specification publications with final published versions.

ExternalIdentifiers needed in VoterRegistration Element

Organization Name: Carl Hage

Organization Type: 4

Document: VoterRecordsInterchange

Reference: 3.1.6.18

Comment: Current HAVA mandated VR databases include an ID for a voter record, sometimes both statewide and local (e.g. county EA). To interoperate with other official databases, and to facilitate tracking and auditing of transactions, it should be required for the VRI to include IDs in retrieved data (for all that exist). Example: Ohio voter file has a SoS ID and county-assigned ID (with county number) for each voter registration record.

Suggested Change: Add <ExternalIdentifier> to the members of <VoterRegistration>. Note that there may be a prior (external) record ID, e.g. in the case of a change of address transaction. An open issue is distinguishing between current and prior (removed/inactive) record IDs.

Update PDF Prototypes

Update prototypes of XFA based PDFs to use latest version of the schema.

Fix markdown documentation

Fix two issues with Markdown documentation:

• Use curly brace syntax for properties that are associations.
• Reorder properties to match the order they appear in XML Schema.

General Pre-Election Day Ballot (Absentee) Request

State Absentee (Pre Election Day) Ballot Request Proposal

The VRI Specification currently supports digital analogs of the NVRA (National Voter Registration Act) and FPCA (Federal Postcard Application) forms. FPCA is a combined voter registration and absentee request.

Perhaps the second most common transaction after voter registration is requests for a pre-election day ballot.

A semantic model of the absentee (pre-election day) requests is available here

Absentee ballot requests generally consist of a subset of information required by a voter registration request. However, this is not always the case. Some states that require a valid excuse to voter absentee, additional addressing information, etc.

When registration and absentee information is provided in a single request, it is implied that a single vehicle is being used for such a request (a hybrid form), rather than two separate transactions. Separate transactions should be represented as two distinct instances.

Background

Originally, FPCA related attributes were combined with the VoterRegistration class. This made sense when the class only supported FPCA and NVRA style forms. With the addition of state specific absentee support, a more general structure is required.

The revised structure supports the following scenarios

• Voter registration only (e.g. NVRA, State Form)
• Absentee requests only (E.g. State Form)
• Combinations of both (e.g. FPCA)
• A general request (e.g. a lookup)

Changes

This proposal makes a number of breaking changes to the existing VRI specification. These breaking changes were made in order to (1) allow an absentee ballot request independent of a voter registration request, and (2) reduce the duplication when absentee and voter registration requests are combined.

Structural Changes

Instead of every VoterRecordsRequest requiring a VoterRegistration instance, it now requires a Voter instance. This instance contains common attributes between absentee and voter registration forms, such as those for establishing identity (e.g. Name, VoterId, etc.).

Associations moved from VoterRegistration:

• AdditionalInfo
• ContactMethod
• Name
• Party
• RegistrationHelper (now RequestHelper)
• RegistrationProxy (now RequestProxy)
• Signature
• VoterClassification
• VoterId

Attributes moved from VoterRegistration:

• DateOfBirth
• Gender
• MailingAddress
• RegistrationAddress
• RegistrationAddressIsMailingAddress
• OtherForm
• Form

Other attributes in VoterRegistration specific to FPCA have been moved to the BallotRequest detailed below.

Absentee Support

Absentee support is provided via the BallotRequest abstract class. Depending on the laws of the state, one or more concrete implementations will apply:

• PermanentAbsenteeBallotRequest. For a state that allows permanent absentee ballot requests with no specific time expiration.
• ElectionBasedAbsenteeBallotRequest. For a state that allows for a request for a single election event.
• CalendarBasedAbsenteeBallotRequest. For a state that allows a request for a time period, such as an election cycle calendar.

VoterRecordsResponse PNG file missing some classes

The .png file that provides a picture of the UML model for VoterRecordsResponse appears to be missing some classes that are available in the response, such as VoterID and VoterClassification. I think we either need to add all the classes that are available in a response to the PNG or else add some language somewhere that says that not all classes are shown.

Error Handling in VriRecordsResponse

Right now the subtype of VriRecordsResponse, RequestRejectionhas three attributes: AdditionalDetails, Error, and OtherError. Since all these errors are at the same "level", it is very difficult to contextualize errors that are specific to a certain part of the request payload. For example, assume that there is a requirement that the voter's party must be be defined. Right now the response would need to look something like this:

<n2:VoterRecordsResponse xmlns:n2="NIST_V0_voter_records_interchange.xsd">
	<n2:Error>other</n2:Error>
	<n2:OtherError>party-missing</n2:OtherError>
</n2:VoterRecordsResponse>

What you end up with is a lot of duplicative error codes with the difference between them being the target of the error rather than the kind.

Proposed Changes

1. Add an attribute called Ref that would serve as a pointer to the target node(s). The pointer language used would be dependent on the transmission format used (e.g. XPath for XML, JSON Pointer for JSON).
2. Move attribute from (1), Error and OtherError to a composed class Error off of RequestRejection (see image below).

Then we would end up expressing the earlier example as such:

<n2:VoterRecordsResponse>
	<n2:Error>
		<n2:Name>other</n2:Name>
		<n2:OtherError>missing-required-field</n2:OtherError>
		<n2:Ref>/VoterRecordsRequest/Subject/Party</n2:Ref>
	</n2:Error>
</n2:VoterRecordsResponse>

Remove the following enumeration literals from RequestError

• incomplete-address
• incomplete-birth-date
• incomplete-name
• incomplete-signature

Perhaps, some new, more general RequestError enumeration values could be developed as well.

VR content can vary by election date (is election specific)

Organization Name: Carl Hage

Organization Type: 4

Document: VoterRecordsInterchange

Reference: 3.1.6.18 The VoterRegistration Element

Comment: There may be 2 pending elections (e.g. LA has one in October & November),
and the second election might require a new precinct split, e.g. for a proposed district formation
or transfer. The precinct assignment for the first election might be different than for the second.

During redistricting, the district assignments may change. A current and upcoming election might
have different congressional districts, for example.

A voter might move after registration closes for one election but before closing for a subsequent
election. The voter would go to the poll location for the former address in election 1 and poll
location for newly registered address for election 2.

Poll locations, precinct consolidation, and mail-ballot precinct status vary by election date. There
can be 2 upcoming elections within the election cycle where poll locations are required to be final.

Suggested Change: Add an <ElectionDate> element to <VoterRegistration>
in a retrieval request to select a particular election, and to qualify the effective date for data
returned in a response. (The response might give the effective election date to qualify the
response even if no specific date was selected.)

Alternative: Allow data for multiple upcoming elections or to distinguish election-specific content
by creating an <ElectionDate> element with multiple instances allowed to contain response
data qualified by each active upcoming (or past) election. (Using a single selected or reporting
date seems simpler.)

Note, it can be useful to report the scheduled future election dates for a voter, along with the list of districts.

Update README.md

The README.md needs to be updated to reflect the latest uses cases, project structure.