https://github.com/sixarm/sixarm_ruby_zid

SixArm.com » Ruby » ZID: Zen Identifier
https://github.com/sixarm/sixarm_ruby_zid

ruby zid

Last synced: about 1 year ago
JSON representation

SixArm.com » Ruby » ZID: Zen Identifier

• Host: GitHub
• URL: https://github.com/sixarm/sixarm_ruby_zid
• Owner: SixArm
• License: other
• Created: 2015-02-11T19:18:04.000Z (over 11 years ago)
• Default Branch: main
• Last Pushed: 2025-04-14T09:21:39.000Z (about 1 year ago)
• Last Synced: 2025-04-22T12:50:47.185Z (about 1 year ago)
• Topics: ruby, zid
• Language: Ruby
• Homepage:
• Size: 434 KB
• Stars: 4
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md
  • Code of conduct: CODE_OF_CONDUCT.md
  • Citation: CITATION.cff
  • Codeowners: CODEOWNERS

Awesome Lists containing this project

README

          
# SixArm.com → Ruby → 
 ZID: Xeno Identifier for foreign keys

[![Gem Version](https://badge.fury.io/rb/sixarm_ruby_zid.svg)](http://badge.fury.io/rb/sixarm_ruby_zid)

[![Build Status](https://travis-ci.org/SixArm/sixarm_ruby_zid.png)](https://travis-ci.org/SixArm/sixarm_ruby_zid)

[![Code Climate](https://api.codeclimate.com/v1/badges/e0e205a7564fafacc365/maintainability)](https://codeclimate.com/github/SixArm/sixarm_ruby_zid/maintainability)

* Git: 

* Doc: 

* Gem: 

* Contact: Joel Parker Henderson, 

* Project: [changes](CHANGES.md), [license](LICENSE.md), [contributing](CONTRIBUTING.md).

## Introduction

ZID stands for "Zen Identifier".

A ZID is a secure random id, similar to a random UUID (Universally Unique Identifier).

ZID specification:

  * Generated entirely by using a secure random generator.

  * You can use as many bits as you like, for example ZID128 is 128 bits.

  * The string representation is always hexadecimal lowecase: digits 0-9 and lowercase a-f.

See below for a comparison of ZID and UUID.

For docs go to 

Want to help? We're happy to get pull requests.

## Install

### Gem

To install this gem in your shell or terminal:

    gem install sixarm_ruby_zid

### Gemfile

To add this gem to your Gemfile:

    gem 'sixarm_ruby_zid'

### Require

To require the gem in your code:

    require 'sixarm_ruby_zid'

## Details

Class methods:

  * `ZID.generate`: generate a new ZID string.

  * `ZID.valid?(string)`: is a string a valid ZID?

  * `ZID.parse(object)`: parse any object to a new ZID string.

Notes:

  * ZID uses Ruby's SecureRandom methods for strong security.

  * ZID generates a Ruby string, so you can do any string methods on it.

## UUID comparison

ZID is much like UUID:

  * ZID and UUID are both 128 bit.

  * ZID has one form. UUID has multiple forms known as variants and versions.

  * ZID mandates secure randomness. UUID has no mandate of secure randomness.

  * ZID is entirely random. UUID has a non-random variant value.

  * ZID is entirely lowercase. UUID representation and reading allows uppercase or lowercase.

  * ZID is entirely hex digits. UUID allows dashes to separate sequences.

  * ZID is always 32 characters. UUID allows 32-36 characters.

To format an ZID in the style of a UUID canonical representation:

    zid = "90f44e35a062479289ff75ab2abc0ed3"

    zid.sub(/(.{8})(.{4})(.{4})(.{16})/,"#$1-#$2-#$3-#$4")

    #=> "90f44e35-a062-4792-89ff75ab2abc0ed3"

Note: the result string is formatted like a UUID, but is not guaranteed to be valid UUID. This is because the ZID is random, whereas the UUID specification requires a specific bit that indicates the UUID is random.

To format a UUID in the style of an ZID:

    uuid = "14fFE137-2DB2-4A37-A2A4-A04DB1C756CA"

    uuid.gsub(/-/,"").downcase

    #=> ""14f7e1372db24a37a2a4a04db1c756ca"

Note: the result string is formatted like a ZID, but is not a valid ZID. This is because there's no guarantee that the UUID was randomly generated using a secure random generator, and also because the UUID-4 specification requires a random UUID to set the third section's first digit to 4.

## Unix tooling

To generate an ZID on a typical Unix system, one way is the hexdump command:

    $ hexdump -n 16 -v -e '16/1 "%02x" "\n"' /dev/random

    b29dd48b7040f788fd926ebf1f4eddd0

To digest an ZID by using SHA256:

    $ echo -n "b29dd48b7040f788fd926ebf1f4eddd0" | shasum -a 256

    afdfb0400e479285040e541ee87d9227d5731a7232ecfa5a07074ee0ad171c64

## Database tooling

To store an ZID in a database, one way is using a string field that is 32 characters long.

Some databases have specialize fields for 128 bit values, such as PostgreSQL and its UUID extensions. PostgreSQL states that a UUID field will accept a string that is lowercase and that omits dashes. PostgreSQL does not do any validity-checking on the UUID value. Thus it is viable to store an ZID in a UUID field. Our team has a goal to create a PostgreSQL extension for the ZID data type.

## Credits

* [Joel Parker Henderson](https://github.com/joelparkerhenderson)

* [Michael Pope](https://github.com/amorphid)