ASDF Coordinates Schemas

Common errors

• asdf.exceptions.ValidationError: Tag 'tag:astropy.org:astropy/coordinates/skycoord-1.0.0' not found in schema

  cause The ASDF library could not find the schema definition required to validate the `SkyCoord` tag. This typically means the extension that provides this schema (e.g., `asdf-astropy`) is not installed or properly registered.
  fix Install `asdf-astropy` to register the necessary schemas and converters: `pip install asdf-astropy`.

• TypeError: 'SkyCoord' object is not ASDF-serializable

  cause When attempting to write an `astropy.coordinates.SkyCoord` object to an ASDF file, the `asdf` library reported that it doesn't know how to serialize this Python object. This indicates that the corresponding converter for `SkyCoord` is not registered.
  fix Ensure that `asdf-astropy` is installed. It provides the necessary converters for `astropy.coordinates` objects to be serialized into ASDF files: `pip install asdf-astropy`.

Warnings

• gotcha Users should generally install `asdf-astropy` instead of `asdf-coordinates-schemas` directly. `asdf-coordinates-schemas` only provides the schema definitions, while `asdf-astropy` provides the necessary Python converters and automatically registers these schemas with the `asdf` library for practical usage.
  Fix: Ensure `asdf-astropy` is installed: `pip install asdf-astropy`. This will automatically install `asdf-coordinates-schemas` as a dependency.
• breaking Major version changes in ASDF tags (e.g., `skycoord-1.0.0` vs. `skycoord-2.0.0`) signify breaking changes in the schema definition. If you are working with ASDF files created with older versions of `astropy.coordinates` or the ASDF standard, ensure your `asdf` and `asdf-astropy` installations are compatible with the schema versions used in those files.
  Fix: When creating ASDF files, be mindful of the ASDF standard version used. When reading, `asdf` is generally backwards compatible, but ensure your `asdf-astropy` package supports the specific schema version of the coordinates tag in the file. Consult `asdf-astropy` and `asdf` change logs for specific migration details.
• deprecated The core `asdf` library, which is fundamental to using `asdf-coordinates-schemas` indirectly, has deprecated `AsdfFile.open` in favor of `asdf.open` (as of ASDF 2.2). While not directly part of `asdf-coordinates-schemas`, users interacting with ASDF files should use the modern `asdf.open` approach.
  Fix: Replace `AsdfFile.open()` calls with `asdf.open()` for reading ASDF files. For example, `with asdf.open('file.asdf') as af:`.

Install

• pip install asdf-coordinates-schemas Install latest version

Imports

• Not applicable for direct import
  wrong:

  import asdf_coordinates_schemas

  correct:

  This library primarily provides schema definitions for the ASDF ecosystem. It is not typically imported directly into Python code for use of its classes or functions. Its schemas are automatically registered and used by the `asdf` library when `asdf-astropy` is installed.

  While importing the package is syntactically correct, it offers no direct user-facing API. The value lies in its registered schemas.

Quickstart

This quickstart demonstrates how `asdf-coordinates-schemas` works implicitly. By installing `asdf-astropy` (which depends on `asdf-coordinates-schemas`), `astropy.coordinates` objects like `SkyCoord` can be seamlessly serialized into and deserialized from ASDF files. The schemas provided by this library ensure the correct validation and structure of the coordinate data within the ASDF file.

import asdf
import astropy.units as u
from astropy.coordinates import SkyCoord, ICRS

# This example relies on asdf-astropy being installed to register the schemas and converters.
# If you run this without asdf-astropy, it will likely fail to serialize SkyCoord.

# Create an Astropy SkyCoord object
coord = SkyCoord(ra=10.68458 * u.deg, dec=41.26917 * u.deg, frame=ICRS())

# Create an ASDF tree with the coordinate object
tree = {'my_coordinate': coord}

# Save the ASDF tree to a file
# This will use the schemas provided by asdf-coordinates-schemas (via asdf-astropy)
with asdf.AsdfFile(tree) as af:
    af.write('my_coordinates.asdf')

print("ASDF file 'my_coordinates.asdf' created successfully.")

# Read the ASDF file back
with asdf.open('my_coordinates.asdf') as af_read:
    read_coord = af_read['my_coordinate']
    print(f"Read coordinate: {read_coord}")
    print(f"Type: {type(read_coord)}")