Some questions related to custom json schema

Question

I'm noob to json. While defining the format of my RESTful API's result (viz JSON), I felt it would be easier to document it as my own JSON schema. While writing one I had few questions:

1. In my result JSON, how do I specify the URI to teh schema it confirms to? --edit-- is it using $schema attribute?
2. Are there any conventions/guidelines for JSON schema versioning? Are there some attributes that I should/can define inside my schema as attributes? I see JSON schema itself has no version defined except in it's URI specified as value of key $schema.
3. Can I break down my one BIG JSON schema into multiple smaller ones and include one in another? Like #include in C++, then refer to multiple schemas in the JSON I sent to user as result.
4. Can I define a custom value for key "type"? E.g. I would like to reuse the definition of "date" like this:

[ignore this line, it's to get the formatting working for following json..]

{
    "date":{
        "type":"object",
        "properties":{
            "month":{
                "type":"integer",
                "minimum":1,
                "maximum":12
            },
            "year":{
                "type":"integer",
                "minimum":0
            }
        }
    },
    "personInfo":{
        "type":"object",
        "properties":{
            "name":{
                "type":"string"
            },
            "dateOfBirth":{
                "type":"date"
            }
        }
    },
    "student":{
        "type":"object",
        "properties":{
            "id":{
                "type":"personInfo"
            },
            "pass_out_year":{
                "type":"date"
            }
        }
    }
}

instead of providing properties of "date" in multiple places like this:

{
    "personInfo":{
        "type":"object",
        "properties":{
            "name":{
                "type":"string"
            },
            "dateOfBirth":{
                "type":"object",
                "properties":{
                    "month":{
                        "type":"integer",
                        "minimum":1,
                        "maximum":12
                    },
                    "year":{
                        "type":"integer",
                        "minimum":0
                    }
                }
            }
        }
    },
    "student":{
        "type":"object",
        "properties":{
            "id":{
                "type":"personInfo"
            },
            "pass_out_year":{
                "type":"object",
                "properties":{
                    "month":{
                        "type":"integer",
                        "minimum":1,
                        "maximum":12
                    },
                    "year":{
                        "type":"integer",
                        "minimum":0
                    }
                }
            }
        }
    }
}

according to 5.1 type in the spec, it's not possible, but it seems like such a basic usecase!

Answer 1

1. As you correctly figured out, $schema can be used to specify the schema it conforms to.
2. I actually found this topic while googling for JSON Schema versioning, and the idea of using the URI for versioning sounds logical.
3. You can use $ref to link to another schema that is then pulled in.
4. Again, you could use $ref and JSON Pointer to import definitions from other schemas.

You can always test things out by validating your schema to see if you've made any mistakes.

Answer 2

At the time of this writing, the current version of the JSON Schema specification is draft-v4, in which the format date-time for string instances is clearly specified and is very useful in practice.

There is no simpler format date defined so far, but you can easily define your object's property as type string and then apply a format pattern validation (ECMA 262 regex dialect) on top of it.

For example:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Example Schema"
    "description": "This schema contains only a birth date property"
    "type": "object",
    "required": ["birth_date"],
    "properties": {
        "birth_date": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
        }
    }
}

Answer 3

Why don't you just use the "format" : "date" as per #5.23 in JSON Schema Draft 03?

Plus your definition of birth date doesn't contain date which seems to be an error.

Answer 4

The spec seems to suggest you could:

Other type values MAY be used for custom purposes,...

It then goes on to discuss what validators of the minimal implementation might do.

To my mind, what you want to do seems OK. It might help your schema's clarity to keep the type reference and type definition in the same file.

I think your file includes Q should be handled outside of json, e.g. have a dev step that generates the complete json from a script/template (e.g. erb or some such) merging your subfiles. To my mind your service should always deliver the full json required to fully interact with that service. If this gets unmanageable from the clients perspective, it may be a signal to refactor and introduce another service.