fixed apiVersion key
tighten up spec and add comments