On Tue, Dec 3, 2013 at 3:01 PM, Benjamin Young <byo...@bigbluehat.com>wrote:
> Hi all, > > Recently the "doc._*" reservation has been causing me trouble when pulling > in "arbitrary" JSON from various sources that also use the underscore > prefixed names for things (HAL [1], vnd.error [2], other APIs). I've also > hit the wall several times when trying to import filesystem contents > (Sphinx, ghpages, and the like) that use _* prefixing for their "special > folders." > > As such, I'd like to propose the following: > 1. Begin storing new reserved terms in doc._.* (rather than doc._*). > - this gives developers one object to look into for the meta-data about a > doc > - you can see the scope creep of our current doc._* best in the > replicator status messages. > - doc._ replication_* would become doc._.replication.* > 2. Move "magic" API endpoints under "/_/" term as well (for the sake of > attachments. > - _design/doc would stay the same > - but the child endpoints would live under "_design/doc/_/*" > - _design/doc/_/view/by_date > - _design/doc/_/list/by_date/ul > - _design/doc/_/rewrite > > I realize these are extreme API shifts, and would need to wait for CouchDB > 2.0. > > The first steps this direction would be to put new reserved word keys into > a "doc._.*" namespace going forward. Closer to the "cut over" for 2.0 > duplicates of the existing keys (doc._id, doc._rev, especially) could also > live at their new underscore prefixed names (doc._.id, doc._.rev) which > would give devs a chance to migrate code and content. > > Doing this would: > 1. Give us "limitless" space to add content. > 2. Encourage a namespacing pattern for things like doc._.replication.* or > other logically grouped content. > 3. Free up CouchDB to accept a far broader range of content and remove the > "hey, you can't put that there! I was here first!" errors. :) > > Thanks for considering this, > Benjamin > > [1] http://stateless.co/hal_specification.html > [2] https://github.com/blongden/vnd.error > I don't see why couchdb should adapt itself to newer things that didn't take care of an older API when doing their stuff but that's probably another concern ;) I would find a "/_/" in the URL rather ugly and not needed in that case. Same for having a _ in a doc. also it doesn't have much sense. Why do you want to change the HTTP api at that level? Another way to do it and probably more restish woudl be moving all couchdb resources in their own namespace. Say `couchdb/` for example. so anything in the resource couchdb will be related to couchdb. Next is the the prefix "_" in the doc. It's actually reserved because sometimes, once day we will add other metadata which is fine. But raises the issue you have. If I summarise the discussion here amd precedent discussions there are different school there: - remove the metadata from the doc and put them in headers or aside. I quite like the first solution, though it may be a problem behind some proxies, or with the header length (especially for json values). Also headers are supposed to be in latin1 in a lot of clients... - put the metadata in their own namespace which is what you propose. I dislike the last solution. Mostly because it would force the clients to wait this namespace to read the metadata while parsing the JSON (which could be when streaming it). Instead I would prefer to keep them at the first level and due the reverse: put the data in their own namespace, say `_data`. This allows any clients to ignore this layer if needed while parsing the JSON and get it directly (without parsing then). The metadata should be the first citizem imo. Optionally we could add some new parameters to the doc api allowing someone to only fetch the metadata, etc.. Also couchdb could also parse the coming doc and stop to parse the json when seeing this property and store it directly. It is also following the logic of attachments somehow. Another things that could be done at the api level is having smth like `/db/docid/_data` which would allows you to only retrieve the data instead of using a show function. What do you think? - benoit
