couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian Mitchell <>
Subject Re: [PROPOSAL] new underscore namespacing
Date Tue, 03 Dec 2013 17:18:36 GMT
On Tue, Dec 3, 2013 at 9:01 AM, 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."

I've usually stored such data inside nested objects. Our top-level
namespace is getting muddy which not only affects our use of other
formats but other systems that would want to integrate CouchDB data in
them as well. I can imagine the sort of metadata that needs to be
stored will only grow with plugins.

> 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.*

Very nice. It makes a clear separation between system-controlled and
user-controlled name spaces. Avoiding the topic of whether or not
metadata should be embedded or not, this seems like an improvement.

> 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

We do have many other places where we use special names like _changes,
_all_dbs, _uuids &c. While this does mirror the document's special _
namespace, it makes it less consistent with everything else we put in
the URL. I'm not sure what else we are really buying here outside of
attachments with odd names.

> I realize these are extreme API shifts, and would need to wait for CouchDB
> 2.0.

All the more reason to find a way to get plugins working well so there
can be a playground for ideas before such a serious version jump is
made. Some of these are trickier since we don't really expose proper
APIs for manipulating some of these but it's probably worth looking at

> 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.

I wonder if the API could be versioned using HTTP headers. The CouchDB
host could set a default version and clients could request specific
versions. I've played with versioned vendor media types but those get
complicated and confuse far too many HTTP agents. A simple header like
Couch-API-Version: 2 might be a place to start.

> Thanks for considering this,
> Benjamin

Thank you for sharing.

View raw message