One area where JSON Schema is perhaps a little lax is the basic requirement for the document to be a JSON object in order for it to contain meaningful information. JSON Schema allows a document to contain a simple boolean value of “true” or an empty anonymous object to represent a schema that will always validate (conversely, a simple boolean value of “false” will never validate). I may come to discover why this was considered beneficial but my starting point for JSD is that a valid JSD document must have an anonymous object as its root.
Both XML Schema and JSON Schema provide metadata fields to identify the schema of the document (using a URI) within the document itself. In JSON Schema, this is achieved using the property “\$schema”, and this seems a very reasonable starting point. As such, valid JSD documents should include a reference to the formal JSD schema definition document through the “\$schema” property. There then comes the question of identifying the schema that the JSD document is itself defining. JSON Schema uses the “$id” property for this but, while “\$id” has the advantage of brevity, it seems less intuitive that “\$schema” refers to the schema of the JSD document while “\$id” refers to the schema that is being defined by it. It is also worth noting that the development of JSON Schema has clearly considered whether the identification of the target schema is a meta property of the schema definition or actually just a simple property of the schema definition alongside structural definitions. I lean towards the latter perspective and, accordingly, JSD documents will use the property “target-schema” to identify the schema being defined using a URI.
{
"$schema": "https://whitecottage.org.uk/JSD/2025-06/",
"target-schema": "https://somedomain.com/schema-id"
}It should be apparent at this point that a convention could be adopted whereby the presence of the “\$schema” property in any JSON instance document could be interpreted as a reference to the definition of its schema.
Thinking back to the structure of XSD, one useful concept it introduced was a Schema location expressed as a URL in addition to the identifying URL. To add this into the JSD specification, we use the optional “schema-location” property, thus:
{
"$schema": "https://whitecottage.org.uk/JSD/2025-06/",
"target-schema": "https://somedomain.com/schema-id",
"schema-location": "https://somedomain.com/schema-id"
}At this point, we now need to start addressing the definition of the structure of the schema. JSON Schema very sensibly uses the “type” property for this purpose, which we will also adopt. This immediately requires us to think about restricting the values of simple JSON types as the “type” property itself must clearly be restricted to an enumeration of valid JSON types (“object”, “string”, etc.). JSON Schema handles this using the “enum” specifier in place of the “type” specifier (noting that a property could have multiple valid value types). Again, we will adopt this approach. Given that the type of any property (particularly the document root) may be an object, we must also allow object properties to be declared and the JSON Schema “properties” property of type “object” again makes good sense.
We can now start to use the JSD for JSD as an example for building out the rest of the syntax:
{
"$schema": "https://whitecottage.org.uk/JSD/2025-06/",
"target-schema": "https://whitecottage.org.uk/JSD/2025-06/",
"schema-location": "https://whitecottage.org.uk/JSD/2025-06/",
"type": "object",
"properties": {
"$schema": {
"type": "string"
},
"target-schema": {
"type": "string"
},
"schema-location": {
"type": "string"
},
"type": {
"enum": ["object", "array", "string", "boolean", "number", "null"]
},
"enum": {
"type": "array"
}
}
}