---
id: annotatedyaml
version: "1.0.2"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# annotatedyaml — Annotated YAML that supports secrets for Python

License: permissive · Maintenance: active · Downloads: 412.1K/mo

## What it is and what it does

annotatedyaml is a YAML parser and validator for Python that combines YAML parsing with schema validation and secrets support. It wraps pyyaml for parsing and voluptuous for schema validation, allowing developers to define typed, validated configuration structures in YAML while handling sensitive data securely. The package is in pre-alpha and requires Python 3.13 or later.

The package is designed to handle configuration files that need both structural validation and the ability to reference or embed secrets. It appears to be part of the Home Assistant ecosystem but is published as a standalone library. With significant adoption, its pre-alpha status and recent release date mean the API and behavior may still evolve.

Use it for:

- Validate Home Assistant configuration YAML files with type checking and schema enforcement
- Parse application config files that contain both public settings and secret references
- Define and enforce YAML schema structures using voluptuous validators in Python
- Load and validate typed configuration data from YAML with automatic error reporting

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parses and validates YAML files with support for embedded secrets and type annotations, using a schema-based validation approach.

Yes, with conditions. The package is actively maintained and permissively licensed, making it suitable for projects requiring YAML validation with secrets support. However, its pre-alpha status and Python 3.13-only requirement limit adoption; evaluate whether your environment supports Python 3.13 and whether pre-alpha stability is acceptable for your use case. No known vulnerabilities.

## Install

pip install annotatedyaml
uv add annotatedyaml
poetry add annotatedyaml

## Installing annotatedyaml

Before you install: Medium install friction due to compiled wheels across multiple Python versions and platforms. Active maintenance with recent commits; however, the package is in pre-alpha status (Development Status :: 2) and has been in active development for less than a year, so stability is not yet established.

License in practice: Licensed under Apache-2.0 (permissive), allowing use in commercial and private projects with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

pip install annotatedyaml

import annotatedyaml
from voluptuous import Schema, Required

schema = Schema({Required('key'): str})
data = annotatedyaml.load(open('config.yaml'), schema=schema)

Requires Python 3.13 or later; pyyaml, propcache, and voluptuous must be available.

Verify before relying:

- How secrets are embedded and retrieved within YAML (encryption method, storage format, or reference mechanism not detailed in excerpt)
- Whether the package integrates with Home Assistant or is usable standalone
- Performance characteristics when validating large YAML files
- Exact validation error messages and debugging experience

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 412.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

yaml parsing with secrets, annotated yaml validation, yaml schema validation, yaml with type hints, secure yaml configuration, yaml secrets management, configuration file validation, yaml-validation, secrets-management, schema-validation

[View on SkillFed](https://skillfed.io/packages/annotatedyaml) · [View on PyPI](https://pypi.org/project/annotatedyaml/)