Structure json schema files

[eugenk]

The JSON schema files that document the API need to be structured strictly for ontohub/ontohub-frontend#41 to work.

I suggest the following file names and directory tree:

• spec/support/api/schemas/: The JSON Schema directory
  • controllers/<controller_name>/: All the actions of the controllers are defined in this place. There is one file per action, for example, v2/repositories/get_show.json. These may contain $refs to files of the following bullet.
  • models/: Definitions of the models with their attributes, links and relationships. For instance, a repository_model.json would be here. These will be needed in the frontend to generate models there. The relationships themselves are just $refs to files of the following bullet.
  • relationships/: Definitions of the structure that the models have inside a relationships object. For example, the definition of properties.relationships.owner of a repository would be placed in the organizational_unit_relationship.json in this directory.

Every file should have the following header:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "<title for the documentation>",
  "description": "<description fot the documentation>",

  // the actual content of this schema goes here...
}

Note that there is no id of the schema itself any more.
Also, schemas that are referenced via $ref are defined in the root object and not nested in a definitions object.