Restructure Schemas

[jwhitlock]

The current schemas almost work. The "PATCH" schemas seem like a better base schema (all optional fields), and switching would eliminate a current mypy error around the EmailPatchSchema and the EmailBase schema for the primary_email field (Incompatible types in assignment (expression has type "Optional[str]", base class "EmailBase" defined the type as "str"). One possible hierarchy:

• Base schema - all data items are optional, no DB-only fields like timestamps (appropriate for PATCH input, API methods)
  • Create schema - Some items are required, others have defaults if omitted (appropriate for POST input)
    • Upsert schema - More items are required (appropriate for PUT input)
      • Output schema - All items are required, includes timestamps (appropriate for API output)
        • Model schema - Adds DB-only fields, timestamp setters (appropriate for bulk importer)

In the case of emails:

• EmailBaseSchema - All data fields optional
  • EmailCreateSchema - primary_email now required, view will generate email_id if omitted
    • EmailUpsertSchema - email_id now required
      • EmailOutputSchema - All data is required, adds timestamps, orm_mode=True
        • EmailModelSchema - Adds extra="forbid" to forbid extra fields. In the future may include additional DB-only columns.

I'd also like to:

• Use class Config for descriptions and examples. I'm jealous of Taskcluster's structured data for API definitions, and I see this as a transitional step, as well as removing some duplication in the docs
• Make mypy happier, maybe even required for schemas
• Make the output of full contact data more natural. There's too much manual creation of ContactSchema and amo=contact.amo or AddOnsSchema() nonsense.

This all seems possible to me, but I expect details to change as I restructure the code.

┆Issue is synchronized with this Jira Task