{"id":13459235,"url":"https://github.com/ulid/spec","last_synced_at":"2026-01-28T15:05:04.763Z","repository":{"id":37677742,"uuid":"113100288","full_name":"ulid/spec","owner":"ulid","description":"The canonical spec for ulid","archived":false,"fork":false,"pushed_at":"2024-07-20T13:02:18.000Z","size":53,"stargazers_count":10055,"open_issues_count":67,"forks_count":177,"subscribers_count":93,"default_branch":"master","last_synced_at":"2025-03-25T08:42:56.379Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ulid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-04T22:04:08.000Z","updated_at":"2025-03-25T05:51:46.000Z","dependencies_parsed_at":"2024-07-31T09:20:45.911Z","dependency_job_id":null,"html_url":"https://github.com/ulid/spec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ulid/spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ulid","download_url":"https://codeload.github.com/ulid/spec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28846103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T13:02:32.985Z","status":"ssl_error","status_checked_at":"2026-01-28T13:02:04.945Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T09:01:11.785Z","updated_at":"2026-01-28T15:05:04.743Z","avatar_url":"https://github.com/ulid.png","language":null,"readme":"\u003ch1 align=\"center\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003cimg width=\"360\" src=\"logo.png\" alt=\"ulid\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\u003c/h1\u003e\n\n# Universally Unique Lexicographically Sortable Identifier\n\nUUID can be suboptimal for many use-cases because:\n\n- It isn't the most character efficient way of encoding 128 bits of randomness\n- UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address\n- UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures\n- UUID v4 provides no other information than randomness which can cause fragmentation in many data structures\n\nInstead, herein is proposed ULID:\n\n```javascript\nulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV\n```\n\n- 128-bit compatibility with UUID\n- 1.21e+24 unique ULIDs per millisecond\n- Lexicographically sortable!\n- Canonically encoded as a 26 character string, as opposed to the 36 character UUID\n- Uses Crockford's base32 for better efficiency and readability (5 bits per character)\n- Case insensitive\n- No special characters (URL safe)\n- Monotonic sort order (correctly detects and handles the same millisecond)\n\n## Implementations in other languages\n\nFrom ourselves and the community!\n\n| Language | Author | Binary Implementation |\n| -------- | ------ | --------------------- |\n| [C++](https://github.com/suyash/ulid) | [suyash](https://github.com/suyash) | ✓ |\n| [C#](https://github.com/mcb2001/CSharp.Ulid) | [mcb2001](https://github.com/mcb2001) |\n| [Clojure](https://github.com/theikkila/clj-ulid) | [theikkila](https://github.com/theikkila) |\n| [Objective-C](https://github.com/whitesmith/ulid) | [ricardopereira](https://github.com/ricardopereira) |\n| [Crystal](https://github.com/SuperPaintman/ulid) | [SuperPaintman](https://github.com/SuperPaintman) |\n| [Dart](https://github.com/agilord/ulid) | [isoos](https://github.com/isoos) | ✓ |\n| [Dart](https://github.com/GuepardoApps/d-ulid) | [GuepardoApps](https://github.com/GuepardoApps) |\n| [Delphi](https://github.com/martinusso/ulid) | [matinusso](https://github.com/martinusso) |\n| [D](https://github.com/enckse/ulid) | [enckse](https://github.com/enckse) |\n| [D (dub)](https://code.dlang.org/packages/ulid-d) | [extrawurst](https://github.com/Extrawurst)\n| [Erlang](https://github.com/savonarola/ulid) | [savonarola](https://github.com/savonarola) |\n| [Elixir](https://github.com/Homepolish/ulid) | [Homepolish](https://github.com/Homepolish) | ✓ |\n| [Elixir](https://github.com/merongivian/ulid) | [merongivian](https://github.com/merongivian) |\n| [Elixir](https://github.com/omisego/ex_ulid) | [omisego](https://github.com/omisego) | ✓ |\n| [Elixir (Ecto)](https://github.com/TheRealReal/ecto-ulid) | [dcuddeback](https://github.com/dcuddeback) | ✓ |\n| [F#](https://github.com/lucasschejtman/FSharp.Ulid) | [lucasschejtman](https://github.com/lucasschejtman) |\n| [Factor](https://github.com/AlexIljin/ulid) | [Alexander Ilin](https://github.com/AlexIljin) | ✓ |\n| [Go](https://github.com/oklog/ulid) | [oklog](https://github.com/oklog) | ✓ |\n| [Haskell](https://github.com/steven777400/ulid) | [steven777400](https://github.com/steven777400) | ✓ |\n| [Java](https://github.com/huxi/sulky/tree/master/sulky-ulid) | [huxi](https://github.com/huxi) | ✓ |\n| [Java](https://github.com/azam/ulidj) | [azam](https://github.com/azam) |\n| [Java](https://github.com/Lewiscowles1986/jULID) | [Lewiscowles1986](https://github.com/Lewiscowles1986) |\n| [JavaScript](https://github.com/ulid/javascript) | [ulid](https://github.com/ulid) |\n| [JavaScript](https://github.com/aarondcohen/id128) | [aarondcohen](https://github.com/aarondcohen) | ✓ |\n| [Julia](https://github.com/ararslan/ULID.jl) | [ararslan](https://github.com/ararslan) |\n| [Kotlin](https://github.com/GuepardoApps/kULID) | [GuepardoApps](https://github.com/GuepardoApps) |\n| [Lua](https://github.com/Tieske/ulid.lua) | [Tieske](https://github.com/Tieske) |\n| [.NET](https://github.com/RobThree/NUlid) | [RobThree](https://github.com/RobThree) | ✓ |\n| [.NET](https://github.com/fvilers/ulid.net) | [fvilers](https://github.com/fvilers)\n| [Nim](https://github.com/adelq/ulid) | [adelq](https://github.com/adelq)\n| [OCaml](https://github.com/stripedpajamas/ocaml-ulid) | [stripedpajamas](https://github.com/stripedpajamas) |   |\n| [Perl 5](https://github.com/bk/Data-ULID) | [bk](https://github.com/bk) | ✓ |\n| [PHP](https://github.com/Lewiscowles1986/ulid) | [Lewiscowles1986](https://github.com/Lewiscowles1986) |\n| [PHP](https://github.com/robinvdvleuten/php-ulid) | [robinvdvleuten](https://github.com/robinvdvleuten) |\n| [PowerShell](https://github.com/PetterBomban/posh-ulid) | [PetterBomban](https://github.com/PetterBomban) |\n| [Python](https://github.com/mdipierro/ulid) | [mdipierro](https://github.com/mdipierro) |\n| [Python](https://github.com/ahawker/ulid) | [ahawker](https://github.com/ahawker) | ✓ |\n| [Python](https://github.com/mdomke/python-ulid) | [mdomke](https://github.com/mdomke) | ✓ |\n| [R](https://github.com/hrbrmstr/ulid) | [hrbrmstr](https://github.com/hrbrmstr) |   |\n| [Ruby](https://github.com/rafaelsales/ulid) | [rafaelsales](https://github.com/rafaelsales) |\n| [Rust](https://github.com/mmacedoeu/rulid.rs) | [mmacedoeu](https://github.com/mmacedoeu) | ✓ |\n| [Rust](https://github.com/dylanhart/ulid-rs) | [dylanhart](https://github.com/dylanhart) | ✓ |\n| [Scala](https://github.com/petitviolet/ulid4s) | [petitviolet](https://github.com/petitviolet) |\n| [SQL-Microsoft](https://github.com/rmalayter/ulid-mssql) | [rmalayter](https://github.com/rmalayter) | ✓ |\n| [Swift](https://github.com/simonwhitehouse/ULIDSwift) | [simonwhitehouse](https://github.com/simonwhitehouse) |\n| [Swift](https://github.com/yaslab/ULID.swift) | [yaslab](https://github.com/yaslab) | ✓ |\n| [Tcl](https://wiki.tcl-lang.org/48827) | [dbohdan](https://github.com/dbohdan) |\n\n## Specification\n\nBelow is the current specification of ULID as implemented in [ulid/javascript](https://github.com/ulid/javascript).\n\n*Note: the binary format has not been implemented in JavaScript as of yet.*\n\n```\n 01AN4Z07BY      79KA1307SR9X4MV3\n\n|----------|    |----------------|\n Timestamp          Randomness\n   48bits             80bits\n```\n\n### Components\n\n**Timestamp**\n- 48 bit integer\n- UNIX-time in milliseconds\n- Won't run out of space 'til the year 10889 AD.\n\n**Randomness**\n- 80 bits\n- Cryptographically secure source of randomness, if possible\n\n### Sorting\n\nThe left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed\n\n### Canonical String Representation\n\n```\nttttttttttrrrrrrrrrrrrrrrr\n\nwhere\nt is Timestamp (10 characters)\nr is Randomness (16 characters)\n```\n\n#### Encoding\n\nCrockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.\n\n```\n0123456789ABCDEFGHJKMNPQRSTVWXYZ\n```\n\n### Monotonicity\n\nWhen generating a ULID within the same millisecond, we can provide some\nguarantees regarding sort order. Namely, if the same millisecond is detected, the `random` component is incremented by 1 bit in the least significant bit position (with carrying). For example:\n\n```javascript\nimport { monotonicFactory } from 'ulid'\n\nconst ulid = monotonicFactory()\n\n// Assume that these calls occur within the same millisecond\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0\n```\n\nIf, in the extremely unlikely event that, you manage to generate more than 2\u003csup\u003e80\u003c/sup\u003e ULIDs within the same millisecond, or cause the random component to overflow with less, the generation will fail.\n\n```javascript\nimport { monotonicFactory } from 'ulid'\n\nconst ulid = monotonicFactory()\n\n// Assume that these calls occur within the same millisecond\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVRY\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0\nulid() // 01BX5ZZKBKACTAV9WEVGEMMVS1\n...\nulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZX\nulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZY\nulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZZ\nulid() // throw new Error()!\n```\n\n#### Overflow Errors when Parsing Base32 Strings\n\nTechnically, a 26-character Base32 encoded string can contain 130 bits of information, whereas a ULID must only contain 128 bits. Therefore, the largest valid ULID encoded in Base32 is `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, which corresponds to an epoch time of `281474976710655` or `2 ^ 48 - 1`.\n\nAny attempt to decode or encode a ULID larger than this should be rejected by all implementations, to prevent overflow bugs.\n\n### Binary Layout and Byte Order\n\nThe components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).\n\n```\n0                   1                   2                   3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                      32_bit_uint_time_high                    |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|     16_bit_uint_time_low      |       16_bit_uint_random      |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                       32_bit_uint_random                      |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                       32_bit_uint_random                      |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n## Prior Art\n\nPartly inspired by:\n- http://instagram-engineering.tumblr.com/post/10853187575/sharding-ids-at-instagram\n- https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html\n","funding_links":[],"categories":["miscellaneous","Others","UUID Like","Tools","\u003ca name=\"Not%20Set\"\u003e\u003c/a\u003eNot Set"],"sub_categories":["Packages","WebTools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulid%2Fspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulid%2Fspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulid%2Fspec/lists"}