Skip to main content

Object Identifier

Draft specification

Maturity: Draft — not yet validated by a reference implementation. Subject to change during Runtime development.

See Protocol Specifications for reading order and the full specification index.

Abstract​

This specification defines UUID version 7 (RFC 9562) as the mandatory object identifier format for the Faberio platform.

Every identifiable object — regardless of type, storage backend, or application domain — MUST use a UUIDv7 identifier. This ensures consistent, interoperable, and time-ordered identification across all runtimes, SDKs, and protocol implementations.

1. Scope​

This specification applies to all objects managed by the Faberio platform, including but not limited to:

  • database records
  • file storage objects
  • replicated state entities
  • messages and events
  • RPC request and response references
  • node records
  • user records
  • information space records
  • information space membership records
  • application-defined entities

Every object stored in a database — including nodes and users — MUST have a UUIDv7 identifier assigned at creation time.

1.1 Object Identifier vs Identity Model​

Faberio distinguishes between two concepts:

ConceptPurposeIdentifier
Object identifierPrimary key of a record in the databaseUUIDv7
Identity modelAuthentication, trust, and access control at the protocol levelDefined by the Faberio Identity Model

A node exists as a database object with a UUIDv7 identifier. At the protocol level, the same node is also identified by a cryptographic key pair for authentication and secure communication.

A user exists as a database object with a UUIDv7 identifier within an information space. At the protocol level, the same user is identified by a cryptographic key pair registered in the information space public key registry.

UUIDv7 identifies the record. The identity model defines how that record authenticates and authorizes operations. These are complementary — not alternative — identification mechanisms.

2. Motivation​

Distributed systems require identifiers that work across independently operated nodes without a central allocation authority.

UUIDv7 provides:

  • Global uniqueness without coordination between nodes
  • Time-ordering — identifiers are naturally sortable by creation time
  • Interoperability — a single standard format across all languages and runtimes
  • Compact representation — 128 bits in binary, 36 characters in canonical string form

Requiring UUIDv7 in all cases eliminates ambiguity between identifier formats and simplifies replication, indexing, and cross-runtime communication.

3. Requirements​

3.1 Mandatory Usage​

Implementations MUST assign a UUIDv7 identifier to every new object at creation time.

Implementations MUST NOT use alternative identifier formats for objects, including:

  • auto-increment integers
  • UUID version 1, 3, 4, 5, or 6
  • ULID, Snowflake, or other custom schemes
  • composite or namespaced string identifiers

3.2 Immutability​

An object identifier MUST NOT change after assignment.

If an object is copied or replicated to another node, the identifier MUST be preserved.

3.3 Uniqueness​

Each object MUST have a globally unique identifier within its scope.

Collision probability MUST be treated as negligible. Implementations SHOULD use a cryptographically secure random number generator for the random portion of the UUID.

4. Format​

4.1 Binary Representation​

A UUIDv7 is a 128-bit value with the following layout:

FieldBitsDescription
unix_ts_ms48Unix timestamp in milliseconds (big-endian)
ver4Version field, fixed value 0111 (7)
rand_a12Random data
var2Variant field, fixed value 10
rand_b62Random data

4.2 Canonical String Representation​

The canonical string representation MUST follow the format defined in RFC 9562:

xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx

Where:

  • x is a lowercase hexadecimal digit (0–9, a–f)
  • the third group begins with 7 (version)
  • the fourth group begins with 8, 9, a, or b (variant)

Example:

018f3e2a-7b4c-7890-a234-567890abcdef

Implementations MUST generate identifiers in lowercase. Implementations MUST accept uppercase input for parsing but SHOULD normalize to lowercase for storage and transmission.

4.3 Protocol Serialization​

When transmitted over the Faberio Protocol, object identifiers MUST be serialized as canonical string values in UTF-8 encoding.

Binary serialization MAY be used in storage backends for efficiency, but protocol-level interchange MUST use the canonical string form.

5. Generation​

5.1 Timestamp​

The unix_ts_ms field MUST contain the current Unix timestamp in milliseconds at the time of object creation.

If multiple identifiers are generated within the same millisecond, implementations MUST increment rand_a and/or rand_b to maintain uniqueness.

5.2 Randomness​

The rand_a and rand_b fields MUST be populated with cryptographically secure random data.

Implementations MUST NOT use predictable or sequential values for random fields.

5.3 Monotonic Generation​

When generating multiple identifiers in rapid succession, implementations SHOULD use monotonic generation as described in RFC 9562 Section 6.2 to preserve strict time-ordering within the same millisecond.

6. Validation​

Implementations MUST validate object identifiers before use.

A valid UUIDv7 identifier MUST satisfy all of the following:

  1. Conforms to the UUID string format (8-4-4-4-12 hexadecimal groups separated by hyphens)
  2. Version field equals 7
  3. Variant field equals RFC 4122 variant (10xx, resulting in 8–b as the first character of the fourth group)
  4. unix_ts_ms is a plausible timestamp (implementations MAY reject identifiers with timestamps far in the future)

Invalid identifiers MUST be rejected with an error. Implementations MUST NOT silently coerce or substitute invalid identifiers.

7. Usage in Platform Services​

7.1 Database​

Every database record MUST include a UUIDv7 primary identifier assigned at creation time.

Foreign key references MUST use UUIDv7 identifiers.

See Distributed Database for the replication model.

7.2 File Storage​

Every stored file object MUST be assigned a UUIDv7 identifier independent of its file path or name.

See Distributed File Storage for the replication model.

7.3 Replication​

Replicated objects MUST be matched by their UUIDv7 identifier across nodes.

CRDT merge MUST treat the identifier as the stable identity of the object.

7.4 Messaging and RPC​

Message and event payloads that reference objects MUST use UUIDv7 identifiers. See Messaging for the message format and RPC for the request-response format.

8. Sorting and Indexing​

UUIDv7 identifiers are naturally sortable by creation time when compared as byte sequences or canonical strings.

Database and storage implementations SHOULD use UUIDv7 identifiers as primary keys or clustering keys to benefit from time-locality in indexes.

Lexicographic string comparison of canonical UUIDv7 values produces the same ordering as binary comparison.

9. Examples​

9.1 Record Creation​

Object type: database record
Identifier:  0195a3f0-7c12-7891-b456-426614174000
Assigned at: object creation
Immutable:   yes

9.2 File Object​

Object type: file storage object
Identifier:  0195a3f0-7d34-7892-8abc-def012345678
Path:        /documents/report.pdf
Note:        identifier is independent of path

9.3 Replicated Entity​

Node A: identifier 0195a3f0-7e56-7893-9def-0123456789ab
Node B: identifier 0195a3f0-7e56-7893-9def-0123456789ab  (same object, replicated)

9.4 Node Record​

Object type:     node record
Object ID:       0195a3f0-7f78-7894-abcd-ef0123456789  (UUIDv7)
Display name:    Home Server
Protocol identity: cryptographic public key (Faberio identity model)

The UUIDv7 identifies the node as a database object. The cryptographic key pair is used for protocol-level authentication and secure communication.

9.5 User Record​

Object type:          user record
Object ID:            0195a3f0-809a-7895-bcde-f01234567890  (UUIDv7)
Information space:    0195a3f0-8000-7890-abcd-000000000001  (UUIDv7)
Display name:         Alice
Protocol identity:    Ed25519 public key (User ID derived from key)
Devices:              one or more authorized user devices (see Identity Model)

The UUIDv7 identifies the user as a database object within an information space. The cryptographic key pair is used for protocol-level authentication. Access rights are determined by approval status and access policies defined in the information space.

9.6 Information Space Record​

Object type:   information space record
Object ID:     0195a3f0-8000-7890-abcd-000000000001  (UUIDv7)
Display name:  Project Alpha

The UUIDv7 identifies the information space as a database object. The display_name provides a human-readable label for the trust boundary in which nodes discover peers and share data.

9.7 Information Space Membership Record​

Object type:           information space membership record
Object ID:             0195a3f0-8200-7892-cdef-000000000003  (UUIDv7)
Node:                  0195a3f0-7f78-7894-abcd-ef0123456789  (UUIDv7 of the node record)
Information space:     0195a3f0-8000-7890-abcd-000000000001  (UUIDv7 of the information space record)
Status:                pending | approved | rejected

A node participates in an information space through one or more membership records. Each membership requires administrator approval (status: approved) before the node participates in node-level background replication. See Node Discovery.

10. References​