title: RESTful Collection Resources - idiomatic JSON representations and roundtripping
body: <p>I have a collection resource called Columns. A <code>GET</code> with <code>Accept: application/json</code> <a href="http://haacked.com/archive/2009/06/24/json-hijacking.aspx" rel="nofollow">can't directly return a collection</a>, so my representation needs to nest it in a property:-</p>
  
  <pre><code>{ "propertyName": [
     { "Id": "Column1", "Description": "Description 1" },
     { "Id": "Column2", "Description": "Description 2" }
    ]
  }
  </code></pre>
  
  <p>Questions:</p>
  
  <ol>
  <li><p>what is the <em>best</em> name to use for the identifier <strong>propertyName</strong> above? should it be:</p>
  
  <ul>
  <li><strong>d</strong> (i.e. is <strong>d</strong> an established convention or is it specific to some particular frameworks (<a href="http://www.west-wind.com/weblog/posts/2007/Oct/04/WCF-and-JSON-Services" rel="nofollow">MS WCF</a> and <a href="http://encosia.com/a-breaking-change-between-versions-of-aspnet-ajax/" rel="nofollow">MS ASP.NET AJAX</a> ?) </li>
  <li><strong>results</strong> (i.e. is <strong>results</strong> an established convention or is it specific to some particular specifications (<a href="http://msdn.microsoft.com/en-us/library/dd942341%28v=prot.10%29.aspx" rel="nofollow">MS OData</a>)?) </li>
  <li><strong>Columns</strong> (i.e. the top level property should have a clear name and it helps to disambiguate my usage of generic <code>application/json</code> as the Media Type)</li>
  </ul>
  
  <p><em>NB I feel pretty comfortable that there should be something wrapping it, and as pointed out by @tuespetre, XML or any other representation would force you to wrap it to some degree anyway</em></p></li>
  <li><p>when PUTting the content back, should the same wrapping in said property be retained [given that it's not actually necessary for security reasons and perhaps conventional JSON usage idioms might be to drop such nesting for PUT and POST given that they're not necessary to guard against scripting attacks] ?</p>
  
  <p><em>my gut tells me it should be symmetric as for every other representation but there may be prior art for dropping the <strong>d</strong>/</em>*results** [assuming that's the answer to part 1]*</p>
  
  <p>... Or should a PUT-back (or POST) drop the need for a wrapping property and just go with:- </p>
  
  <pre>
   [
         { "Id": "Column1", "Description": "Description 1" },
         { "Id": "Column2", "Description": "Description 2" }
   ]
  </pre>
  
  <ul>
  <li>Where would any root-level metadata go if one wished to add that?</li>
  <li>How/would a person crafting a POST Just Know that it needs to be symmetric?</li>
  </ul></li>
  </ol>
  
  <hr>
  
  <p>EDIT: I'm specifically interested in an answer that with a reasoned rationale that specifically takes into account the impacts on client usage with JSON. For example, <a href="http://stateless.co/hal_specification.html" rel="nofollow">HAL</a> takes care to define a binding that makes sense for both target representations.</p>
  
  <p>EDIT 2: <strong>Not accepted yet, why?</strong> The answers so far don't have citations or anything that makes them stand out over me doing a search and picking something out of the top 20 hits that seem reasonable. Am I just too picky? I guess I am (or more likely I just can't ask questions properly :D). Its a bit mad that a week and 3 days even with an )admittedly measly) bonus on still only gets 123 views (from which 3 answers ain't bad)</p>