Addressable for Ruby URI, IRI, and URI template handling

Addressable's Ruby URI replacement scope

Addressable addresses a specific gap between Ruby's standard `URI` library and applications that regularly handle modern web identifiers. It is intended for Ruby developers working with URI syntax, internationalized resource identifiers, or templates. The project describes itself as an alternative implementation of the URI implementation included with Ruby's standard library. That distinction matters because replacing the library is not only a matter of changing a class name. Parsing acceptance, normalization behavior, access to components, and template operations all become part of the application's contract.

The project closely follows RFC 3986 for URIs, RFC 3987 for IRIs, and RFC 6570 level 4 for URI templates. These specifications cover different parts of the problem. URI parsing exposes components such as scheme, host, and path. IRI support permits internationalized text in the relevant identifier positions. URI templates provide a separate syntax for representing URI families whose query values, path segments, host, or fragment vary.

Addressable is most relevant when the application must do more than split an address into strings. It can normalize an IRI containing an internationalized domain name, expand a query template from a hash, partially expand selected variables, or extract values from a concrete URI. A service that constructs callback URLs or accepts user-defined template expressions is a plausible fit. By contrast, code that only opens HTTP connections still needs a client library, and the README does not present Addressable as an HTTP client.

Addressable::URI parsing, components, and normalization

The basic flow begins with `Addressable::URI.parse`. It receives the address as a string and returns an `Addressable::URI` object whose components can be read through methods such as `scheme`, `host`, and `path`. This object-oriented representation is useful when several components must be inspected independently. The README example parses `http://example.com/path/to/resource/`, then retrieves `http`, `example.com`, and `/path/to/resource/` from the resulting object.

Normalization is a separate operation. Calling `uri.normalize` does not alter the input string at the time of parsing; it asks the parsed object for its normalized representation. The internationalized example is more revealing:

require "addressable/uri"

uri = Addressable::URI.parse("http://www.詹姆斯.com/")
uri.normalize
#=> #<Addressable::URI:0xc9a4c8 URI:http://www.xn--8ws00zhy3a.com/>

The returned URI uses the Punycode representation `xn--8ws00zhy3a.com` for the internationalized host. The README does not enumerate every normalization rule or guarantee that every accepted spelling has one canonical output, so applications should not invent a broader normalization policy from this example. What is documented is a clear distinction between parsing human-readable IRI input and requesting a normalized URI representation.

For workflows that should reject malformed input rather than attempt interpretation, the README's emphasis on heuristic parsing deserves attention. The project explicitly presents flexibility as a feature, but permissive parsing can be undesirable in security boundaries or protocol gateways where acceptance rules must be strict. The README does not describe a strict-parsing mode, an error taxonomy, or normalization guarantees for every RFC edge case.

Addressable::Template expansion and value extraction

URI template support is implemented separately through `Addressable::Template`. A template object is constructed from a string containing RFC 6570 expressions. Expansion maps variable names to values. In the README example, the expression `{?query*}` receives a hash, and the result contains the generated query string:

require "addressable/template"

template = Addressable::Template.new("http://example.com/{?query*}")
template.expand({
  "query" => {
    'foo' => 'bar',
    'color' => 'red'
  }
})
#=> #<Addressable::URI:0xc9d95c URI:http://example.com/?foo=bar&color=red>

This is more than ordinary string interpolation because the template syntax defines how values are encoded and assigned to URI positions. The returned value in this example is an `Addressable::URI` object.

Addressable also supports partial expansion. The following call supplies values for `one` and `three`, then inspects the remaining pattern so the caller can continue the work:

template = Addressable::Template.new("http://example.com/{?one,two,three}")
template.partial_expand({"one" => "1", "three" => 3}).pattern
#=> "http://example.com/?one=1{&two}&three=3"

The inverse operation, `extract`, maps components and query values from a concrete URI back into template variable values. This makes Addressable relevant to routing systems, callback configuration, and tools that need to interpret generated addresses. The README does not describe a resolver for choosing among several templates when more than one can match, so applications should not assume such matching logic exists.

Installing Addressable and performing a first parse

The README identifies RubyGems as the installation path. On a Ruby environment where the gem command is available, install the package with the documented command:

gem install addressable

A first use can begin with component access. This example is copied from the README and returns the parsed scheme, host, and path:

require "addressable/uri"

uri = Addressable::URI.parse("http://example.com/path/to/resource/")
uri.scheme
#=> "http"
uri.host
#=> "example.com"
uri.path
#=> "/path/to/resource/"

Internationalized domain-name support does not necessarily depend on the optional native packages for every operation. The README specifically says native IDN support can be enabled by installing `libidn` and the associated gem. Its Debian or Ubuntu command is:

sudo apt-get install libidn11-dev

The corresponding Homebrew command shown for OS X is:

brew install libidn

The README then gives this RubyGems installation command for the IDN binding:

gem install idn-ruby

The text calls this optional, so deployment environments should first verify whether their actual IDN path works without native support. The README does not document feature detection, fallback behavior, or a verification command for the binding.

Standards coverage, heuristic trade-offs, and operational limits

The strongest reason to choose Addressable over a small wrapper around the standard library is its explicit standards scope. RFC 3986, RFC 3987, and RFC 6570 level 4 are named in the README, while template expansion, partial expansion, extraction, and IRI normalization are exposed as concrete operations. These are project-specific reasons to evaluate the gem.

The same flexibility creates a trade-off. Heuristic parsing is useful when inputs vary or contain human-readable international identifiers, but a parser that accepts and interprets difficult input can be a poor fit for a strict allowlist. The documentation does not state which deviations are accepted, how recovery works, or how errors are categorized. Developers adopting it for request validation, redirects, or security-sensitive URL handling would need to identify a separate validation policy, although the README does not prescribe one.

There is also no GitHub release listed in the repository information. Version selection therefore needs to come from RubyGems and the project's SemVer documentation rather than an assumed GitHub release stream. The last push was on 2026-06-27, so the repository is not archived and has recent recorded development activity, but repository activity does not establish compatibility for a particular application.

Dependency constraints, licensing, and the standard library alternative

Addressable uses Semantic Versioning. The README recommends a pessimistic constraint covering the major and minor values, and gives `~> 2.7` as its primary example. Applications that need a specific bug-fix floor without excluding later minor releases are shown another form:

spec.add_dependency 'addressable', '~> 2.7'

The README also demonstrates a narrower lower bound:

spec.add_dependency 'addressable', '~> 2.3', '>= 2.3.7'

These examples illustrate two different dependency policies: accepting compatible releases across a range, or requiring at least a selected tiny version for a fix. There are no GitHub releases to use as an upgrade checklist. Upgrade planning would therefore need to account for application tests and any changes in the URI or template behavior the application relies on.

The project is licensed under Apache 2.0, with `LICENSE.txt` present in the repository. That identifies the license, but it does not by itself answer organization-specific compliance questions.

The main alternative is Ruby's built-in `URI` implementation. Keeping the standard library avoids adding an external gem when the application only needs ordinary URI components and does not require IRI normalization or RFC 6570 operations. Addressable is the different choice when template processing or its documented internationalized URI behavior is part of the requirement. It is not automatically the safer or stricter option, because its documented heuristic parsing can be the opposite of what a strict gateway needs.

Editorial conclusion

Addressable is suitable for Ruby applications that need RFC 3986 and RFC 3987 behavior, internationalized identifiers, or RFC 6570 template expansion and extraction. It is a poorer choice for code that specifically depends on Ruby URI's parsing rules or expects permissive heuristic parsing to be rejected. Before adoption, verify whether your URI inputs are valid according to the standards Addressable claims to follow, whether optional IDN dependencies are acceptable, and whether the documented pessimistic dependency constraint fits the application's release process.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. sporkmonger/addressable on GitHub