# resource-labels Specification

## Purpose
TBD - created by archiving change add-key-value-labels. Update Purpose after archive.
## Requirements
### Requirement: Resource stores labels as key-value pairs

Each resource SHALL have a Labels property that stores arbitrary string key-value pairs. Labels SHALL be initialized to an empty collection and MUST NOT be null.

#### Scenario: New resource has empty labels

- **WHEN** a resource is created
- **THEN** the resource has an empty Labels collection

#### Scenario: Labels are stored per resource

- **WHEN** a label with key "env" and value "production" is added to resource "web-01"
- **THEN** resource "web-01" has Labels containing "env" -> "production"
- **AND** other resources are unaffected

### Requirement: User can add a label to a resource

The system SHALL allow users to add a label (key-value pair) to any resource via CLI and Web UI.

#### Scenario: Add label via CLI

- **WHEN** user runs `rpk servers label add web-01 --key env --value production`
- **THEN** resource "web-01" has label "env" with value "production"
- **AND** the change is persisted to YAML

#### Scenario: Add label via Web UI

- **WHEN** user opens the resource card, clicks add label, enters key "owner" and value "team-a", and submits
- **THEN** the resource has label "owner" with value "team-a"
- **AND** the change is persisted

#### Scenario: Add label to existing key overwrites value

- **WHEN** resource "web-01" has label "env" with value "staging"
- **AND** user adds label "env" with value "production"
- **THEN** resource "web-01" has label "env" with value "production"

### Requirement: User can remove a label from a resource

The system SHALL allow users to remove a label by key from any resource via CLI and Web UI.

#### Scenario: Remove label via CLI

- **WHEN** resource "web-01" has label "env" with value "production"
- **AND** user runs `rpk servers label remove web-01 --key env`
- **THEN** resource "web-01" no longer has label "env"
- **AND** the change is persisted to YAML

#### Scenario: Remove label via Web UI

- **WHEN** resource has label "owner" with value "team-a"
- **AND** user clicks remove on that label in the resource card
- **THEN** the resource no longer has label "owner"
- **AND** the change is persisted

#### Scenario: Remove nonexistent key is no-op

- **WHEN** resource "web-01" does not have label "env"
- **AND** user runs `rpk servers label remove web-01 --key env`
- **THEN** no error occurs
- **AND** the resource is unchanged

### Requirement: Labels persist in YAML

Labels SHALL be serialized and deserialized from the YAML resource file. Existing resources without a labels section SHALL deserialize with an empty Labels collection.

#### Scenario: Labels are written to YAML

- **WHEN** resource "web-01" has labels "env: production" and "owner: team-a"
- **AND** the resource is saved
- **THEN** the YAML file contains a labels section for that resource with the key-value pairs

#### Scenario: Legacy YAML without labels deserializes correctly

- **WHEN** resource in YAML has no labels section
- **THEN** the resource deserializes with an empty Labels collection

### Requirement: Labels are displayed in resource views

The system SHALL display labels in resource describe output (CLI) and resource cards (Web UI).

#### Scenario: Describe shows labels

- **WHEN** resource "web-01" has labels "env: production" and "owner: team-a"
- **AND** user runs `rpk servers describe web-01`
- **THEN** the output includes the labels in key-value format

#### Scenario: Resource card shows labels

- **WHEN** resource has label "env" with value "production"
- **AND** user views the resource card in Web UI
- **THEN** the label is displayed

### Requirement: Label key and value are validated

The system SHALL validate label key and value before adding. Key and value MUST be non-empty after trimming. Key length MUST NOT exceed 50 characters. Value length MUST NOT exceed 200 characters.

#### Scenario: Empty key is rejected

- **WHEN** user attempts to add a label with empty or whitespace-only key
- **THEN** a validation error is returned
- **AND** the resource is not updated

#### Scenario: Empty value is rejected

- **WHEN** user attempts to add a label with empty or whitespace-only value
- **THEN** a validation error is returned
- **AND** the resource is not updated

#### Scenario: Key exceeds length limit is rejected

- **WHEN** user attempts to add a label with key longer than 50 characters
- **THEN** a validation error is returned
- **AND** the resource is not updated

#### Scenario: Value exceeds length limit is rejected

- **WHEN** user attempts to add a label with value longer than 200 characters
- **THEN** a validation error is returned
- **AND** the resource is not updated

#### Scenario: Add label for nonexistent resource fails

- **WHEN** user attempts to add a label to a resource that does not exist
- **THEN** a not-found error is returned
- **AND** no change is persisted