Merge pull request #1229 from lukpueh/adr0004

ADR0004: Justify extent of OOP in metadata model

Author: lukpueh

docs/adr/0004-extent-of-OOP-in-metadata-model.md

@@ -0,0 +1,48 @@
+# Add classes for complex metadata attributes
+
+* Status: accepted
+* Date: 2020-11-30
+
+Technical Story: https://github.com/theupdateframework/tuf/issues/1133
+
+## Context and Problem Statement
+Custom classes for the TUF signed metadata wrapper (Metadata) and metadata
+payload containers (Root, Timestamp, Snapshot, Targets) were added recently.
+Complex attributes on these classes are still represented as dictionaries.
+Should we add classes for these attributes too?
+
+## Decision Drivers
+
+* Transition to class-based role metadata containers in progress (see *"class
+  model"* links below)
+* Harden in-memory representation of metadata model
+* Replace `securesystemslib` schema validation (see *"schema checker"* link
+  below)
+
+## Considered Options
+
+* Use custom classes for complex attributes
+* Use dictionaries for complex attributes
+
+## Decision Outcome
+
+Chosen option: "Use custom classes for complex attributes", to provide a
+consistently object-oriented, well-defined, single source of truth about the
+TUF metadata model (not only its containers). In addition to convenience update
+methods, the model may be extended with self-validation behavior (see
+*"validation guidelines"* link below) to replace `securesystemslib` schema
+checks.
+
+### Negative Consequences
+
+* Implementation overhead
+* Less flexibility in usage and development (this is actually desired)
+* Maybe less idiomatic than dictionaries
+
+## Links
+
+* [class model](https://github.com/theupdateframework/tuf/pull/1112)
+* [class model (root)](https://github.com/theupdateframework/tuf/pull/1193)
+* [WIP: class model (complex attributes)](https://github.com/theupdateframework/tuf/pull/1223)
+* [new TUF validation guidelines](https://github.com/theupdateframework/tuf/issues/1130)
+* [securesystemslib schema checker issues](https://github.com/secure-systems-lab/securesystemslib/issues/183)

docs/adr/index.md

@@ -8,6 +8,7 @@ This log lists the architectural decisions for tuf.
 - [ADR-0001](0001-python-version-3-6-plus.md) - Default to Python 3.6 or newer for new development
 - [ADR-0002](0002-pre-1-0-deprecation-strategy.md) - Deprecation strategy
 - [ADR-0003](0003-where-to-develop-TUF-1-0-0.md) - Develop TUF 1.0.0 in a subdirectory of the current TUF implementation
+- [ADR-0004](0004-extent-of-OOP-in-metadata-model.md) - Add classes for complex metadata attributes
 
 <!-- adrlogstop -->