On 29/12/2008, at 7:20 PM, Christopher Lenz wrote:
This would break all substantial client code out there for
questionable benefit.
It's not even a released product yet. Preserving accidental
implementation artifacts to satisfy early pre-release clients is a
very sad idea.
I don't think there's anything inconsistent here, or anything to be
confused about. The rule is simple: reserved fields *inside*
documents have a leading underscore as to not clash with user fields
(as user fields must not have a leading underscore at the top-level
of the document).
Why have any rule about 'inside' or 'outside' a document - just use
the same name everywhere.
There are a couple of meta-data fields that are packed into
documents, such as "id" and "rev". Now just because those fields get
the leading-underscore treatment in documents doesn't mean they need
a leading underscore whenever they appear in other places, such as
view results.
By using a consistent name for fields you reduce confusion and
emphasise that they have the same semantic type. Your argument is
based on the underscore not actually being part of the name, but
rather a removable qualifier that is used to reduce the chances of
collision. Contextually sensitive name transformations in an API are
an unnecessary complication.
Then the question is, where would you stop? Would you also rename
"key" to "_key", "value" to "_value", and so on, for consistency?
What about the "?rev=1234" query-string parameter? We could get to a
point where every term used in the API will have a leading
underscore just "to be safe" :P
Both key and value never appear in a couch-metadata role within a
document. I think _rev in the query string parameter is a good idea
for consistency. Whenever a _rev appears, it's name should be _rev.
Same for the _id of a document.
I think this is the wrong direction. If these naming issues really
are generating substantial confusion (which I doubt), we should
rather be looking into changing the mechanism for including meta-
information with documents so that the leading underscores could be
dropped across the board.
It's not about *substantial* confusion - I'd like to see as much
consistency and regularity in the API as possible before a 1.0
release; said release being IMO a point at which backwards compatible
cost-benefit concerns become appropriate.
Maybe something like:
{
"_meta": {
"id": "foo",
"rev": "1234"
},
"title": "Foo",
...
}
This would also cause client breakage, but at least we wouldn't be
scattering more underscores around the API.
I really like this idea.
Oh, and if this thread was actually only about the "rev" field in
the review results of _all_docs (note it's *not* in all view
results), why not just drop it instead? Is there any practical
reason it's in there?
I think it should either be in every view result that has an id, or in
none. In so many cases you need the id and the rev to represent point-
in-time identity, I think they should be supplied together whenever
feasible.
Antony Blakey
-------------
CTO, Linkuistics Pty Ltd
Ph: 0438 840 787
A Buddhist walks up to a hot-dog stand and says, "Make me one with
everything". He then pays the vendor and asks for change. The vendor
says, "Change comes from within".
