RFC: Change to container schema specification.

[saibotsivad]

Currently the container specifies the schemas to validate against in this way:

"schemas": [
  "sdmp://GlvAreTo..."
]

Each schema is resolved and the container is validated at the root.

There are two technical limitations:

1. There could be a collision of property names, if two schemas are desired in a single container.
2. If a schema wants to be restrictive, it would need to include the container schema as well.

Because of this, I propose that the schemas property becomes an object map, where the key matches the container key, and the value is the schema used to validate the container property.

The SDMP example valid container would then look like this:

{
  "sdmp": {
    "version": "0.13",
    "schemas": {
      "example": "sdmp://GlvAreTo..."
    }
  },
  "example": {
    "hello": "world"
  }
}

The key name example is entirely arbitrary, so that an equally valid container would be:

{
  "sdmp": {
    "version": "0.13",
    "schemas": {
      "anything": "sdmp://GlvAreTo..."
    }
  },
  "anything": {
    "hello": "world"
  }
}

[saibotsivad]

I have to say that I'm not very keen on this approach. Mostly because it allows for property names which are unrelated to the property content. E.g.

{
  "sdmp": {
    "version": "0.13",
    "schemas": {
      "identity": "sdmp://URI"
    }
  },
  "identity": {
    "key": "key like object"
  }
}

This example makes the JSON object read as though the identity property could be an identity object, and this confuses the document.

The alternative approach I've been working on would be like this:

{
  "sdmp": {
    "version": "0.13"
  },
  "sdmp://GlvAreTo...": {
    "hello": "world"
   }
}

Then you would simply say that the object keys must be the core names (e.g. identity, encrypted, etc.) or a URI to a schema. The key would define how to validate the value.

The one change with this (compared to the proposed approach) is that you can't have multiple of the same schema type. This is the same as the current 0.12 SDMP, so that's not an overall change.

[jmhobbs]

I agree on the arbitrary nature of schema names, but I also prefer the explicit schema enumeration in the first example.

What about some sort of required extension namespace?

{
  "sdmp": {
    "version": "0.13",
    "schemas": {
      "identity": "sdmp://URI"
    }
  },
  "schema:identity": {
    "key": "key like object"
  }
}

or at the very least bring back the list of expected schemas?

{
  "sdmp": {
    "version": "0.13",
    "schemas": [
        "sdmp://GlvAreTo..."
    ]
  },
  "sdmp://GlvAreTo...": {
    "hello": "world"
   }
}

[saibotsivad]

:+1: I do like that last example, where the schemas are enumerated and also set in their namespace by the schema URI. I suppose that would make it easier on some implementations--they can always look at sdmp.schemas for the list of expected data.

[saibotsivad]

I made the changes in #53 for this. One thing I noted that I'm not too thrilled about is that a container now looks like this, which means that the URI is repeated twice (I'm not too keen on how many bytes it adds):

{
    "sdmp": {
        "version": "0.10.6",
        "schemas": [
            "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA"
        ]
    },
    "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA": {
        "hello": "world"
    }
}

[saibotsivad]

It should be noted that most application data probably won't be that short, so an actual container might look more like this:

{
    "sdmp": {
        "version": "0.10.6",
        "schemas": [
            "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA"
        ]
    },
    "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA": [{
        "description": "Bart's home address",
        "street": "123 N West St.",
        "city": "Springfield",
        "state": "IL",
        "zipcode": "12345"
    },{
        "description": "Bart's school address",
        "street": "9001 Oakville Plaza",
        "city": "Springfield",
        "state": "IL",
        "zipcode": "12345"
    }]
}

In this example, there are still the duplicated bytes of the URI, but the contributing size of it (relative to the data) is much smaller.

Still, it might be an argument to have named properties, e.g.:

{
    "sdmp": {
        "version": "0.10.6",
        "schemas": {
            "address": "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA"
        }
    },
    "address": [{
        "description": "Bart's home address",
        "street": "123 N West St.",
        "city": "Springfield",
        "state": "IL",
        "zipcode": "12345"
    },{
        "description": "Bart's school address",
        "street": "9001 Oakville Plaza",
        "city": "Springfield",
        "state": "IL",
        "zipcode": "12345"
    }]
}

[saibotsivad]

I'm leaving it the longer way in #53, but more discussion prior to the 0.13 release might be appropriate.

[saibotsivad]

I would like to believe that I'm older and wiser now, and in that (hopeful) wisdom I'm thinking of something like this:

{
  "sdmp": {
    "version": "0.13",
    "schemas": {
      "key1": "sdmp://GlvA...",
      "key2": "sdmp://reTo..."
    },
    "data": [{
      "schema": "key1",
      "content": { ".....blah1....." }
    }, {
      "schema": "key1",
      "content": { ".....blah2....." }
    }, {
      "schema": "key2",
      "content": { ".....more blah....." }
    }]
  }
}

[saibotsivad]

And then I'm thinking that, if the structure is that shape, it could be simplified to this:

{
  "version": "0.13",
  "schemas": {
    "key1": "sdmp://GlvA...",
    "key2": "sdmp://reTo..."
  },
  "data": [{
    "schema": "key1",
    "content": { ".....blah1....." }
  }, {
    "schema": "key1",
    "content": { ".....blah2....." }
  }, {
    "schema": "key2",
    "content": { ".....more blah....." }
  }]
}

[saibotsivad]

Here's a more complete example, with "real" data:

{
  "version": "0.13",
  "schemas": {
    "address": "sdmp://GlvAreTo0lCSyum7Wzh8pzhxYOOu-gMIgO2N95AAwAGP6-nR8xCvWvIW0t9rF_ZZfpCY_fDV38JDFKaOU91A8Q/h6FWguOHjaB5eUCsjeSIUGxA6p2abtY6HmaUin0F_9INc60VT3IELkP-q7IuWEwBCA8SpIbkfO9ZAIj5jgusYA"
  },
  "data": [{
    "schema": "address",
    "content": {
      "description": "Bart's home address",
      "street": "123 N West St.",
      "city": "Springfield",
      "state": "IL",
      "zipcode": "12345"
    }
  },{
    "schema": "address",
    "content": {
      "description": "Bart's school address",
      "street": "9001 Oakville Plaza",
      "city": "Springfield",
      "state": "IL",
      "zipcode": "12345"
    }
  }]
}