JSON v2

These are some thoughts on an improved JSON data-format that includes support for namespaces and schema description.

We want to optionally include a JSON schema for a namespace. Schema could be either inline or a URL which would identify the schema. For example below the 'jj5' schema is inline but the 'example' schema is by-ref.

The rules for namespaces are that you have to nominate an alias for each namespace that you use. You can use multiple aliases for the same namespace. The alias 'default' is special (a reserved word) and it is used to point to the alias for the namespace which is assumed when no namespace alias appears on data items. (/* 2017-07-08 jj5 - THINK: do we want syntactic support for auto-generated namespace aliaes? E.g. a namespace with a '$' or '-' in it might indicate it was generated automatically by software? */)

The 'version' and 'namespace' data is listed first, then the 'data' itself, then the 'schema' data if it's available. We put the schema last because it's the least interesting thing to read when a human is looking at the data.

NOTE: one problem with namespaces (and namespace aliases) is that they complicate the data format. So it would probably be useful to have tooling which could simplify a JSON v2+ document. Simplification would return data from the document in a single nominated namespace and strip out all namespace aliases. So you can process data in your own namespace without regard for which specific namespace aliases were used or what other data may have been added from foreign namespaces.

var data = {

  // a JSON v2+ document is indicated by a sole 'json' property in the root data item
  "json": {

    // 'version' is only a 'major version' for the JSON format, this should rarely change
    "version": 2,

    // a map of namespace aliases and the namespace they refer to
    "namespace": {

      // the 'default' namespace alias is the alias implied if no alias is specified
      "default": "jj5",

      // the formal namespaces are a URL the details of which may vary as indicated in these examples
      // it would be nice if these URLs returned the JSON schema for themselves, but that is not a requirement
      "jj5": "https://schema.jj5.net/json/example/v2/schema.json",
      "ex": "https://v1.example.schema.json.example.com/schema.json"

    },

    // note that the 'data' array can't indicate its namespace so is implicitly in the 'default' namespace
    "data": [
      {

        // these properties don't have a namespace alias so are in the 'default' namespace
        "first_name": "John",
        "last_name": "Elliot",

        // a namespace is indicated with its alias followed by a semi-colon
        "ex:lucky_number": 37,

        // this looks like a namespaced attribute, but since we don't have a 'bogus' namespace alias it's not one
        "bogus:thing": "not a namespace alias"

      }
    ],

    "schema": {

      // so we have an inline schema for 'jj5' but no schema for 'ex':
      "jj5": {

        "$schema": "https://schema.jj5.net/json/example/v2/schema.json",
        "title": "List of people",
        "type": "array",
        "items": {
          "title": "Person",
          "type": "object",
          "properties": {
            "first_name": {
              "type": "string"
            },
            "last_name": {
              "type": "string"
            },
            "age": {
              "description": "Age in years",
              "type": "integer",
              "minimum": 0
            }
          }
        },

        // I'm not sure how to indicate an "open information model" where any extra unknown properties are allowed...
        "required": [ "first_name", "last_name" ]

      }
    }
  }
};

Simplification

Some example input:

{
  "jj5:first_name": "John",
  "jj5:last_name": "Elliot",
  "ex:lucky_number": 37,
  "bogus:thing": "not a namespace alias"
}

After simplifying for the jj5 namespace this input becomes:

{
  "first_name": "John",
  "last_name": "Elliot"
}

// 2017-07-08 jj5 - THINK: should there be a 'complification' process to merge changed simplified data back into the original payload..? :P