✨ Create a formal specification of the election record serialization format

[JohnLCaron]

Is there an existing issue for this?

• I have searched the existing issues

Suggestion

A formal specification is needed to prevent needless churn among collaborators. Its ok if it needs to be changed before finalization, but we need a clear spec in order to identify bugs in our code and the reference code.

We will have to decide how to specify. Could be an abstract language (UML?) or something ad-hoc or ? It has to describe how to translate JSON encoding into a language specific data type.

For example the field may be an enum, and has to match the list of enum names in the reference library. For integers, typically you also specify size and signedness (16 bits unsigned, etc), though its ok to just use one type big enough for everything. A BigInteger has to be distinguished from a regular integer, and its string encoding (hex, base64, decimal) specified.

Theres really a small number of such base types, and not hard to do. The various implementors can then weigh in on any issues they have, and a consensus should emerge quickly.

Possible Implementation

I would be happy to make a first draft if that would be helpful.

Anything else?

No response

[keithrfung]

@JohnLCaron we def agree with this. We had cards on this repo to originally do this with a JSON Specification. We're currently in flux so I think trying to complete it today would be unwise but perhaps starting it not.

[keithrfung]

Also I shifted the repository for this issue. This top level repository should truly be the piece dictating this information, not the python repository. We are trying to make that adjustment.

https://www.electionguard.vote/develop/Architecture/

[JohnLCaron]

Heres a draft JSON serialization proposal. Its almost what the python library is putting out now.

https://github.com/JohnLCaron/electionguard-java/blob/master/docs/JsonElectionSpec.md

JsonElectionSpec.md

[JohnLCaron]

Here are the equivilent as protobuf schemas:
electionguardSerializationProtos.zip

[JohnLCaron]

Here are the latest proposed protobuf serializations from Dan and me. Perhaps a starting point for 2.0.

https://github.com/danwallach/electionguard-kotlin-multiplatform/blob/main/docs/SerializationSpec.md

https://github.com/danwallach/electionguard-kotlin-multiplatform/tree/main/src/commonMain/proto

[keithrfung]

@JohnLCaron Just FYI, that repository is private so we cannot see those links. Perhaps share in Slack.