Amazon S3 annotations: attach rich, queryable context directly to your objects | Amazon Web Services

Amazon S3 annotations let organizations attach rich, mutable context directly to objects without rewriting the underlying data. Each object can have up to 1,000 named annotations, with a combined limit of 1 GB, in formats such as JSON, XML, YAML, or plain text. The annotations move with objects during copying and replication, can be queried through S3 Metadata tables, and are intended to support large-scale analytics and AI-driven workflows.

Richer Metadata at Object Scale

• Annotations address limitations of existing S3 metadata features:
  • System metadata describes properties such as size and storage class.
  • Object tags support operational tasks but are limited to 10 immutable tags.
  • User-defined metadata is limited to approximately 2 KB of headers and must be supplied during upload.
• Annotations can be modified or deleted independently without rewriting the object.
• Each annotation has a unique name and can hold up to 1 MB, with up to 1 GB total per object.
• Supported content includes structured formats such as JSON, XML, and YAML, as well as plain text.

Supporting AI and Industry Workflows

• AI-generated transcripts, summaries, classifications, ratings, and technical specifications can remain attached to the relevant data.
• Media companies can store transcripts, moderation results, subtitles, licensing information, and media specifications alongside video assets.
• Financial institutions can attach investment summaries and sentiment analysis to research documents for autonomous discovery.
• Life sciences organizations can add regulatory status, cohort information, and approval chains to clinical-trial data.
• Annotations remain available for objects in archival storage classes without restoring the objects or paying retrieval charges.

Object Lifecycle and Synchronization

• Annotations automatically move with objects during copy, replication, and cross-Region transfers.
• S3 removes annotations when the associated object is deleted.
• This reduces dependence on separate metadata databases or sidecar files and avoids synchronization overhead.
• Different teams or enrichment processes can maintain separate annotations on the same object without overwriting one another.

Working with Annotations

• IAM or bucket policies must grant:
  • s3:PutObjectAnnotation
  • s3:GetObjectAnnotation
• The main APIs are:
  • PutObjectAnnotation to create or update an annotation
  • GetObjectAnnotation to retrieve one annotation
  • ListObjectAnnotations to view all annotations on an object
  • DeleteObjectAnnotation to remove an annotation
• Reusing an annotation name with PutObjectAnnotation updates its content.
• For multipart uploads, annotations are added after the upload is completed.
• The example uses separate mediainfo JSON and ai_summary text annotations on a video object.

Querying Through S3 Metadata

• When S3 Metadata is enabled, annotations automatically populate managed annotation tables.
• These tables can be queried with Amazon Athena and other analytics engines.
• The S3 Tables MCP server provides a standardized interface for AI models and agents to query annotation data using natural-language workflows.
• This enables discovery across large collections of S3 objects without retrieving the objects themselves.

S3 annotations are most useful when object context is large, frequently updated, and needed for cross-object search or AI automation. Organizations should use them to keep business and machine-generated metadata directly associated with the data while using S3 Metadata tables for scalable querying.