Merging Capabilities

NOTE: This documentation is a work in progress

The ability to have a document reference other documents (via the 'links' construct) means that merging strategies are required to handle scenarios where the linked documents and current document contain overlapping keys.

The supported merge scenarios are detailed below, with the help of these sample JSON documents.

###defaults.json { "settings": { "numCores": 2, "memoryGb": 4, "roles": [ "common" ], "drives": [ { "name": "OS", "sizeGb": 40 }, { "name": "SWAP", "sizeGb": 10 } ], "certificateInfo": { "thumbprintAlgorithm": "sha1", "purpose": "Server Authentication" } } }

###document.json { "links": [ "defaults.json" ], "settings": { "memoryGb": 8, "roles": [ "sql" ], "drives": [ { "name": "SWAP", "sizeGb": 20 }, { "name": "DATA", "sizeGb": 500 } ], "certificateInfo": { "thumbprint": "0a52e0c3b55f4dfef40f5737120e604dbfecf947", "purpose": "Client Authentication" } } }

##Notes on Precedence Simple precedence rules are applied when resolving the final values for keys that exist in multiple documents.

The root document will be processed top to bottom, links first (in the order they are specified in the root document) and with the keys/values defined in the root document taking the highest precedence.

TODO: Example

##Scalar Values This is the simplest scenario, whereby values in the root document (e.g. 'document.json') will override equivalent values in linked documents.

####Example Results settings.memoryGb = 8

##Scalar Arrays Arrays of simple values will be combined to form a superset of values from all documents, root and linked.

####Example Results settings.roles = [ "common", "sql" ]

TODO: Ordering rules?

##JSON Objects Objects will have their keys & values combined to form an object with a superset of keys/values from all documents, root and linked.

Where the same key/value pair is defined in multiple documents the precedence rules described above are applied.

####Example Results settings.certificateInfo = { "thumbprintAlgorithm": "sha1", "thumbprint": "0a52e0c3b55f4dfef40f5737120e604dbfecf947", "purpose": "Client Authentication" }

##JSON Object Arrays Arrays of objects will be combined to form a superset of all the objects from all documents, root and linked. To avoid sequencing differences between documents causing non-deterministic results, a convention is used whereby objects are keyed by their 'name' property.

####Example Results settings.drives = [ { "name": "OS", "sizeGb": 40 }, { "name": "SWAP", "sizeGb": 20 }, { "name": "DATA", "sizeGb": 500 } ]