Add validation guidelines

[lukpueh]

There seems to be agreement to discontinue the securesystemslib schema facility (see secure-systems-lab/securesystemslib#183). We still need to be able to validate all inputs at the user boundary (type annotations should make this a lot easier), and provide tools to check if metadata is spec compliant (maybe we can use something like JSON schema?).
At any rate, it would be helpful for contributors to provide guidelines for validation.

[lukpueh]

Using in-toto style ValidationMixin might be a commendable way to validate metadata in memory (see the mixin and it's usage for details).

[lukpueh]

secure-systems-lab/code-style-guidelines#18 has an interesting discussion about input validation, control flow and program consistency.

[joshuagl]

The approach I would take to this research project, is:

Understand the current validation mechanism in use:

• Review securesystemslib.schema, its purpose and its flaws.
• Review in-toto's ValidationMixin, which validates metadata in memory utilising securesystemslib.schema (see example usage).

Review existing external/3rd-party solutions:

• pydantic -- uses type annotations to provide data validation (runtime type hint validation) and settings management.
• marshmallow -- uses schemas to provide simplified object serialisation, deserialisation, and input data validation.

Understand options for custom validation logic

• Descriptors seem well suited for attribute validation. However, they may not allow for the currently supported pattern of initialising empty objects, assigning values, and later validating them (from Add input validation to simple metadata api #1140 (comment)).

For each of the three possible new approaches suggested above, I would expect some prototype code to be written to get a feel for how the approach fits with our new code. I'd be inclined to base on #1279, if it has not already been merged by the time we get to experimenting with new approaches.

Goals:
We want to be able to:

• validate all inputs at the user boundary.
• provide tools to check if metadata is specification compliant.

Outcomes:

• Submit an ADR on input validation, summarising different approaches and making a recommendation for the project.

Considerations:

• Are the stated goals appropriate/sufficient?
• Which Python versions are supported by the various mechanisms explored?
• pip is about to become a major user and has to vendor any dependencies we add. This may be a good argument for a custom implementation, or perhaps not if the transitive closure of dependencies to vendor is small.
• Be aware of performance impact (see Revise schema and formats facility secure-systems-lab/securesystemslib#183 (comment)).
• Other third-party solutions exist i.e. desert and typical.

Next steps:

• Input validation for simple metadata API (Add input validation to simple metadata api #1140).

---

See also, the related issue on input validation for metadata API: #1140

Other possibly useful references:

• Unreachable else best practice secure-systems-lab/code-style-guidelines#18 has a discussion about input validation, control flow and program consistency.
• blog post about instance attribute validation techniques including the in-toto approach and Descriptors
• The section of the Hypermodern Python guide on typing discusses data validation with Desert and Marshmallow