[RFD]: Hardware Inventory API and Data Model Proposal

[bmcdonald3]

Decision Goal

To agree on the core data models and API endpoints for a new Hardware Inventory contract, and to identify key areas that require further discussion before implementation.

Category

Architecture

Stakeholders / Affected Areas

Sys admins, magellan, SMD

Decision Needed By

No response

Problem Statement

OpenCHAMI currently lacks means for tracking Field Replaceable Units (FRUs) and other hardware. The existing process is focused on functional gathering (e.g., information required for power control) and relies on manual workflows and CLI tools that are not easily auditable or consumable by other services. This proposal aims to solve that problem by defining a core inventory contract and a corresponding set of APIs to establish a baseline, programmatic source of truth for all hardware in the system.

Core Data Models

The Device Model

The Device model represents any physical hardware component that is uniquely trackable within the system, covering everything from top-level systems like servers and switches down to individual FRUs such as GPUs, NICs, or DIMMs. The primary qualification for an item to be a Device is that it can be uniquely identified, typically through a combination of its manufacturer, part number, and serial number discovered via an out-of-band management interface like Redfish. The rationale here is that all items that can be individually replaced are tracked as their own distinct entities.

When storing cables, information about connections (such as when a node is connected to a switch) may be stored in the properties field. Best practice is to store this information as a connection with endpointA that lists a port and deviceID and endpointB that lists a port and deviceID to model the connection.

Core fields

• id (UUID): The permanent, unique identifier for the hardware.
• deviceType (Enum): The type of hardware (e.g., "Node", "GPU", "Rack").
• manufacturer (String): The manufacturer name.
• partNumber (String): The part number.
• serialNumber (String): The serial number.
• parentID (UUID): The parent device of this device. If null, this is a top-level device (i.e., a rack; dimms are children of nodes, etc.).
• childrenDeviceIds (Array of UUIDs): A read-only list of devices contained within this one. Calculated on-request, not stored (to avoid frequent updates).

Arbitrary key-value store

• properties (Map of strings to JSON values): An arbitrary key-value map for storing additional, non-standard attributes.

Properties information

The properties Field for Custom Attributes

To resolve the open question regarding custom attributes, a properties field will be in the Device model. This field allows storing arbitrary key-value data that is not covered by the core model fields.

The properties field is a map where keys are strings and values can be any valid JSON type (string, number, boolean, null, array, or object). To ensure consistency and usability, the following constraints and guidelines apply.

Constraints on Keys

• all keys must be in lowercase snake_case.
• keys may only contain lowercase alphanumeric characters (a-z, 0-9), underscores (_), and dots (.).
• the dot character (.) is used exclusively as a namespace separator to group related attributes (e.g., bios.release_date).

Key Transformation Examples

HPCM Key	OpenCHAMI Key
biosBootMode	bios_boot_mode
operationalStatus	operational_status
rootFs	root_fs
CONSERVER_LOGGING	conserver_logging
dns_domain	dns_domain
Wake-up Type	wake_up_type
SKU Number	sku_number
bios.Release Date	bios.release_date

Other constraints

• all values stored in the properties field must be valid JSON
• whenever possible, use simple JSON types (String, Number, Boolean)
• only use JSON Objects or Arrays when data is inherently structured as a group or list

Example of a JSON Object value:

"aliases": {
  "a2000": "ProLiant_XL225n_Gen10_Plus_n1",
  "brazos": "brazos1",
  "product": "XL225n_Gen10_Plus_n1"
}

Example of a JSON array value:

"protocol": ["Hpe", "NO_DCMI", "NO_DCMI_NM", "None", "ipmi", "redfish"]

Metadata

• apiVersion (String): The API group version (e.g., "inventory/v1").
• kind (String): The resource type (e.g., "Device").
• schemaVersion (String): The version of this resource's schema.
• createdAt (Timestamp): Timestamp of when the device was created.
• updatedAt (Timestamp): Timestamp of the last update.
• deletedAt (Timestamp): Timestamp for soft deletes.

Device JSON

{
  "apiVersion": "inventory/v1",
  "kind": "Device",
  "schemaVersion": "v1",
  "id": "d5e6f7a8-b9c0-d1e2-f3g4-h5i6j7k8l9m0",
  "deviceType": "Node",
  "manufacturer": "Vendor Inc.",
  "partNumber": "VN-123-456",
  "serialNumber": "SN987654321",
  "parentID": "f7g8h9i0-j1k2-l3m4-n5o6-p7q8r9s0t1u2",
  "childrenDeviceIds": [
    "gpu-uuid-01",
    "dimm-uuid-01",
    "dimm-uuid-02"
  ],
  "properties": [
    "device_type_slug": "ProLiant-BL460c-Gen10",
    "protocol": ["Hpe", "NO_DCMI", "NO_DCMI_NM", "None", "ipmi", "redfish"]
  ]
  "createdAt": "2025-09-20T10:00:00Z",
  "updatedAt": "2025-09-29T14:30:00Z",
  "deletedAt": null
}

{
  "apiVersion": "inventory/v1",
  "kind": "Device",
  "schemaVersion": "v1",
  "id": "d5e6f7a8-b9c0-d1e2-f3g4-h5i6j7k8l9m0",
  "deviceType": "Node",
  "manufacturer": "Vendor Inc.",
  "partNumber": "VN-123-456",
  "serialNumber": "SN987654321",
  "parentID": "chassis-uuid-b01",
  "childrenDeviceIds": [
    "gpu-uuid-01",
    "dimm-uuid-01",
    "dimm-uuid-02"
  ],
  "properties": {
    "device_type_slug": "ProLiant-BL460c-Gen10",
    "protocol": ["Hpe", "NO_DCMI", "NO_DCMI_NM", "None", "ipmi", "redfish"],
    "connections": [
      {
        "endpointA": "switch-uuid-tor1",
        "port": "eth0"
      },
      {
        "endpointB": "node1-uuid",
        "port": "gbe-1/0/5"
      }
    ]
  },
  "createdAt": "2025-09-20T10:00:00Z",
  "updatedAt": "2025-09-29T14:30:00Z",
  "deletedAt": null
}

API Specification

The hardware inventory contract is exposed through three logical API groups. Clients can request a specific schema version of a resource using the Accept header.

Inventory API (/apis/inventory/v1)

Provides a RESTful interface for managing the current state of the inventory via CRUD operations.

• Device Management
  • GET /devices: List and filter all devices.
  • POST /devices: Create a new device.
  • GET /devices/{deviceId}: Get a single device.
  • PATCH /devices/{deviceId}: Partially update a device.
  • DELETE /devices/{deviceId}: Delete a device.

Other APIs

To fully support FRU tracking snapshots and history, there will be two supporting APIs (inventory history and inventory collection), but the contents of those are outside the scope of this current RFD.

The collection API will have a scan operation to gather inventory and display what has changed since the last approved system state and the history API will store individual machine states as snapshots to provide a record of machine hardware changes.

Proposed API Groups

The proposed solution is a unified hardware inventory contract exposed via three logical API groups that work together to provide a complete inventory solution.

• Inventory API: The system of record. Its sole responsibility is to provide a RESTful interface for managing the current state of hardware inventory.
• History API: Manages the long-term storage of historical inventory snapshots, provides data retention capabilities, and handles comparison (diff) operations.
• Collection API: Actively discovers hardware information, compares it to the last known state to generate a diff report, and submits approved changes to the Inventory API.

Alternatives Considered

• Extend Magellan: Implement inventory gathering using the existing magellan CLI tool for manual management rather than building a new set of APIs. Rejected, as the goal is to provide stable APIs that other services can consume programmatically.

Other Considerations

Ongoing Design Questions

• COMPLETE (see blelow) Endpoint-to-Location Mapping: What is the most effective and flexible mechanism for administrators to provide the mapping between discoverable hardware endpoints (e.g., BMC IPs) and their physical locations?
• COMPLETE (see below) Custom Attributes: Should the API support storing arbitrary key-value data for devices and locations?

Changes based on discussion

• Moved deviceTypeSlug out of top-level design. This is gathered/created fundamentally differently than hardware-specific things, such as manufacturer, part number, etc., so we decided that it should belong in the properties field, if desired.
• Added a properties field for storing arbitrary string->JSON values.
• Added a description of what the point is for having locations separate from devices.
• Added a description of what all counts as a device.
• Renamed componentType to deviceType.
• Added geolocation to location to represent the actual physical location, which cannot be discovered by out-of-band discovery.
• Workflow updated to reflect new, optional-geolocation model.
• Pulled out less-relevant parts into summary sections
• Broke down fields based on metadata vs core fields to make it more readable
• Restructured document to make more readable
• Removed location and connection resources
• Added parentID to device
• Removed locationID from device
• Added section about modeling connections with cables properties field

Related Docs / PRs

• https://github.com/Cray-HPE/cani
• https://cloudevents.io/

Details

System workflow overview and Events

System Workflow Overview

The new workflow is discovery-first, automatically generating the inventory structure based on what is physically present. Specific geolocation details are treated as optional data that can be added by an administrator after the hardware has been discovered.

1. Discovery is Initiated: A scan is collected by the Collection API using a list of discoverable hardware management endpoints (e.g., a range of BMC IP addresses).
2. Hardware and Hierarchy are Discovered: The collection logic connects to each endpoint and discovers all hardware components and their parent-child relationships (e.g., a server containing GPUs and DIMMs).
3. A Diff Report is Generated: The discovered hardware state is compared against the last known state in the Inventory API. For new hardware, the system proposes the creation of corresponding Device and Location resources, automatically building the location hierarchy based on the discovered parent-child relationships.
4. Changes are Approved: An administrator reviews the structured diff report and approves the changes through the Collection API.
5. System State is Updated: Upon approval, the Inventory API creates or updates the Device resources and their associated Location resources. A top-level component's location will have a null parentLocationId, establishing it as the root. Events are then emitted to trigger the creation of a new historical snapshot.
6. Physical Geolocation is Optionally Added: After the hardware exists in the system, an administrator can enrich the data by updating the Location resources with specific physical details (e.g., rack, U-position) via the new geolocation field. This is a manual enrichment step, not a prerequisite for discovery.

Event Sourcing with CloudEvents

Inventory operations will generate events, the long term vision is currently to use CloudEvents, but the broader decision of OpenCHAMI event sourcing is not a part of this RFD and will be proposed after consensus is reached on the broader question of events in OpenCHAMI.

Initial draft of other APIs to provide context, though these are subject to change and will be presented as separate RFDs.

History API (/apis/history/v1)

Provides endpoints for accessing and managing historical inventory snapshots.

• GET /snapshots: List all available snapshots.
• GET /snapshots/{snapshotId}: Get a specific historical snapshot of the inventory.
• GET /snapshots/diff: Compare two snapshots. (e.g., ?from={snapshotId1}&to={snapshotId2})
• GET /events?subject={deviceId}: Get the complete change history of events for one specific device.
• Data Retention
  • GET /policy: Get the current data retention policy.
  • PUT /policy: Set the data retention policy.
  • POST /snapshots/{snapshotId}/pin: Pin a snapshot to prevent automatic deletion.
  • DELETE /snapshots/{snapshotId}/pin: Unpin a snapshot.

Collection API (/apis/collection/v1)

Provides endpoints for initiating and managing the asynchronous hardware discovery workflow.

• POST /scans: Trigger a new discovery scan. Returns an Operation resource.
• POST /scans/{scanId}/approve: Approve the changes from a completed scan. Returns an Operation resource.
• GET /scans/{scanId}/diff: Get the diff report for a completed scan. The scanId is found in the result of a successful scan Operation.
• GET /operations/{operationId}: Get the status of a long-running operation.

The Operation Model

The Operation resource is used to track the status of any long-running asynchronous task, such as a hardware scan or the process of applying approved changes.

• name (String): The unique, server-assigned name of the operation, which also serves as its ID (e.g., operations/scan-a4b1c2d3e4f5).
• done (Boolean): A flag indicating if the operation is complete. false while in progress, true when finished.
• metadata (Object): A flexible object containing progress information specific to the operation.
• result (Object): A field that contains the final outcome of the operation once done is true. It will contain either a response or an error.

{
  "name": "operations/scan-a4b1c2d3e4f5",
  "done": false,
  "metadata": {
    "@type": "type.googleapis.com/openchami.collection.v1.ScanMetadata",
    "startTime": "2025-10-01T16:30:00Z",
    "progressPercent": 45,
    "lastUpdateTime": "2025-10-01T16:35:10Z"
  }
}

[alexlovelltroy]

1. Schemas and URL Structure

Take a look at the ADR we're working on that deals with API versioning. It will have an impact on the structure of the resources and the urls. Add comments there as you see fit.

OpenCHAMI/community#27

2. Microservices

I'm not convinced that multiple microservices are necessary here. Help me understand why we can't extend SMD for at least most of this. Why is the historical information in a secondary API?

3. Scan

I don't like the idea of using a REST endpoint for an imperative indirect action. Have you considered the operation resource pattern? I like the description from Google on long-running operations to describe it. https://google.aip.dev/151

4. Cloudevents

I think using a standard like this is a great idea, but I don't see how the events here fit into what you're describing. Which services generate them? Which services consume them? How are they transported or discovered?

[bmcdonald3]

1. Noted, I've reviewed it, and I've updated the proposal to align with the two-layer versioning standard, I made these changes:

• updated all API endpoints to use the /apis prefix
• added the apiVersion and schemaVersion fields to the Device, Location, and Connection models
• clarified in the API specification that clients can request specific schema versions using the Accept header

2. That is a good point, I think it was a mistake on my part to include the 3 separate microservices part. I've updated the proposal to just list the APIs and whether or not they are their own services or not, I think that is a separate question, here I would like to try to focus on the API and data models. (FWIW, I think that it would be reasonable to extend SMD for this, my prototypes have been using SMD as the backend anyway).

3. I've updated to include the Operation resource for the long-standing operation, makes sense to me.

4. Edit: Wait a minute, let me think about these events more...

[jvd10]

3. Scan

I don't like the idea of using a REST endpoint for an imperative indirect action. Have you considered the operation resource pattern? I like the description from Google on long-running operations to describe it. https://google.aip.dev/151

Shouldn't the plan for long running operations take place under the existing RFD for Asynchronous Operations?

#83

[bmcdonald3]

Looking at the data model in the context of Fabrica, I have converted the data fields into how these would look as Fabrica resources.

All fields covered by Metadata are moved to the Metadata category, whereas everything is placed into Spec, where the idae behind this inventory is that it will reflect the actual state of the hardware as seen by Redfish/other tools, so it is not something that should be changed via user input.

Device Model

Data Field	Fabrica Mapping	Category
id	Metadata.UID	Metadata
name	Metadata.Name	Metadata
createdAt	Metadata.CreatedAt	Metadata
updatedAt	Metadata.UpdatedAt	Metadata
componentType	Spec.ComponentType	Spec
manufacturer	Spec.Manufacturer	Spec
partNumber	Spec.PartNumber	Spec
serialNumber	Spec.SerialNumber	Spec
locationId	Spec.LocationID	Spec
numericId	Spec.NumericID	Spec
childrenDeviceIds	Spec.ChildrenDeviceIDs	Spec

---

Location Model

Data Field	Fabrica Mapping	Category
id	Metadata.UID	Metadata
name	Metadata.Name	Metadata
parentLocationId	Spec.ParentLocationID	Spec
locationType	Spec.LocationType	Spec
numericId	Spec.NumericID	Spec
childrenLocationIds	Spec.ChildrenLocationIDs	Spec

---

Connection Model

Data Field	Fabrica Mapping	Category
id	Metadata.UID	Metadata
connectionType	Spec.ConnectionType	Spec
mediumId	Spec.MediumID	Spec
endpointA	Spec.EndpointA	Spec
endpointB	Spec.EndpointB	Spec
numericId	Spec.NumericID	Spec

The branch that I have been working with this on has been pushed up here: https://github.com/bmcdonald3/fabrica/tree/inventory-proposal (note, you'll have to replace my local replace command to get this to run elsewhere). I have added some fake data I've been using to populate and test my script.

To run the server, I was using this command:

./fru-server serve --database-url "file:fru.db?_fk=1"

Which requires the database-url change from the PR I submitted to Fabrica (not yet merged, but it's in my branch that I pushed up).

To populate this with the information that I've provided, you just run the fru server, then you run ./populate.sh from the top-level Fabrica directory. This will convert some data in HPCM format to this new inventory format.

Details

$ curl -s http://localhost:8080/api/locations | jq
$ curl -s http://localhost:8080/api/devices | jq  

[
  {
    "apiVersion": "v1",
    "kind": "Location",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-location",
      "uid": "loc-9cdc5897",
      "createdAt": "2025-10-14T10:08:49.714532-07:00",
      "updatedAt": "2025-10-14T10:08:50.545641-07:00"
    },
    "spec": {},
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Location",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-proc-1-socket",
      "uid": "loc-2c298b92",
      "createdAt": "2025-10-14T10:08:49.855443-07:00",
      "updatedAt": "2025-10-14T10:08:49.855443-07:00"
    },
    "spec": {
      "parentLocationId": "loc-9cdc5897",
      "locationType": "Socket"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Location",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-proc-2-socket",
      "uid": "loc-583e43a3",
      "createdAt": "2025-10-14T10:08:50.001331-07:00",
      "updatedAt": "2025-10-14T10:08:50.001331-07:00"
    },
    "spec": {
      "parentLocationId": "loc-9cdc5897",
      "locationType": "Socket"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Location",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-null-slot",
      "uid": "loc-a1feae22",
      "createdAt": "2025-10-14T10:08:50.173823-07:00",
      "updatedAt": "2025-10-14T10:08:50.173823-07:00"
    },
    "spec": {
      "parentLocationId": "loc-9cdc5897",
      "locationType": "Slot"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Location",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-null-slot",
      "uid": "loc-02e462cf",
      "createdAt": "2025-10-14T10:08:50.329838-07:00",
      "updatedAt": "2025-10-14T10:08:50.329838-07:00"
    },
    "spec": {
      "parentLocationId": "loc-9cdc5897",
      "locationType": "Slot"
    },
    "status": {}
  }
]

[
  {
    "apiVersion": "v1",
    "kind": "Device",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01",
      "uid": "dev-a672f939",
      "createdAt": "2025-10-14T10:08:49.771939-07:00",
      "updatedAt": "2025-10-14T10:08:50.479951-07:00"
    },
    "spec": {
      "componentType": ""
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Device",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-cpu-SN-CPU-001",
      "uid": "dev-6782c31a",
      "createdAt": "2025-10-14T10:08:49.916758-07:00",
      "updatedAt": "2025-10-14T10:08:49.916758-07:00"
    },
    "spec": {
      "componentType": "CPU",
      "manufacturer": "CPU Vendor A",
      "serialNumber": "SN-CPU-001",
      "locationId": "loc-2c298b92"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Device",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-cpu-SN-CPU-002",
      "uid": "dev-dcc55086",
      "createdAt": "2025-10-14T10:08:50.059616-07:00",
      "updatedAt": "2025-10-14T10:08:50.059616-07:00"
    },
    "spec": {
      "componentType": "CPU",
      "manufacturer": "CPU Vendor A",
      "serialNumber": "SN-CPU-002",
      "locationId": "loc-583e43a3"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Device",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-dimm-0000000A",
      "uid": "dev-63ebec13",
      "createdAt": "2025-10-14T10:08:50.232364-07:00",
      "updatedAt": "2025-10-14T10:08:50.232364-07:00"
    },
    "spec": {
      "componentType": "DIMM",
      "manufacturer": "Memory Vendor B",
      "partNumber": "null",
      "serialNumber": "0000000A",
      "locationId": "loc-a1feae22"
    },
    "status": {}
  },
  {
    "apiVersion": "v1",
    "kind": "Device",
    "schemaVersion": "",
    "metadata": {
      "name": "compute-node-01-dimm-0000000B",
      "uid": "dev-550c53f6",
      "createdAt": "2025-10-14T10:08:50.385437-07:00",
      "updatedAt": "2025-10-14T10:08:50.385437-07:00"
    },
    "spec": {
      "componentType": "DIMM",
      "manufacturer": "Memory Vendor B",
      "partNumber": "null",
      "serialNumber": "0000000B",
      "locationId": "loc-02e462cf"
    },
    "status": {}
  }
]

[jacobsalmela]

I think having the deviceTypeSlug as a top-level field is still worthwhile here and should be added back in. It allows for future expansion using the netbox device-type library: https://github.com/netbox-community/devicetype-library and can still be generally useful while having little negative impact.

[alexlovelltroy]

1. I thought this API was planned to handle Field Replaceable Units. Is that interchangeable with Devices here? Is a stick of RAM or PCI Card tracked as a Device?
2. DeviceSpec -> ComponentType is confusing. Would DeviceType work instead?
3. I think an inline Location is better than having a dedicated Location Resource. There's no lifecycle to manage of a Location and we can use Validation to prevent conflicts. Is there another reason to keep it separate?
4. Since Status is intended to be observed conditions, I don't understand putting the ChildrenDeviceIDs in the Status. What about information about power and temperature that can be left empty if not relevant? What other observed characteristics might make sense? "In Service" vs "Out for Repair"?
5. Help me understand more about the connections and how you see them being used. If it is to track expensive cables can we consider adding Cable as a ComponentType and including custom properties about where it is installed to the Spec.Properties field?

Below is my suggestion for a simpler data model.

// DeviceSpec defines the desired state of Device
type DeviceSpec struct {
	DeviceType string `json:"DeviceType" validate:"required"` // Enumerate the valid DeviceTypes in the Validate method
	Manufacturer  string `json:"manufacturer,omitempty"`
	PartNumber    string `json:"partNumber,omitempty"`
	SerialNumber  string `json:"serialNumber,omitempty"`
	Model        string `json:"model"`

	// Location information as inline struct for simplicity
	Location DeviceLocation `json:"location"`

	// Relationships
	ParentUID    string   `json:"parentUID,omitempty"`    // Parent FRU
	ChildrenUIDs []string `json:"childrenUIDs,omitempty"` // Child FRUs

	// Redfish path for management
	RedfishPath string `json:"redfishPath,omitempty"`

	// Custom properties
	Properties map[string]string `json:"properties,omitempty"`

}

type DeviceLocation struct {
	BMCUID   string `json:"bmcUID,omitempty"`  // BMC managing this FRU
	NodeUID  string `json:"nodeUID,omitempty"` // Node containing this FRU
	Rack     string `json:"rack,omitempty"`
	Chassis  string `json:"chassis,omitempty"`
	Slot     string `json:"slot,omitempty"`
	Bay      string `json:"bay,omitempty"`
	Position string `json:"position,omitempty"`
	Socket   string `json:"socket,omitempty"`
	Channel  string `json:"channel,omitempty"`
	Port     string `json:"port,omitempty"`
        // Other details needed?
}

// DeviceStatus defines the observed state of Device
type DeviceStatus struct {
        Temperature  float64            `json:"temperature,omitempty"`
	Power             float64            `json:"power,omitempty"`
        Conditions      []resource.Conditions `json:"conditions,omitempty"` // See https://github.com/alexlovelltroy/fabrica/blob/main/pkg/resource/conditions.go
	// Add other status fields here
}

[alexlovelltroy]

I think having the deviceTypeSlug as a top-level field is still worthwhile here and should be added back in. It allows for future expansion using the netbox device-type library: https://github.com/netbox-community/devicetype-library and can still be generally useful while having little negative impact.

Rather than storing the slug as a field, I would recommend adding a custom function Device.Slug() that generates the slug based on the information stored in the Device resource.

[jacobsalmela]

Rather than storing the slug as a field, I would recommend adding a custom function Device.Slug() that generates the slug based on the information stored in the Device resource.

I agree that a getter method is a great way to get that info, but the device-type library has a lot of information we can infer about the device simply by that string. I would still keep that getter method, but having the deviceTypeSlug as a field will allow the possibility to add a device by slug alone, and then known properties can be pre-populated.

This field could be omitempty and not required for the first iteration.

Here is an example of what I see as a future possibility:

$ # minimal info needed to add a device: vendor, part number, componentType, etc can be populated automatically
$ curl -X POST http://localhost:8080/devices -d '
{
  "deviceTypeSlug": "hpe-dl325"
}
'
# some fields omitted for brevity:
{
  "id": "d5e6f7a8-b9c0-d1e2-f3g4-h5i6j7k8l9m0",
  "name": "generated-name,
  "componentType": "Blade",
  "deviceTypeSlug": "hpe-dl325",
  "manufacturer": "HPE",
  "partNumber": "VN-123-456",,
}

The devicetype-library has a strong footing in the community and this inventory API can be extended to support more devices without input from us--as community members contribute to that repo, we can add new devices anytime.

This also allows for both humans and robots to interact easily with the API. If someone wants to pre-populate an inventory with things they know they bought or to design a system from scratch, they can add items via slug, and then the discovery process like magellan can come back and update it with more information.

Similiarly, if a robot/cralwer can find device names, a fuzzy/ai/regex/LLM search could craft the slug and populate the inventory with a minimum of data.

[alexlovelltroy]

My concern about allowing users to indicate slugs as part of creating the device resource is that it puts the burden on the user to remain consistent. A slug ends up with inferred meaning in different contexts.

I do see the value in the interoperability. What about a subcommand of the server that exports the entire dataset for use elsewhere? At its most basic level, it could just be a yaml/json export, but with some minor additional code, we could export specifically to formats used by other systems, masking sensitive fields and/or adding computed fields like slug.

they can add items via slug, and then the discovery process like magellan can come back and update it with more information

I don't think this is a good idea. It reinforces the idea that slug is a common convention that two unrelated pieces of software need to understand in the same way. The Device resource already has a unique uid field that will be returned on creation of a resource, even if there is very little information included. Another unique field that crawlers like Magellan need to understand and map in order to update doesn't seem like it adds any value to me.

[jacobsalmela]

What about a subcommand of the server that exports the entire dataset for use elsewhere? At its most basic level, it could just be a yaml/json export, but with some minor additional code, we could export specifically to formats used by other systems, masking sensitive fields and/or adding computed fields like slug

I think this is a good thing to have regardless of the deviceTypeSlug.

My concern about allowing users to indicate slugs as part of creating the device resource is that it puts the burden on the user to remain consistent. A slug ends up with inferred meaning in different contexts.

The API can easily query the known device types and reject invalid slugs. It can also point to a "generic" devicetype if they need to add it anyway. I do not think this needs to be a required field right now; it just gives users another path to use if they want.

The reason I bring it up is because I have an inventory API in development, which already handles that exact scenario.

I don't think this is a good idea. It reinforces the idea that slug is a common convention that two unrelated pieces of software need to understand in the same way. The Device resource already has a unique uid field that will be returned on creation of a resource, even if there is very little information included. Another unique field that crawlers like Magellan need to understand and map in order to update doesn't seem like it adds any value to me.

The UUID is and should be the unique identifier. The deviceTypeSlug is just like an alias or name field. I do not see any tooling having too much trouble with some string keys.

A lot of what I see likely to happen with inventory is a lot of Extract, Transform, Load (ETL) (maybe this has a more advanced term now with LLMs and the like): many tools exist to gather info about hardware/FRUs and will do just that--some tool (magellan, dmidecode, shell scripts, humans) gathers a bunch of info from a device. That info will always need some sort of transformation into whatever data structures are designed here for this API.

The other reason the devicetypes offer value is with the connections (this sort of ties in with your bulleted questions before this thread got going). The devicetype definitions know about what interfaces are available on devices and what could connect to what.

[bmcdonald3]

I thought this API was planned to handle Field Replaceable Units. Is that interchangeable with Devices here? Is a stick of RAM or PCI Card tracked as a Device?

Yes, I think that is interchangeable with devices here. The way that I've been thinking about this is essentially anything that shows up in Redfish as their own endpoint with a serial number, part number, etc., would be stored as a device.

Does the main confusion come from the name of Device itself or something else about the model? I think that I'd be open to other names, I don't feel wedded to Device.

DeviceSpec -> ComponentType is confusing. Would DeviceType work instead?

Works for me, though, I think this hinges on what we decide for the question above.

I think an inline Location is better than having a dedicated Location Resource. There's no lifecycle to manage of a Location and we can use Validation to prevent conflicts. Is there another reason to keep it separate?

The reason that we were proposing to keep this separate is thinking about the physical layout of a machine (location) vs the actual components that are in that machine (device).

How I imagine this working would be that each device discovered in the initial scan has a corresponding location created with it. These locations don't change, regardless of what device is holding that location at any given time. For example, you could take out a stick of RAM from a node, that location still exists, even though that device is not longer occupying the location.

NetBox does something very similar with their Device Bays. A Device Bay is a distinct object in the database that represents a physical slot or bay where another device can be installed. You can create all the Device Bays for a server before you install any child devices (like blade servers or power supplies) into them. This allows a complete physical representation of the server regardless of what is/isn't currently installed. (they also have other things like module bays and locations of their own, but the simpler location proposal here I think suits our needs).

Since Status is intended to be observed conditions, I don't understand putting the ChildrenDeviceIDs in the Status. What about information about power and temperature that can be left empty if not relevant? What other observed characteristics might make sense? "In Service" vs "Out for Repair"?

I guess it seems that I had this backwards... I was thinking that Status represented things that users can change, whereas Spec represented things that the user cannot modify. Looking back at the Fabrica docs, I am seeing that I've got everything in reverse here, I think that everything would go in Status, not Spec, right? I wouldn't think that we would expect the user to have to declare, say, where they would want their devices to be, the purpose of the inventory service itself is to show what actually is. Given this, I think that I'd switch around all my friends. Does this sound right?

Regarding the additional fields, we are currently working on how we want to represent those other fields that aren't top-level based on what we've seen from HPCM and CSM. To give you a preview of what we are thinking, the idea is we'll have a properties field that is a key-value map that has keys with naming guidelines mapped to values that must be valid JSON objects. This will be following (hopefully) very shortly; this is what was being referred to as an ongoing discussion in the original comment with "Should the API support storing arbitrary key-value data for devices and locations?"