Proof of concept: Split out one RAML schema into a file

We should split the RAML files into smaller more specific ones. Our processes for generating the documentation etc. should be updated to handle split/multiple RAML files. This ticket is for doing this in on place—probably the RBAC rights endpoints—so we can make sure all our tooling works with external RAML schema files.

We would define our JSON Schemas in external JSON files and then reference them in the RAML like so:

That would create a number of extra files, but it works in RAML v0.8, so that's the benefit for now.

Acceptance Criteria

• Updated RAML files for RBAC in Reference Data service.

• Test that Swagger and static API docs still work correctly with the split-up RAML. Address any bugs or issues with that.

• Verify that our automated tests that check RAML schemas also work correctly with the split-up RAML.

• Add documentation into the wiki or the code Style Guide to explain that our standard practice for RAML schemas is to split them into their own files.

• If this new pattern works, put out guidance for other developers on how to do this elsewhere (then we may update the check list).