Implementation:Iterative Dvc Annotations

Knowledge Sources	Iterative_Dvc
Domains	Metadata, Artifact_Management
Last Updated	2026-02-10 10:00 GMT

Overview

Public metadata dataclasses for attaching human-readable annotations to DVC outputs and artifacts, provided by the DVC library.

Description

The dvc/annotations.py module (52 lines) defines two dataclasses -- Annotation and Artifact -- that serve as the canonical metadata containers for DVC-tracked files and model registry artifacts.

The Annotation dataclass carries four optional fields: desc (a human-readable description), type (a category string such as "model" or "dataset"), labels (a list of string tags), and meta (a free-form dictionary for arbitrary key-value metadata). Each field has a corresponding class-level PARAM_* constant used as the serialization key in YAML files.

The Artifact dataclass extends the same set of annotation fields with a required path field that locates the artifact within the repository. This makes Artifact the primary data structure for entries in the artifacts section of dvc.yaml.

Both dataclasses provide a to_dict() method that serializes the instance to a dictionary, using funcy.compact to strip any None or empty values. The module also exports ANNOTATION_FIELDS (a list of field names from Annotation), ANNOTATION_SCHEMA (a voluptuous validation schema for annotation fields), and ARTIFACT_SCHEMA (which extends the annotation schema with a Required(path) entry).

Usage

Use Annotation when you need to attach metadata to DVC outputs (e.g., in dvc.yaml output definitions). Use Artifact when defining or reading entries from the artifacts section of dvc.yaml, such as when registering models in the DVC model registry. The validation schemas are consumed internally by DVC's YAML parsing layer to ensure well-formed configuration files.

Code Reference

Source Location

• Repository: DVC
• File: dvc/annotations.py
• Lines: L1-53

Signature

@dataclass
class Annotation:
    PARAM_DESC: ClassVar[str] = "desc"
    PARAM_TYPE: ClassVar[str] = "type"
    PARAM_LABELS: ClassVar[str] = "labels"
    PARAM_META: ClassVar[str] = "meta"

    desc: Optional[str] = None
    type: Optional[str] = None
    labels: list[str] = field(default_factory=list)
    meta: dict[str, Any] = field(default_factory=dict)

    def to_dict(self) -> dict[str, str]:
        ...


@dataclass
class Artifact:
    PARAM_PATH: ClassVar[str] = "path"
    PARAM_DESC: ClassVar[str] = "desc"
    PARAM_TYPE: ClassVar[str] = "type"
    PARAM_LABELS: ClassVar[str] = "labels"
    PARAM_META: ClassVar[str] = "meta"

    path: str
    desc: Optional[str] = None
    type: Optional[str] = None
    labels: list[str] = field(default_factory=list)
    meta: dict[str, Any] = field(default_factory=dict)

    def to_dict(self) -> dict[str, str]:
        ...

Import

from dvc.annotations import Annotation, Artifact

I/O Contract

Annotation Fields

Name	Type	Required	Description
desc	Optional[str]	No	Human-readable description of the output or artifact.
type	Optional[str]	No	Category string (e.g., "model", "dataset", "checkpoint").
labels	list[str]	No	List of string tags for classification. Defaults to an empty list.
meta	dict[str, Any]	No	Free-form dictionary for arbitrary key-value metadata. Defaults to an empty dict.

Artifact Fields

Name	Type	Required	Description
path	str	Yes	Path to the artifact file within the DVC repository.
desc	Optional[str]	No	Human-readable description (inherited from Annotation pattern).
type	Optional[str]	No	Category string (inherited from Annotation pattern).
labels	list[str]	No	List of string tags (inherited from Annotation pattern).
meta	dict[str, Any]	No	Free-form metadata dictionary (inherited from Annotation pattern).

Module-Level Exports

Name	Type	Description
ANNOTATION_FIELDS	list[str]	List of field names from the Annotation dataclass: ["desc", "type", "labels", "meta"].
ANNOTATION_SCHEMA	dict	Voluptuous validation schema for annotation fields.
ARTIFACT_SCHEMA	dict	Voluptuous validation schema that extends ANNOTATION_SCHEMA with a required path field.

Usage Examples

Creating Annotations

from dvc.annotations import Annotation, Artifact

# Create an annotation for a DVC output
ann = Annotation(
    desc="Trained sentiment classifier",
    type="model",
    labels=["nlp", "production"],
    meta={"framework": "pytorch", "accuracy": 0.95},
)
print(ann.to_dict())
# {'desc': 'Trained sentiment classifier', 'type': 'model',
#  'labels': ['nlp', 'production'], 'meta': {'framework': 'pytorch', 'accuracy': 0.95}}

# Create an artifact entry for dvc.yaml
artifact = Artifact(
    path="models/sentiment.pt",
    desc="Sentiment analysis model v2",
    type="model",
    labels=["nlp"],
)
print(artifact.to_dict())
# {'path': 'models/sentiment.pt', 'desc': 'Sentiment analysis model v2',
#  'type': 'model', 'labels': ['nlp']}

Related Pages

Implements Principle

• Principle:Iterative_Dvc_Artifact_Metadata