made links optional, in line with the HAL specification
added comments