Document general-purpose aggregation in business-modules

Let's put a page under the website GH repo about aggregation.

As I work on which includes migrating the inventory interface to use this composite includes format (and potentially to sharing schema definition, as this was part of the motivation for this style of interface), I've encountered a few questions around how we want to approach certain aspects (I’ll ask more as I figure out how to better express them).

1. Up until now, the collection resource type has used the same resource representation for read and write (GET, POST and PUT) meaning that a client can GET a representation and modify it to make write requests if it chooses to.

Following the discussions about aggregation, we are defining composite representations (e.g. https://github.com/folio-org/raml/blob/82f83f5dab40f60de9aa664b0940df41b77a3e76/schemas/mod-users-bl/compositeUser.json) for read (GET) responses.

Do we want to preserve the symmetry between read and write requests or use the none-composite representation of the primary record for write operations (POST/PUT)?

2. Given we intend to share the schema between storage and business logic modules, if a business logic module needs to extend the representation, should it do it by adding properties to the composite schema (meaning that it doesn’t only do aggregation of related record representations)?

As part of this change, we seem to be changing to using nested properties for the primary record. Where we used to have the user or item as the top level JSON object, we now represent them as compositions, where one of the properties is for this primary record e.g.

instead of:

If we have business logic interfaces that don't currently have any related records and so no inclusions, do we still want to nest the primary record (as this makes it more consistent and allow for extension to these related records later without necessarily breaking compatibility)?

Agreed; omit.

My preference would be to omit it entirely.

From the experiments I've tried with schema, if we decide to validate the response, the patronGroup would be expected to be an object and I don't think null validates again that definition (unless we say that patronGroup can be an object or null).