types and specs for public functions