usnistgov / voting

The NIST Voting Program repository

Voting - Files related to the NIST Voting program.

This repository holds information associated with the NIST Voting Program. It currently holds information about the election common data format (CDF) project and related information and files that are being created by NIST and collaborators.

NIST's election CDF project has the goal of (a) specifying a common import/export format for election devices such as electronic pollbooks, election management systems, and vote capture devices, and (b) specifying a comprehensive foundational UML models that will cover election data in general. The model defines the various objects (e.g., candidates, contests, offices, etc.) and their associated attributes, and specifies the relationships between and among the objects. It includes a glossary and other tools to ensure that the implementations of the model (e.g., XML or JSON formats) are consistent in style, definition, and composition.

There is an election glossary of terms, many of which are used in VVSG 2.0, located at https://pages.nist.gov/ElectionGlossary/

There are currently 8 CDF projects under active development, located in the following repositories:

1. Ballot Definition - created by EMSs to support interoperable ballot styles that can be read by scanners - the repository is located at https://github.com/usnistgov/BallotDefinition.
2. Cast Vote Records - created by scanners or DREs, contain tabulatable voter choices - the repository is located at https://github.com/usnistgov/CastVoteRecords.
3. CDF Test Method - An executable test method for determining conformance to CDF specifications, including related test data - the repository is located at https://github.com/usnistgov/cdf-test-method.
4. Election Event Logging - election-related events logged by election devices - the repository is located at https://github.com/usnistgov/ElectionEventLogging.
5. Election Results Reporting - pre- and post-election information and results - the repository is located at https://github.com/usnistgov/ElectionResultsReporting.
6. microCDF - serialization for interoperability of machine readable data in space-constrained environments (e.g. paper) - the repository is located at https://github.com/usnistgov/mcdf
7. Voter Records Interchange - voter registration-related information to support voter registration, electronic pollbooks, and voter registration database exchanges - the repository is located at https://github.com/usnistgov/VoterRecordsInterchange.

Please contact the NIST Voting Team with questions and for more information

There are additionally two other CDF-related projects under active development:

8. Election Business Process Modeling - for defining and modeling election processes for the purposes of informing use case development for CDF projects and showing where interoperability between processes may be beneficial and worthwhile to pursue - the repository is located at https://github.com/usnistgov/ElectionModeling. Contact John Dziurlaj for questions and more information.
9. Voting Methods - for defining a standard, specification and reference consisting of rigorously and precisely defined models of voting methods or modules including counting, tabulation, mathematical evaluation, and, common operations on vote data sets to support Data Interoperability - the repository is located at https://github.com/usnistgov/VotingMethods. Contact Lauren Massa-Lochridge for questions and answers.

voting's Issues

Language changes in generated documentation

The column heading Attribute in the UML generated documentation is wrong. It should be changed to Property, as it covers both attributes and associations.

Invalid namespace names in XSDs

I was doing some work with MorganaXProc and got the following error

Document            tries to declare namespace with an URI not conforming to RFC 3986.            Typically this comes from a missing (but required) URI scheme.            Defective URI is 'NIST_V2_election_results_reporting.xsd'.

It appears that the namespace name used in the XSDs are invalid per the XML Namespace specification, which references RFC 3986

Appendix is at wrong heading level

In the word docs, the Appendixes are at the wrong heading level (6) instead of (1). Checked 1500-100 and 1500-102.

JSON number data type

Organization Name: The Turnout LLC

Organization Type: 1 (CTR)

We use the JSON Schema data types to further restrict the JSON number data type. However, this provides limited protections in the real world that this value does not get mangled by whatever floating point handling the parser / JS engine uses, as the JS number data type is considered a IEEE floating point number.

JSON mapping of xsd:language type incomplete

Organization Name: The Turnout

Organization Type: 1 (CTR)

Comment (Include rationale for comment): JSON Schemas map xsd:language typed properties to the plain JSON Schema String. However, the XML Schema Part 2: Datatypes Second Edition Section 3.3.3 says that lexical space of a xsd:language typed value is [a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*

Suggested Change:

Add pattern constraint of [a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})* to for JSON equivalents of xsd:language.

---

Organization Type: 1 = Federal, 2 = Industry, 3 = Academia, 4 = Self, 5 = Other

JSON properties use singular names even when type is array

Organization Name: The Turnout

Organization Type: 1 (CTR)

Document: All JSON Schemas

Comment (Include rationale for comment): The JSON schema uses the property names from the UML model as-is. This leads to creating arrays with singular names. E.g. Contest is an array containing zero or more objects.

Suggested Change: Consider whether these properties should be pluralized. We do pluralize names in other places, such as when a directed reference can point to multiple objects (Ids vs Id suffix).

Specification Page Numbers

Organization Name: The Turnout LLC

Organization Type: 1 (CTR)

Document: All CDF specifications

Comment (Include rationale for comment): PDF page numbers and printed page numbers (i.e. numbers at the bottom of each page) do not match. This can make citations more difficult.

Suggested Change: Regenerate PDFs with page numbers synchronized

---

Organization Type: 1 = Federal, 2 = Industry, 3 = Academia, 4 = Self, 5 = Other

Number types could be more precise

Organization Name: The Turnout

Organization Type: 1 (CTR)

Document: Various

A lot of properties in the CDF data models use xs:integer. However, this allows for negative numbers, which makes little sense in most cases. For example, negative BallotsCast or Round. The XDM supports several subtypes, including xs:nonNegativeInteger, and should be explored.

Improve documentation of primitive subtypes

Organization Name: The Turnout

Organization Type: 1 (Contractor)

Suggested Change: Primitive subtypes such as ShortString, HtmlColorString, TimeWithZone, etc. are not well documented. In many cases, the documentation tooling generates hyperlinks to sections that do not exist. Add sections for these subtypes.

Make UML properties public

Currently all UML properties are private. This presents issues when performing certain operations on the models, such as simulations.

Public URL for schemaLocation

Outside of a raw URL GitHub provides, is there a definitive public URL that can be used within the schema element for an XML file that intends to adhere to the NIST common election data format?

Investigate JSON schema format of URI

JSON Schema format: uri appears to be stricter than XML anyURI. For example www.example.com is valid for XML but not JSON.

Add documentation to JSON schemas

Organization Name: The Turnout

Organization Type: 1 (Contractor)

Suggested Change:

Existing JSON Schemas do not have documentation associated with data structures, while XML Schema (XSD 1.0) does. Add support for description metadata in JSON schemas.

Factor out shared MagicDraw packages

Each common data format model is stored in a MagicDraw XMI file. These MagicDraw projects include copies of several profile packages, which allow the models to be tagged with details regarding their conversion from UML to JSON/XML. However, because each profile is copied directly into the CDF project, they cannot be effectively updated without modifying each CDF MD file, which is time consuming and error-prone.

To remedy this, I propose that each CDF MD file reference a shared, externally defined "CDF Profiles" package that can be distributed as a MagicDraw Resource Distribution ZIP file.

This affects the internal structure of the MagicDraw files only. It does not affect generated JSON/XML or UML Models.

More idiomatic JSON

Right now the JSON schemas developed produce JSON that somewhat verbose. In large JSON files, it's clear this is coming from two areas:

1. @type key is always required, even when it can be inferred
2. InternationalizedText typed properties use an overly complicated structure

The solution to (1) might be to allow this key to be omitted when the usage is clear (e.g. when the object's type does not have subtypes). For (2), we could look at the structure in JSON-LD for RDF language tags.

JSON mapping of ID, IDREF and IDREFS types incomplete

Organization Name: The Turnout

Organization Type: 1 (CTR)

Comment (Include rationale for comment): JSON Schemas map xsd:ID, xsd:IDREF and xsd:IDREFS typed properties to the plain JSON Schema String. However, all are derived from xs:NCName which has the lexical space of [\i-[:]][\c-[:]]*. IDREFS has more restrictions besides. See XML Schema Part 2: Datatypes Second Edition sections 3.3.8, 3.3.9, 3.3.10.

Suggested Change:

Add pattern constraint of [\i-[:]][\c-[:]]* for JSON equivalents of xsd:ID, xsd:IDREF and xsd:IDREFS.

---

Organization Type: 1 = Federal, 2 = Industry, 3 = Academia, 4 = Self, 5 = Other