couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benjamin Young <>
Subject Re: [PROPOSAL] new underscore namespacing
Date Tue, 03 Dec 2013 15:42:22 GMT
Replies inline...

On 12/3/13, 9:16 AM, Robert Newson wrote:
> I like the idea, though I remember a suggestion to lift all of these
> things out of the bodies entirely (I'm thinking mostly of _id and
> _rev) and into request/response headers. This has other advantages (we
> wouldn't need to convert doc bodies to a mutable intermediate state to
> inject id and rev, we could send it more directly).

The end objective is to get CouchDB (and friends) to be more receptive. 
The ideal would be to get all the meta-data out of the body/content 
area, so we can avoid "opening the envelope" to do the routing.

This "doc._.*" proposal is mostly a hybrid, but I'd be more than happy 
to see it only applied to "internal" docs like _users, _replicator, etc. 
Docs we act on or produce ourselves, and then move content documents 
into a doc + meta/headers combo (like you and now Volker just described).

> As for "I realize these are extreme API shifts, and would need to wait
> for CouchDB 2.0.", this has it precisely backwards. There's no waiting
> for 2.0. If we change the API in incompatible ways, we bump the major
> version. To say it another way, making this change *creates* couchdb
> 2.0.

Fabulously rephrased. Thank you! :)

> As for migration, I think it would only be necessary for 2.0 to
> understand the old format. E.g, the replicator would look for
> doc._.replication_state first and fallback to doc._replication_state
> if it's missing. We could go further and add forward looking code in a
> minor release that does the reverse of that.


> Of course now I'm visually how the chttpd/couch_httpd url mapping code
> will look for the /_/ idea... :D

Let the fun begin. ;)

Perhaps a good first step would be an exploratory plugin that handles 
these proposed "/_/" routes for design document endpoints. Maybe?

> B.
> On 3 December 2013 14:01, Benjamin Young <> 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._.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]
>> [2]

View raw message