Human Friendly IDs (HFID) & Display Labels
Relevant source files
The following files were used as context for generating this wiki page:
Human Friendly IDs (HFID) and Display Labels provide human-readable identification and visual representation for nodes within the Infrahub graph. HFIDs serve as stable, readable identifiers for referencing nodes in configuration files, YAML imports, and API requests, replacing the need for UUIDs in standard workflows. Sources: backend/AGENTS.md:129, dev/constitution.md:20
Display Labels define how the system presents a node within the User Interface (UI). These labels summarize node identity based on specific attribute values or relationships defined in the schema. Sources: specs/2026-05-schema-doc-migration.md
Human Friendly Identifiers (HFID)
HFIDs are a specific kind of node attribute used for unique identification. The schema layer governs the definition of these identifiers to ensure data integrity. Sources: dev/constitution.md:18
HFID Characteristics and Constraints
- Uniqueness: HFIDs must be unique within their node type and branch context. Sources: specs/2026-05-schema-doc-migration.md
- Derivation: The backend derives HFIDs during update and create mutations based on attribute values. Sources: backend/AGENTS.md:104
- API Reference: The system uses HFIDs as a primary mechanism for referencing objects in the Python SDK and GraphQL API. Sources: backend/AGENTS.md:129, dev/constitution.md:88
HFID Generation Flow
The following diagram illustrates how HFIDs are managed during node mutations:
This diagram shows the validation and derivation process occurring during a write operation. Sources: backend/AGENTS.md:104, dev/constitution.md:20
Display Labels
Display Labels control the visual presentation of nodes in the Infrahub web interface. They allow developers to define which attributes or relationships best describe a node to a human user. Sources: specs/2026-05-schema-doc-migration.md
Presentation Logic
The UI uses Display Labels to represent complex graph objects in lists, breadcrumbs, and search results. The derivation of these labels is defined at the schema level, ensuring that every node presents information consistently across different branches and time states. Sources: dev/constitution.md:25, specs/2026-05-schema-doc-migration.md
Comparison of HFID and Display Labels
| Feature | Human Friendly ID (HFID) | Display Label |
|---|---|---|
| Primary Purpose | Unique identification and referencing | Visual representation and UI display |
| Required Uniqueness | Strictly enforced by database constraints | Not required to be unique |
| Consumer | API, SDK, YAML imports, Developers | Human users via the Web UI |
| Governance | Defined as a specific attribute kind | Defined as a display parameter |
Sources: dev/constitution.md:18-28, specs/2026-05-schema-doc-migration.md
Schema Implementation
Schema definitions act as the single source of truth for both HFIDs and Display Labels. Every node, relationship, and constraint must be defined in the schema layer before it exists in the database. Sources: dev/constitution.md:18
The diagram represents the relationship between the node schema and the attributes that constitute identifiers and labels. Sources: specs/2026-05-schema-doc-migration.md
Configuration Elements
| Element | Description |
|---|---|
hfid | The attribute designated as the unique human-friendly identifier. |
display_label | The configuration or pattern determining the string shown in the UI. |
uniqueness_constraints | Enforced constraints that often include the HFID attribute. |
Sources: specs/2026-05-schema-doc-migration.md, dev/constitution.md:18
Conclusion
Human Friendly IDs and Display Labels are critical components for maintaining a branch-safe and user-accessible infrastructure graph. By moving identification from opaque UUIDs to structured HFIDs, Infrahub enables seamless Git-like workflows where infrastructure data can be safely merged and referenced across different environments. Sources: dev/constitution.md:33, backend/AGENTS.md:129