Ballot Data Classes (UML)

[stratofax]

Updated class diagram from TrustTheVote-Project/BallotLab#81 (reply in thread)

classDiagram
  ElectionData *-- BallotStyleData
  BallotStyleData *-- CandidateContestData
  BallotStyleData *-- BallotMeasureData
  BallotMeasureData *-- BallotChoiceData
  ContestData <|-- BallotMeasureData
  CandidateContestData *-- CandidateChoiceData
  ContestData <|-- CandidateContestData
  CandidateChoiceData *-- PartyData

  class ElectionData {
    +String name
    +String type
    +String start_date
    +String end_date
  }

  class BallotStyleData {
    +GpUnit[] ballot_scopes
    +ContestData[] contests

    +candidate_contests()
    +ballot_measure_contests()
  }

  class ContestData {
    +String  id
    +String  title
    +String  district
  }

  class CandidateContestData {
    +String  vote_type
    +Integer votes_allowed
    +CandidateChoiceData[] candidates
  }

  class CandidateChoiceData {
    +String  id
    +PartyData party
    +Boolean is_write_in
  }

  class PartyData {
    +String name
    +String abbreviation
  }

  class BallotMeasureData {
    +String text
    +BallotChoiceData[] choices
  }

  class BallotChoiceData {
    +String id
    +String choice
  }

Loading

Notes

• Base type ContestData for the real contest data types.
  • Allows some shared code.
  • More importantly BallotStyleData.contests has to be a union of the contest types because contests are a mix of possible contest types, and splitting them would lose their ordering.
• PartyData type is used because it's easier to manage than having it be a dictionary.
• ballot_scopes is a list of the GpUnits the BallotStyle refers to
• BallotStyleData.id is the BallotStyle.ExternalIdentifier.Value. (There is no @id for BallotStyles.)
  • This is an optional field in the NIST SP 1500-100 definition, but it is present in the September test case, and it's likely we should require it for the TTV EDF profile.

[windoverwater]

@ion-oset @stratofax Created an initial pass (it is just a starting point) at a UML at https://github.com/TrustTheVote-Project/VTP-web-api/blob/feature/12-add-uml-mermaid-diagram/docs/VTP-core-data-classes.md. It did not take long for me to hit some fundamental questions. I know this is a UML targeted to the VTP-web-api and hence is not a UML for the VoteTrackerPlus repo implementation, but I am confused regarding the line between data and 'action' (code).

For example, in the current version of the above which is based on the current version of the VoteTrackerPlus repo, the tally operation returns/prints stream based IO. It is more like a syslog then a data structure. I don't think it is wise to try to replicate the logic in javascript or anywhere else and I don't think we have the time to change the format from syslog like to a proper data structure - this is a tally which is a function, not a data structure. If that is true (TBD), then the tally box will want something like verbosity which really speaks to 'code' as opposed to 'data'.

In any case, I would like to hear comments and discuss what is there now before spending more time on it solo.

[stratofax]

@windoverwater Thanks for posting this. I'd add the following guidelines to our diagramming exercise:

• We are currently only interested in data, not actions. Specifically, we need to focus on the exact set of data that the web client needs to render an empty ballot. Let's start with that, no more, no less.
• The other data set we'll need to diagram soon is the minimal set of data needed to send a filled-in ballot from the web client to VTP.
• All of this should be from the perspective of the web client. In other words, any data -- and especially any operations -- that aren't needed by the web client should not appear on these diagrams. A perfect example: the process to tally the votes. The web client doesn't care how this is done.
• There may be other aspects of the system we want to diagram in the near future, but right now we need to focus on these two data sets: a blank ballot for the client to render, and a filled-in ballot for the server to consume.

I hope this helps!

[windoverwater]

Yes. But regarding the tally, the web client will care about displaying the output. Ideally it would be formatted data but it is not and we probably do not have the time to make is so. Hence, it will probably remain in random log/logger output.

Regardless, it would be compelling from a demo point of view if the web client did something more than just display the logger output. For example, if it could convert some of the output into click-able hyperlinks might make for a more compelling demo but that is a UX TBD once we have some end users try it out.

Regardless of the logger output, it is important to convert the ballot check sheet into hyperlinks as well. This piece is easy to convert into a formal data structure within the demo time frame.

It is these two reasons why the initial pass at the UML includes both the ballot check and a tally operation class.

We can talk about this in person tomorrow :-)

[stratofax]

Sounds good! We can work on the diagram tomorrow, for sure

[windoverwater]

Here is a first pass at just the blank ballot first two endpoints.

Note - the solid black diamonds are 'has-a' relationships (a.k.a. contains/references/composition) and the hollow arrows are 'is-a' relationships (inheritance)

classDiagram
  Choice *-- Selection
  Ballot *-- Contest
  Contest *-- Selection
  Choice *-- Ticket

  class Choice {
    +String name
    +String party
    +Dict ticket
    +String choice_type
  }

  class Selection {
    +Int index
    +String name
  }

class Ticket {
    +String name
    +String party
}

  class Contest {
    +List choices # order is important
    +String vote_variation # RCV, plurality
    +String uid # unique to election only
    +Float win_threshold # default = 0.5
    +Int votes_allowed # defines overvote
    +String write_in # unimplemented
    +List selection # index + name
  }

  class Ballot {
    +List active_ggos # order is important
    +Dict contests # ordered by active_ggos
    +String ballot_status # blank or cast
  }

Loading