added validation of input json against the schema

this doesn't work currently because JSON.NET doesn't support version v4
and throws on our schema
also added comments to several functions