add docs for the new json format