Design Documents in CouchDB and Validation

To start off, here are the links to my previous posts about CouchDB:

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)
3. PUTting the Couch(DB) in Your Living Room
4. GETting Documents From CouchDB
5. DELETE Documents From CouchDB
6. Adding Attachments to a Document in CouchDB
7. Views into CouchDB

I briefly mentioned ‘design documents‘ in my previous post as the way views are being stored in CouchDB. This is probably the most common use of design documents, but there’s more. One thing that’s interesting is the ability of performing validation. Now before anyone starts raving like a mad man, I’m not implying that all validation or, to make matters even worse, that business rules should now all be handled by CouchDB, let along they should all be written in JavaScript from now on. In fact, quite the contrary.

But one concern that comes to mind that might be interesting for its use is validating the structure of a document.

As you might have noticed from my previous posts, we always dealt with one type of object. But a hello-real-world application typically has a domain where multiple types of objects need to be persisted. With an RDBMS, we usually have separate tables to store these different kinds of objects. CouchDB on the other hand only has the notion of storing documents. Now suppose, we need to store both Customer objects and Order objects (every application needs those, right?). How would we deal with that in CouchDB?

Well, very simple. We’ll just add a Type field to every document.

{
    "Type" : "Customer"
    "FirstName" : "Homer"
    "LastName" : "Simpson"
}

{
    "Type" : "Order"
    "Supplier" : "Duff"
    "Subject" : "Sweet, sweet beer" 
}

Just common sense. In order to get a list of all orders, we could provide the following map function:

function(doc) 
{
  if(doc.Type != "Order") 
    return true

  emit(null, doc);
}

Piece of cake. Now we can use the validation capabilities of CouchDB to ensure that every document that is stored contains a Type attribute. They way to handle this is to create a design document that contains an attribute named ‘validate_doc_update’ that specifies a validation function of the following signature:

function(newDoc, oldDoc, userCtx)
{}

Now in order to keep clear of documents that specify no Type attribute, we could write the following function:

function(newDoc, oldDoc, userCtx)
{
    if(!newDoc.Type)
    {
        throw(
        {
            "Error" : "Documents need a type around here."
        });
    }
}

Every time a document is saved or updated, CouchDB will call every validation function that is stored in a design document with the key ‘validate_doc_update’. When every function passes, the document will be stored. Otherwise, CouchDB will return HTTP status 403 (Forbidden) with a JSON response that contains the error we specified in the validation function.

As you an see, CouchDB provides you with a nice and easy to use validation mechanism that can be useful in a couple of scenarios.

Till next time