RFC3986 Matrix Variables


In RFC3986 section 3.3 the “URI path parameters” were defined. However this kind of URIs are known by the name Tim Berners-Lee gave to them the 19th of December of 1996 in a post: Matrix URIs.

This is an example of URI with Matrix Variables:


They are not Query parameters and serve to a different purpose ( stackoverflow.com/questions/401981/when-to-use-query-parameters-versus-matrix-parameters ):

  • urls with query params won’t have their response cached by
    intermediaries/proxies (at present)
  • matrix parameters may appear
    anywhere in path
  • calculating the relative uri is different
  • query
    params are generally abused to add new verbs instead of using
    existing methods on resources
  • matrix parameters are not resources,
    they are aspects that help reference a resource in an information
    space that is difficult to represent within a hierarchy

Just a handful of frameworks support Matrix Variables. I’m wondering if RAML does support or will support them.


I would say that yes, eventually RAML as a specification will support these along with typing and documentation of each of the variables. This is only to ensure that RAML is as encompassing as possible in the tools that it offers to design or document existing APIs.

On a personal note, I wonder if it is worth it to support them outside of GET. You see, the most typical use I can think of for matrix variables is resource filtering.

Given the following example:

GET /books;author=stephen_king
POST /books;author=stephen_king

I think the POST one will make some REST purists scream.

I wonder what other uses people see for matrix variables…


They are probably a blurry concept but still part of the standard.

Off the top of my head for POST and Matrix vars I can think of a scenario where we may want to mark all the stephen_king books as featured in our book store using the API.

This could be accomplished by sending a payload Content-type: application/vnd+mybookstore.feature+json as POST /books;author=stephen_king


I’m working on an image server handling vector and raster logos. I could imagine using matrix vars like this:


There is the logical logo, which is just the name “company-xyz”, and then there are variants based on preferences, fx. narrow/wide, optimized for light/dark background, a specific resolution, etc. You can GET the resource, either a specific variant or the default if leaving out matrix vars. You could PUT to the resource to update a specific variant or you could leave out matrix vars to set all (or a subset of) variants.

In fact I’m using query parameters in my API right now. I just stumbled upon this thread and thought I would chime in.


I came searching for matrix param support, but it seems it’s not yet supported. How can I vote in favor of adding support? I have an existing API defining matrix params that I would like to express in RAML.


I’d like to see support for matrix parameters too. Any progress on this?


I’d suggest to create an issue on raml-org/raml-spec outlining the proposal and people can vote. Please don’t add +1 as a comment though :wink: it’s enough to add the emoji thumbs up for that.