[RFD] API Tagging

[jsollom-hpe]

API Tagging

What do you propose?

Tagging is a well-known concept which is widely utilized across the industry. Its main purpose is to allow various policies or presentation filters to be applied across services and resource types. This guideline is meant to introduce uniform tagging to allow for the creation of tags-based policies across different services.

Each service would be responsible for providing endpoints to CRUD (create, read, update, and delete) tags on the resources it provides.

Tag Structure

• A tag is a key-value pair of character strings that can be attached to the resource by either a user or a service.
• Users of this API MUST not be able to edit or remove service-originated tag, indicated with the prepended string 'internal:'.
• Resources that support tagging MUST support up to 50 user-originated tags per resource. Number of service-originated tags is not restricted.
• Tags MUST be stored by preserving input case sensitivity. However, tag keys and values are considered case insensitive. This means if a given resource has the tag "location" : "San Jose" then the same resource MUST NOT have "Location" : "New York" tag as it is considered the same key.
• Search on the tags MUST be case insensitive. For REST API implementation for tags please refer to query parameters specific for tags in API Standard .
• For a given resource, there can only be one value for a particular tag key.
• Tag key MUST have 1-128 characters.
• Tag value can have a maximum of 256 characters, but they are allowed to be an empty string.
• Allowed characters for both keys and values are letters, numbers, spaces representable in UTF-8, and the following characters: _ . : = + - @
• Null is not an allowed value. Instead, empty string ("") MUST be supported to enable 'label' semantics.
• Tags MUST NOT be used to store sensitive data, such as personally identifiable information.
• Service-originated tags MUST start with a prefix "internal:". User-defined tags MUST NOT start with the "internal:" prefix.
  • A registry of prefix namespaces should be managed alongside this standard for services to reserve and use for their corresponding service-originated tags. For example: "internal:sdwan:", "internal:backups:", etc.

Tagging Implementation Responsibilities

• Tags MUST be stored and presented in the context of the specific resource and MUST NOT have an independent lifecycle i.e. tags cannot be created, updated or deleted as standalone entities.
• Services own the APIs for tagging (& untagging) resources and for querying the resources based on tags.
• Events MUST be published by the services whenever any tag is modified on any resource.

Related RFDs

Establishment of an API Contract specification for OpenCHAMI

• This RFD should be part of the API contract specification.

[alexlovelltroy]

This is a great start, and I appreciate the effort to bring consistency to how we handle tagging across services. I’d like to suggest tightening the scope of this initial RFD and relaxing some of the specification rules to better accommodate flexibility and future evolution.

Narrow Scope for Initial Standardization

Tags, Groups, Labels, and Annotations all serve slightly different purposes and usage patterns. When we talk about tagging, we should also clarify which of the other concepts should be available to API developers and how to appropriately use each one. Attempting to define them all within a single tagging standard may lead to confusion or overly rigid constraints. It may be more pragmatic to focus this RFD on a minimal, interoperable core model, deferring broader questions around ownership hierarchies, annotations, or labels to follow-on efforts.

For example:

• Tags might be free-form and user-defined.
• Annotations could be structured metadata intended for machine parsing.
• Labels may serve categorical purposes and enable resource filtering or grouping.

Trying to encompass all of these in one set of semantics and validation rules might hinder adoption or lead to conflict with domain-specific needs.

Conflict Management Should Be Contextual

I agree that certain constraints (e.g., mutual exclusivity of ownership tags) are essential. However, I suggest these be defined by domain-specific policies rather than enforced universally in the API standard. Instead of precluding conflicting tags in the spec, we could provide a validation layer or policy enforcement mechanism that can be plugged in per domain or service.

This would allow us to say: "Tags are flexible, but some sets of tags are mutually exclusive in specific contexts."

Questioning the System vs. User Distinction

I'm also skeptical about enforcing a strong system/user distinction at the API level. Instead of embedding rigid logic about internal tags (like the internal: prefix) into every implementation, we might consider a predefined schema of standardized tags with well defined uses—similar to the OCI Image Spec Annotations. Services can recognize and act on known keys without preventing users from using similar keys if they choose.

[jsollom-hpe]

The vision for tags was that they could handle the aforementioned roles:

• Tags
• Groups
• Labels
• Annotations

I listed a definition for each 'role'.

Tags

• Purpose: Used to categorize or group resources by topic or characteristic.
• Usage: Often applied in OpenAPI (Swagger) specs to group endpoints. Can also tag individual resources (e.g., a blog post tagged as “tech”).
• Example:

{
  "id": 123,
  "title": "REST API Best Practices",
  "tags": ["api", "rest", "best-practices"]
}

Groups

• Purpose: Represent logical collections of related resources.
• Usage: Common in APIs managing users, devices, or entities—“groups” may define access control, visibility, or behavior.
• Example:

{
  "groupId": "engineering-team",
  "members": ["user123", "user456"]
}

Labels

• Purpose: Key-value pairs used to identify and filter resources.
• Usage: Widely used in systems like Kubernetes or cloud APIs for resource selection and management.
• Example:

{
  "name": "compute-instance-1",
  "labels": {
    "env": "prod",
    "tier": "backend"
  }
}

Annotations

• Purpose: Also key-value pairs, but intended for attaching non-identifying metadata (i.e., not used for filtering).
• Usage: Designed for tooling or users to store additional data without affecting logic or behavior.
• Example:

{
  "name": "job-runner",
  "annotations": {
    "creator": "admin",
    "notes": "This instance handles batch jobs."
  }
}

The RFD suggests that the attribute 'tags' could fulfill all four roles. Rather than using the separate attributes of 'groups', 'labels', and 'annotations', they would all simply be 'tags'.

Of the four examples, the envisioned purpose for tags, which is resource selection and filtering, most closely aligns with labels and tags. The following examples show how tags could satisfy each role.

Tag

The value is empty because the key says it all.
Example:

{
  "id": 123,
  "type": "compute",
  "tags": [{"x86-64": ""}]
}

Groups

{
  "id": 123,
  "type": "compute",
  "tags": [{"group": "blue"}]
}

Labels

{
  "id": 123,
  "type": "compute",
  "tags": [{"GPU": "nvidia"}]
}

Annotation

{
  "id": 123,
  "type": "compute",
  "tags": [{"LastBooted": "2025-06-01"}]
}

Some of these examples are a little suspect because they show tags that should be attributes of a compute object. The compute could have an architecture attribute which would hold "x86-64".

Annotations seems to be the most spurious use of tags.

[alexlovelltroy]

I agree that storing a list of strings associated with a resource is a common problem that lends itself well to generalization. However, there are user experience implications that I think we should keep in mind before we generalize.

Briefly, separating these key value pairs and string-based tags into labels and annotations encourages better user experience when it matches other uses of those same terms.

• Annotations are generally stored inside the resource and travel with it. They are free-form and often include hierarchical schema. Generally not available for subselect/sorting of resources at the API level. See OCI Annotations for an example standard I think having a similar annotation standard for OpenCHAMI resources would be a good idea
• Labels are generally used at the API layer for grouping resources. These go beyond the fields that define a resource. These are typically not hierarchical. In CSM parlance, a label might be tenant-owner=foo1 . Replacing the label with another one effectively changes the tenant-owner of the resource.
• Tags are generally strings that are used as shorthand to describe resources. I find them easiest to think about with blog tags. An article can be tagged openchami, system-management, hardware-management, hpc to indicate that it is related to other similar articles without implying a hierarchy. Because they are free-form, they are more likely to suffer from subjective bias. Should I use hpc or high-performance-computing. What about hpc/ai? Strong rules around what tags are acceptable can mitigate some of the confusion.

Proposals

1. Reduce the scope of this RFD to simply Tags/Labels and open a question about which SMD fields might be better as tags and which common tags might be better as fields.
2. Remove references to reserved tag names. Every API call is an "external" call which originates with a user or on behalf of a user via a secondary service.
3. Consider opening an additional RFD to discuss annotations, possibly at a resource level
4. Consider opening an additional RFD on groupings (if needed) to explore if the user experience for them is somehow distinct from labels/tags

[rainest]

Do we have a proposed means of implementing this, or any other standard/inherited resource fields?

As-is services vary considerably in their API implementation, and I wouldn't even try to start implementing common fields until they share an API code generator.

Some design will stem from the wire format; you'll probably want that laid out first, with additional requirements over top. "Tags are presented as a JSON object, keys are the object keys, values are strings" implies a different set of requirements than "tags are an array of JSON objects, each object has a key and value field...".

[jsollom-hpe]

No proposed means of implementing this. It was guidance for OpenCHAMI services that could benefit from tagging.

"Tags are presented as a JSON object, keys are the object keys, values are strings" implies a different set of requirements than "tags are an array of JSON objects, each object has a key and value field...".

This is your own wording and is not referencing anything earlier in this RFD.

[rainest]

This is your own wording and is not referencing anything earlier in this RFD.

Sure--they're examples to demonstrate the point about the format probably having a significant impact on the constraints, since the OP doesn't propose a format, just constraints.

Approaching the constraints from that approach makes more sense to me than trying to start with a set of rules and then trying to design a format that fits neatly with them.

Something like:

Allowed characters for both keys and values are letters, numbers, spaces representable in UTF-8, and the following characters: _ . : = + - @

is hard to discuss in isolation. Are # and & forbidden because they're considered unsightly, or because we don't allow punctuation characters with intersecting lines? Having formats and use cases can lead into constraints more intuitively. Grounding principles like

• We're going to store these in JSON strings, and don't want to bother with escaping quotes.
• We're interested in using these in URL-based filters, so we'd like to exclude & and other control characters so that tags don't need percent-encoded characters.

will help ensure we're choosing constraints that support our use cases.

[Masber]

IMO, tags in HTTP APIs give users a flexible way to extend the system with data we don’t yet support. That’s valuable because it shows us real usage patterns and guides future evolution. Restricting labels only limits that feedback.

Splitting tags into two fields makes sense: system-owned (read-only) and user-defined. System-owned tags let us deliver new functionality faster, while user-defined tags preserve flexibility without conflicts.