Metadata format

[chrismajewski]

We need a consistent way to do metadata.

The first part is simple, you use a metadata:{} object as described by json ( http://www.json.org/ ). This is the consistent usage:

    {
        metadata:{}
    }

What differs is how the subsequent data is defined, there are two forms leading to 3 choices ( I can see now ).

1. explicitly nested:

    {
        metadata:{}
        data:{
            "x": 1,
            "y": 2,
            "z": 3
        }
    }

1. metadata as an addition to the data:

    {
        metadata:{}
        "x": 1,
        "y": 2,
        "z": 3
    }

1. or we allow for both.

For official languages the current recommendation is forced nesting. Forced nesting in this case may be considered consistent.

Additionally, the "data:" object can be one of multiple different names but "data:" is a logical complement to "metadata:".

Open for comment.

[samboisvert]

According to the Pragmatic guide for RESTful Services, you shouldn't use a "data" envelope: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#envelope

If we follow this guide, your second option is better.

[chrismajewski]

This is in the document. Closing.