On Tue, Dec 3, 2013 at 9:01 AM, Benjamin Young <[email protected]> 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 still. > 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. 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.
