Skip to main content

Object conversion

Object conversion changes an existing object from one kind to another, keeping the attribute values and relationships that both kinds share. Convert a Layer 2 interface to Layer 3, or a read-only repository to a read-write one, and the object keeps its relationships to everything else.

How object conversion works​

Field mapping and equivalence​

Object conversion operates on the principle of field equivalence between source and destination schema types. The system automatically identifies compatible fields using specific criteria:

Attribute field equivalence:

  • Fields must have identical names
  • Fields must have compatible value types
  • Data validation rules are preserved during conversion

Relationship field equivalence:

  • Fields must have identical names
  • Fields must reference the same peer schema type
  • Cardinality constraints (one-to-one, one-to-many) must match

Automatic mapping process​

When initiating a conversion, Infrahub performs these steps:

  1. Schema analysis: Compares source and destination schema definitions to identify equivalent fields
  2. Compatibility check: Validates that the conversion is technically feasible
  3. Mandatory field identification: Highlights destination fields that require explicit values
  4. Data transformation: Executes the conversion while preserving data integrity

Handling non-equivalent fields​

Not all fields between schema types will have direct equivalents. The conversion process handles these scenarios:

Missing source fields:

  • Destination fields without source equivalents must be manually specified
  • Mandatory destination fields require explicit values or use of defaults
  • Optional fields can leverage schema-defined default values

Surplus source fields:

  • Source fields without destination equivalents are gracefully ignored
  • Data from these fields is not transferred but doesn't impede conversion
  • Historical data remains accessible through version control

Design considerations and constraints​

Version control integration​

Object conversion integrates deeply with Infrahub's Git-like branching model, but this creates important constraints:

Branch-aware attributes:

Converting a branch-agnostic object whose branch-aware attributes carry over to the new kind must run on the default branch, and Infrahub refuses it on any other branch. Infrahub then sets every other open branch to the NEED_REBASE status.

On a branch in NEED_REBASE, only rebasing the branch, deleting it, creating a branch and opening a Proposed Change work (the BranchRebase, BranchDelete, BranchCreate and ProposedChangeCreate mutations). Any other change fails with the BRANCH_NEEDS_REBASE error until you rebase the branch.

When you convert the object, Infrahub deletes it on every branch and creates the replacement on the default branch, using the default branch's values. Any value another branch had set on a branch-aware attribute of the original object is lost, and rebasing that branch does not restore it.

Commit preservation: The conversion process maintains object history and commit lineage, ensuring auditability and rollback capabilities.

Data integrity safeguards​

Several mechanisms protect data integrity during conversion:

Validation enforcement:

  • All destination schema constraints are validated before conversion
  • Referential integrity for relationships is maintained
  • Data type compatibility is strictly enforced

Atomic operations:

  • Conversions execute as atomic transactions
  • Failures result in complete rollback with no partial state
  • Concurrent modifications are handled through Infrahub's conflict resolution

Common use cases​

Infrastructure evolution​

Network interface type changes: Converting between Layer 2 and Layer 3 interfaces as network designs evolve, preserving device associations and configuration parameters while adapting to new operational requirements.

Repository access model changes: Transforming read-only repositories to read-write repositories when teams gain modification privileges, maintaining Git integration while expanding access controls.

Object conversion intersects with several other Infrahub concepts:

  • Schema management: Understanding how schema types define conversion possibilities
  • Version control: How conversions interact with branch and merge operations
  • Metadata: How object metadata is preserved during conversion
  • GraphQL: The API mechanisms that enable conversion operations