Package Metadata

This page defines standard metadata annotations for UDS Packages. UDS products use these annotations to support package discovery and presentation, regardless of where a package is published.

Note

This page uses RFC 2119 terminology.

These annotations are defined under metadata.annotations in your zarf.yaml package config:

zarf.yaml

kind: ZarfPackageConfig
metadata:
  annotations:
    dev.uds.title: "Example Package"
    dev.uds.categories: "Development, Testing"

Production annotations

You SHOULD include the annotations that apply to your package and the UDS products that consume it. The Products column identifies which products use each annotation.

Annotation	Description	Example	Products
dev.uds.title	Human-readable package title	"GitLab Runner"	UDS Registry, UDS Fleet, UDS Portal
dev.uds.categories	Dynamic category list	"Software Dev, Kubernetes (K8s)"	UDS Registry, UDS Fleet
dev.uds.keywords	Search keywords	"CI/CD Pipelines, Automation, GitLab"	UDS Registry
dev.uds.tagline	Short package tagline	"Open Source CI/CD Job Execution Tool"	UDS Registry
dev.uds.icon	Base64 icon as data URI	"data:image/png;base64,iVBORw0KGgo..."	UDS Registry, UDS Fleet, UDS Portal

Implementation guidelines

These guidelines apply to the annotations you choose to include.

Title (dev.uds.title)

• MUST be a human-readable title-case string that clearly identifies the package.
• SHOULD match the official product name when packaging existing software.

Categories (dev.uds.categories)

• MUST be a comma-with-space-separated string ("Category One, Category Two").
• SHOULD include 1-3 categories from these standard options:

Standard categories

• AI
• Cloud Native
• Collaboration
• Command And Control
• Cybersecurity
• Data Engineering
• Databases
• Digital Engineering
• IT Management
• Infrastructure
• Kubernetes (K8s)
• Load Balancing
• Networking
• Observability
• Operator
• Pipelines
• Productivity
• Security
• Software Dev
• Web

• MAY include new categories when existing categories do not adequately describe the package.

Keywords (dev.uds.keywords)

• MUST be a comma-with-space-separated string of relevant search terms (recommended 3-7).
• SHOULD include alternative terms and abbreviations users might search for.

Tagline (dev.uds.tagline)

• MUST be one concise sentence (recommended 5-10 words) describing package function.

Icon (dev.uds.icon)

Icons appear in square UI slots from 24x24 to 80x80 CSS pixels. Choose artwork that remains legible at each size and keep the encoded value compact to limit growth in zarf.yaml and OCI annotations.

• MUST be encoded as a base64 data URI.
• SHOULD keep the complete data URI within 64 KiB (65,536 bytes), including the media type prefix and base64 payload.
• SHOULD use SVG (preferred) or PNG with a square canvas and transparent background.
• SHOULD use raster images of at least 160x160 pixels to support the largest UI size at 2x pixel density. Larger images are acceptable within the byte budget.
• SHOULD include a valid, square viewBox for SVG icons; fixed pixel dimensions are not required.

Tip

Keep annotations concise and user-centered. Think about how the package appears in registry search and detail views.

Provisional annotations

These annotations are experimental and may evolve over time. They MAY be used where applicable for your application.

Annotation	Description	Example	Products
dev.uds.system	Whether a package is system-level (OS/firmware) vs application-level	"true"	UDS Fleet
dev.uds.compat/[label-name]	Hardware compatibility requirement for the target cluster; [label-name] is a placeholder for a capability label defined by your platform integrator	dev.uds.compat/databus: can,can-fd	UDS Fleet

Provisional implementation guidelines

Hardware compatibility (dev.uds.compat/*)

The dev.uds.compat/* annotation scheme lets package authors declare hardware compatibility requirements that UDS Fleet enforces before making a package available for deployment to a cluster. Each annotation key targets a specific compatibility dimension; each value is the set of accepted identifiers for that dimension.

The label names and values available to you are defined by your platform integrator — the organization responsible for orchestrating the deployment ecosystem you are targeting (for example, a systems integrator coordinating a multi-vendor solution). That integrator provides an initialization process that stamps each cluster with its hardware capabilities as labels, and publishes a spec of what label names and values package authors can use.

• [label-name] MUST match a label name from your platform integrator’s compatibility spec. Consult that spec for available label names and values before writing compat annotations.
• Values MUST be a comma-separated list with no spaces (can,can-fd). Multiple values within one annotation use OR semantics: the cluster must match at least one.
• Multiple dev.uds.compat/* annotations on the same package use AND semantics: the cluster must satisfy all of them.
• A package with no dev.uds.compat/* annotations has no compatibility constraints and deploys to any cluster.

zarf.yaml

kind: ZarfPackageConfig
metadata:
  annotations:
    # Cluster must have CAN OR CAN-FD databus, AND obd2-extended telematics
    dev.uds.compat/databus: can,can-fd
    dev.uds.compat/telematics: obd2-extended

Note

If your platform integrator has not published a compatibility spec for your target ecosystem, contact them before adding dev.uds.compat/* annotations. Declaring a label name that no cluster in the environment carries will prevent the package from deploying anywhere in that environment.

Related documentation

• UDS Package Requirements - pre-publish checklist for required capabilities and standards.
• Create a UDS Package - end-to-end guide for building a package that meets UDS requirements.