document corner-cases with map_by schemas