Skip to content

Commit

Permalink
Document ADR 0008 about unrecognized fields
Browse files Browse the repository at this point in the history
Even though, this ADR documents something already implied in the TUF
spec in [document formats](https://theupdateframework.github.io/specification/latest/#document-formats)
it seems better to document this decision clearly so that it could be
referenced and give an explanation why someone can load a metadata file
with additional unrecognized fields.

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
  • Loading branch information
MVrachev committed Apr 8, 2021
1 parent cd39bff commit 74c109d
Showing 1 changed file with 44 additions and 0 deletions.
44 changes: 44 additions & 0 deletions docs/adr/0008-accept-unrecognised-fields.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Accept metadata that includes unrecognised fields

- Status: accepted
- Date: 2021-04-08

Technical Story: https://github.com/theupdateframework/tuf/issues/1266

## Context and Problem Statement

The current reference implementation will ignore unrecognized fields in a
metadata file when loading it.
This leads to the side effect that if you read a metadata file with unrecognized
fields and imidiatly write it back to the disk, this file will be modified.

Furthermore, some TAPs ([6](https://github.com/theupdateframework/taps/blob/master/tap6.md), [10](https://github.com/theupdateframework/taps/blob/master/tap10.md), [14](https://github.com/theupdateframework/taps/blob/master/tap14.md), [15](https://github.com/theupdateframework/taps/blob/master/tap15.md), and [16](https://github.com/theupdateframework/taps/blob/master/tap16.md)) are relying on that unrecognized
fields will be accepted to introduce new fields to the specification without
making the metadata invalid for older clients which don't recognize the field.

## Decision Drivers
- The TUF specification implies support for custom attribute-value fields
See [Document formats](https://theupdateframework.github.io/specification/latest/#document-formats)
- Backward compatibility
- If we perform the following operations on a metadata file with no
intermediate operations:
1. read the metadata file
2. write the metadata file back to the disk
the checksum (the content) of the file must not be changed.
- Flexibility to add new fields in the spec without adding breaking changes.

## Considered Options
- Ignore and drop unrecognized fields.
- Ignore, but store unrecognized fields as an additional attribute.

## Decision Outcome

Chosen option: "Ignore, but store unrecognized fields as an additional
attribute."
The motivations for this decision are that the TUF specification already implies
that we should accept unrecognized fields for backward compatibility and easier
future extensibility.

Additionally, it seems unacceptable to change a metadata file content just by
reading and writing it back.

0 comments on commit 74c109d

Please sign in to comment.