The article describes some very good engineering practices. Nevertheless I’d suggest the json Schema itself is not the root of the documentation but a higher level integrated system like API Blueprints MSON. You still can produce Schema from it but it also can tie into a much better API design lifecycle.