Tag Versioning Overview

Purpose

This document is intended to be a sketch of my understanding of the way that tag and schema versioning currently works. It is also intended to clarify any ambiguities that exist in the standard. Hopefully this document can be used to polish and simplify the existing ASDF implementation, and eventually become adapted as part of the official documentation.

Background

ASDF is capable of serializing and deserializing Python objects. That is, ASDF can convert a Python object into a representation that can be stored in a file (i.e. serialize the object). Upon reading the file, it can convert the stored representation back into an instance of the original type (i.e. deserialize the object). In this document, use of the term "serialize" implies the ability for both serialization and deserialization.

ASDF metadata is represented using YAML, which natively has analogues for basic Python types (namely str, int, float, list, dict, tuple). This means that the basic Python types can be serialized without any modifications or extensions to the YAML implementation that we use.

However, it is often useful or necessary for ASDF to serialize more complicated Python types. In these cases, we must explicitly tell ASDF how a given object should be represented in YAML, and how a YAML representation can be reconstructed into an instance of the original object.

Notes/outline for future work here:

• Not only does ASDF serialize types, but files must be validated
• Clarification of terminology: multiple meanings of "tag", "schema", "type", etc.