Implement data-groups endpoint

[bburda]

Summary

Implement GET /{entity-path}/data-groups endpoint to return logical groupings of data items. Data groups are custom collections defined in the capability description or derived from namespace structure. They allow clients to organize and filter data resources by logical purpose (e.g., "motion", "environment").

Data groups differ from data categories: categories are fixed semantic types (identData, currentData, storedData, sysInfo), while groups are user-defined logical collections that can span multiple categories.

Currently the route is registered in rest_server.cpp but returns 501 Not Implemented.

(ISO 17978-3, §7.9)

---

Proposed solution

GET /api/v1/{entity-path}/data-groups

List all data groups defined for an entity.

Applies to entity types: Components, Apps (SOVDServer aggregation level excluded per spec)

Path parameters:

Parameter	Type	Required	Description
{entity-path}	URL segment	Yes	e.g., components/engine_ecu or apps/temp_sensor

Query parameters:

Parameter	Type	Required	Description
category	string	No	Filter groups by category (e.g., currentData). Only return groups that contain data items in this category.

Request body: None

Response 200 OK:

{
  "items": [
    {
      "id": "motion",
      "name": "Motion Data"
    },
    {
      "id": "environment",
      "name": "Environmental Sensors"
    }
  ]
}

Each item follows the standard SOVD reference format:

Field	Type	Required	Description
id	string	Yes	Group identifier
name	string	Yes	Human-readable group name
translation_id	string	No	Translation key for localization

Note: The response does not include a dataIds array. Per SOVD, the group listing only returns identifiers. To discover which data items belong to a group, clients use the groups query parameter on GET /{entity-path}/data:

GET /api/v1/apps/temp_sensor/data?groups=motion HTTP/1.1

This returns all ValueMetaData items that belong to the motion group. The groups filter takes precedence over categories when both are specified.

Error responses:

Status	Error Code	When
404	entity-not-found	Entity doesn't exist
501	not-implemented	Feature not implemented (current state)

---

Integration with GET /{entity-path}/data

The existing data listing endpoint needs to support group filtering:

GET /api/v1/apps/temp_sensor/data?groups=motion&groups=environment HTTP/1.1

• Multiple groups values → OR (return data items in any of the specified groups)
• groups combined with categories → groups takes precedence (per SOVD §7.9)
• Combined with tags → AND (e.g., ?groups=motion&tags=OBD)

Each ValueMetaData item in the response should include the groups field:

{
  "items": [
    {
      "id": "velocity",
      "name": "Linear Velocity",
      "category": "currentData",
      "groups": ["motion"]
    }
  ]
}

---

Additional context

Group definition sources

1. Manifest-defined (primary): Groups declared per entity in the YAML manifest:

   apps:
     temp_sensor:
       data_groups:
         - id: motion
           name: "Motion Data"
           data_ids: [position, velocity, acceleration]
         - id: environment
           name: "Environmental Sensors"
           data_ids: [temperature, humidity, pressure]

2. Namespace-derived (fallback): Auto-generate groups from topic namespace structure. E.g., topics under /robot/arm/ → group arm, topics under /robot/sensors/ → group sensors.

3. Capability description: Groups can also be defined via OpenAPI extension x-sovd-data-groups in the capability description.

Relationship to data-categories (#137)

Aspect	Categories	Groups
Source	SOVD standard types	User/manifest defined
Values	identData, currentData, storedData, sysInfo	Any custom identifier
Overlap	Each data item has exactly one category	A data item can belong to multiple groups
Filter	GET /data?categories=currentData	GET /data?groups=motion
Precedence	Lower (when both specified)	Higher (overrides categories filter)

Route registration

Route is already registered in rest_server.cpp — implement the handler:

// Already exists:
srv->Get((api_path("/apps") + R"(/([^/]+)/data-groups$)"), handler);
srv->Get((api_path("/components") + R"(/([^/]+)/data-groups$)"), handler);

Changes needed

1. Handler: Implement DataHandlers::handle_list_data_groups (or similar) to read group definitions from manifest/discovery
2. Data listing filter: Extend the existing GET /data handler to support ?groups= query parameter filtering
3. ValueMetaData: Add groups field to the data listing response items

Tests

• Unit test: list data groups returns manifest-defined groups
• Unit test: list groups with ?category=currentData filter
• Unit test: empty groups list for entity with no groups defined
• Unit test: filter GET /data?groups=motion returns only matching items
• Unit test: groups filter takes precedence over categories
• Unit test: 404 for nonexistent entity
• Integration test: verify groups with demo nodes