Support Matrix parameters

[cowwoc]

Please add support for matrix parameters: http://www.w3.org/DesignIssues/MatrixURIs.html

[rodneyrehm]

What kind of API would you expect this to have?

I wonder if @annevk came across any matrix params in the wild in his URL tests.

[annevk]

This seems like it's just an idea from timbl, not something that actually happened.

[rodneyrehm]

Yeah, I thought so. I came across this (or something similar?) a couple of years ago, but never saw anyone actually use it. Thanks @annevk!

[cowwoc]

@rodneyrehm I first heard of matrix parameters in OReilly's RESTful Web Services book and have used them in production during the past 4-5 years. They are well supported by JAX-RS and most REST frameworks I've come across.

I am expecting to be able to get/set matrix parameters the same way as I set query parameters, but in addition to adding/removing parameters against the last path segment (as query parameters currently do) I want additional methods to be able to add/remove matrix parameters against non-terminal path segments.

[rodneyrehm]

Ok, then let's toy with this for a bit. As MatrixURIs is a bit vague at times, I'll quickly re-iterate what I understood.

The character used to delimit keys and values is =, the character to delimit key-value-pairs is ;, both fall into the category of unreserved characters, more precisely into the subset sub-delims. The character group sub-delims is a possible component of every possible segment group (segment, segment-nz, segment-nz-nc) as per Collected URI ABNF, the notation fits general URI rules.

For the most part, the matrix notation fits encoding/decoding of x-www-form-urlencoded - with the exceptions:

• spaces being encoded as %20 instead of +
• ; instead of & being the key-value-pair delimiter
• keys are unique (for compatibility, last declaration wins)
• ;key, unlike &key does not convey a null value (;key= and &key= behave the same, though) - ;key has to be removed from the segment during normalization
• order of keys does not matter, so by convention we'll sort them alphabetically

---

Supporting the MatrixURI notation has implications on the following existing methods

• .normalizePath() to add normalizePathMatrix() to sort and unique-ify matrix params and remove trailing ;
• .relativeTo() and .absoluteTo() because URI(;foo=bar).absoluteTo('//foo.com/one;key=val') should yield '//foo.com/one;key=val;foo=bar'

Supporting the MatrixURI notation calls for additional methods

• .matrix() analogous to .segmentCoded() for access to individual components and the entire path

URI('//foo.com/one;key=val/two;some=m%C3%B6re;data=;bla/thr%3Fe').matrix(true);
// would return the following construct:
[
  {
    segment: 'one',
    matrix: {
      key: 'val',
    },
  },
  {
    segment: 'two',
    matrix: {
      data: '',
      // note: decoded value
      some: 'möre',
    },
  },
  {
    // note: decoded value
    segment: 'thr?e',
    matrix: {},
  },
];

[cowwoc]

@rodneyrehm

Great analysis. This brings up some questions:

1. Since keys are unique, I guess it's up to the user to decide how to pack multiple values per key-value pair?
2. You said that;key= does not convey a null value. What does it convey then? :)

Also, you might want to post a new answer to http://stackoverflow.com/q/401981/14731 with some of these points.

[rodneyrehm]

I might get back to the SO question later, for now let's first figure out what exactly is going on and is expected to happen.

Interesting fact: MatrixURIs do seem to be used in various places:

• Ruby On Rails uses them to denote page state like som/resource;edit
• Piwik "supports" them
• AngularJS seems to support them
• RFC 3986 Section 3.3 explains the concept without calling it MatrixURI in the last paragraph

Some more resources to (re)visit later:

• The Matrix Revisited
• URL Path Parameter Syntax
• Building URIs

---

Since keys are unique, I guess it's up to the user to decide how to pack multiple values per key-value pair?

After looking around for a bit, it seems that the comma (,, also in sub-delims) was intended for just that. Something similar has not been defined for x-www-form-urlencoded because it does not mandate keys being unique, so multiple values could be provided simply by repeating the key over and over again.

You said that;key= does not convey a null value. What does it convey then? :)

It conveys the empty string, which is to be interpreted as "key exists without value".

---

adding the comma to my example above, we end up with:

URI('//foo.com/one;key=val/two;some=m%C3%B6re;data=;list=1,2,3;bla/thr%3Fe').matrix(true);
// would return the following construct:
[
  {
    segment: 'one',
    matrix: {
      key: 'val',
    },
  },
  {
    segment: 'two',
    matrix: {
      data: '',
      // note: "," delimits multiple values within a key-value component
      list: ['1', '2', '3'],
      // note: decoded value
      some: 'möre',
      // note: key 'bla' is removed because it was null
    },
  },
  {
    // note: decoded value
    segment: 'thr?e',
    matrix: {},
  },
];

[cowwoc]

You said that;key= does not convey a null value. What does it convey then? :)

It conveys the empty string, which is to be interpreted as "key exists without value".

If that's the case, then I question your earlier statement:

;key has to be removed from the segment during normalization

It seems to me that this contradicts:

there must be a syntax for removing an attribute, hopefully distinguishing a removed attribute from one whose value if the empty string

found at http://www.w3.org/DesignIssues/MatrixURIs.html. Where did you read that keys with empty values should be removed during normalization?

[rodneyrehm]

see the resolving relative urls at the end of that document

[cowwoc]

@rodneyrehm Okay, I see. I see now that a relative path of ";roads" causes a key to be removed whereas ";roads=" does not. I thought the two forms were equivalent, but they are not.

[dario-liberman-jav]

What is the status on this feature guys?
Quite eager to use Matrix Parameters in my URIs and your library would be a perfect fit if it had the support :)

[rodneyrehm]

the status is: we have figured out what "Matrix Parameters" are supposed to be. There is no clear specification, only a thought-document.

as far as I know nobody has started implementing anything yet