# aws.osml.formats

Strongly-typed Python dataclass models for SICD and SIDD XML metadata,
auto-generated by [xsdata](https://xsdata.readthedocs.io/) from the NGA XML schemas.
Do **not** edit generated files by hand. The package also contains `model_utils.py`,
which provides pre-configured parsers and serializers for working with these models.
This package does **not** include sensor-model construction logic (see
{doc}`/api/metadata`) or pixel processing (see {doc}`/api/image-processing`).

## Dependencies

`formats` depends only on **xsdata** (external) and makes no sibling-package imports.
It is imported by `metadata` (SICD/SIDD sensor-model builders) and by
`image_processing` (SICD/SIDD metadata updaters during ortho/chip generation).

## Design

Generated dataclasses mirror the XML schema structure one-to-one — XML element names
map to Python field names via xsdata naming conventions, preserving the schema's
type hierarchy and nesting.

Multiple schema versions coexist as separate sub-modules:

- **SICD** — v1.2.1, v1.3.0
- **SIDD** — v1.0, v2.0, v3.0

`model_utils.py` exposes `sicd_parser`, `sicd_serializer`, `sidd_parser`, and
`sidd_serializer` — these are the correct entry points for parsing and serializing
XML strings. Prefer them over constructing raw xsdata parsers directly.

## Contributor rules

- To update models after a schema change, re-run xsdata code generation against the
  new XSD. Do **not** manually patch generated files.
- To add a new schema version, add a new sub-package and regenerate.
- The `formats` directory is excluded from Ruff linting (configured in `pyproject.toml`).

```{eval-rst}
.. automodule:: aws.osml.formats
   :members:
   :undoc-members:
   :show-inheritance:
```

## SICD Models

```{eval-rst}
.. automodule:: aws.osml.formats.sicd
   :members:
   :undoc-members:
   :show-inheritance:
```

## SIDD Models

```{eval-rst}
.. automodule:: aws.osml.formats.sidd
   :members:
   :undoc-members:
   :show-inheritance:
```