{"id":8842,"library":"asdf-wcs-schemas","title":"ASDF WCS Schemas","description":"The `asdf-wcs-schemas` library provides ASDF (Advanced Scientific Data Format) schemas specifically designed for validating World Coordinate System (WCS) tags. It is a crucial component within the broader ASDF ecosystem, particularly for astronomical data, and is typically consumed as a dependency by higher-level packages like `gwcs`. The current version is 0.5.0, and its release cadence is tied to updates in the ASDF Standard and related scientific data formats.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/asdf-format/asdf-wcs-schemas","tags":["asdf","wcs","schemas","astronomy","scientific data","validation"],"install":[{"cmd":"pip install asdf-wcs-schemas","lang":"bash","label":"Direct installation"},{"cmd":"pip install gwcs","lang":"bash","label":"Recommended (installs as dependency)"}],"dependencies":[{"reason":"Core ASDF library for reading/writing files that use these schemas.","package":"asdf"},{"reason":"Primary package that uses these schemas for WCS object serialization/deserialization.","package":"gwcs","optional":true},{"reason":"Required by `asdf` and `astropy` dependencies for array handling.","package":"numpy","optional":true},{"reason":"Provides core astronomical objects (units, coordinates, modeling) often used with WCS.","package":"astropy","optional":true}],"imports":[],"quickstart":{"code":"import asdf\nfrom gwcs import wcs\nfrom astropy.modeling import models\nfrom astropy import units as u\nfrom gwcs.coordinate_frames import Frame2D, CelestialFrame\nfrom astropy.coordinates import ICRS\nimport os\n\n# Create a simple WCS object using gwcs\ndetector_frame = Frame2D(name=\"detector\", axes_names=(\"x\", \"y\"))\ncelestial_frame = CelestialFrame(reference_frame=ICRS(), name='icrs', unit=(u.deg, u.deg))\n\ntransform = models.Scale(0.1 * u.deg) & models.Scale(0.1 * u.deg)\n\nmy_wcs_object = wcs.WCS(transform, input_frame=detector_frame, output_frame=celestial_frame)\n\ntree = {\"my_wcs_data\": my_wcs_object}\n\n# Save the WCS object to an ASDF file\nfile_path = \"example_wcs.asdf\"\nwith asdf.AsdfFile(tree) as af:\n    af.write_to(file_path)\n\nprint(f\"WCS object saved to {file_path}\")\n\n# Read the ASDF file back. The WCS schemas are implicitly used for validation.\nwith asdf.open(file_path) as af:\n    loaded_wcs = af.tree[\"my_wcs_data\"]\n    print(\"Loaded WCS object:\")\n    print(loaded_wcs)\n\n# Clean up the created file\nos.remove(file_path)","lang":"python","description":"This quickstart demonstrates how to create and serialize a `gwcs` WCS object into an ASDF file. The `asdf-wcs-schemas` package is implicitly utilized by the `asdf` library during the write and read operations to validate the structure of the WCS data. This package is not intended for direct Python imports for user-level functionality, but rather provides the underlying schema definitions."},"warnings":[{"fix":"Install `gwcs` (or another ASDF extension that leverages WCS schemas) instead of `asdf-wcs-schemas` directly: `pip install gwcs`.","message":"Users should generally not install `asdf-wcs-schemas` directly. It is a schema-only package intended to be a dependency of other libraries, primarily `gwcs`. Installing `gwcs` will automatically pull in the correct version of `asdf-wcs-schemas`.","severity":"gotcha","affected_versions":"All"},{"fix":"Always ensure `asdf`, `gwcs`, and `asdf-wcs-schemas` are kept up-to-date and compatible. Refer to the `gwcs` documentation for recommended dependency versions. Check the `asdf` changelog for details on schema deprecations and moves.","message":"Older ASDF versions (e.g., prior to 2.6.0) might have included WCS schemas that were later deprecated and moved to the `gwcs` package. This can lead to validation issues or unexpected behavior if `asdf`, `gwcs`, and `asdf-wcs-schemas` versions are not compatible or if an old ASDF file is read with a new `gwcs` setup.","severity":"breaking","affected_versions":"<2.6.0 (for `asdf`)"},{"fix":"When creating or modifying ASDF files with WCS objects, ensure that the ASDF tags and manifest versions referenced in the file (e.g., `tag:stsci.edu:asdf/wcs/wcs-1.0.0`) are consistent with the `gwcs` library version being used for serialization. Always use the tags provided by `gwcs` rather than direct schema file references where possible.","message":"ASDF files rely on correct schema and manifest versions. Using incorrect or outdated tags/manifests for WCS objects can lead to validation failures or improper deserialization, even if the underlying `asdf-wcs-schemas` package is present.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade your `asdf` library to a version compatible with your `jsonschema` version, or explicitly pin `jsonschema` to a known compatible version (e.g., `<4.10.0`) if an `asdf` upgrade is not immediately feasible. Consult the `asdf` changelog for `jsonschema` compatibility notes.","cause":"Incompatibility between the `asdf` library's schema resolution mechanism and newer versions of the `jsonschema` validation library (e.g., `jsonschema` 4.10.0 and above with older `asdf` versions).","error":"jsonschema.exceptions.SchemaError: The metaschema specified by $schema was not found. Using the latest draft to validate, but this will raise an error in the future."},{"fix":"This issue is typically resolved by upgrading the `asdf` package to a version that properly handles the changes in `jsonschema`'s API. Ensure `asdf` and `jsonschema` dependencies are updated.","cause":"This error can occur during ASDF file validation when using incompatible versions of `asdf` and `jsonschema`, particularly seen with `jsonschema` 4.10.0 and above. It indicates that the validation process is attempting to call `.get()` on a list where a dictionary-like object (a schema definition) is expected.","error":"AttributeError: 'list' object has no attribute 'get'"}]}