Annotated schema example

Below is the schema for blood glucose. Explanations are interspersed.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "This schema represents a person's blood glucose level, either a single blood glucose measurement, or the result of aggregating several measurements made over time (see Numeric descriptor schema for a list of aggregate measures)",
    "type": "object",

The description specifies the quantitative measure defined by the schema.  

    "references": [ 
        { 
            "description": "The SNOMED code represents Blood glucose level (finding) ", 
            "url": "http://purl.bioontology.org/ontology/SNOMEDCT/365812005" 
        }

References: clinical measures usually can be mapped to a term in a standard dictionary [see Schema design principles for details].  

    ],
    "definitions": {
        "unit_value": {
            "$ref": "unit-value-Y.x.json"
        },

unit_value: A blood glucose measurement value consists of a number and a unit of measure.  

        "specimen_source": {
            "$ref": "specimen_source-1.x.json"
        },

specimen_source: Blood glucose can be measured in different types of blood, so this is one important element characterizing this quantitative measure.  

        "time_frame": {
             "$ref": "time-frame-Y.x.json"
        },
        "temporal_relationship_to_meal": {
            "$ref": "temporal-relationship-to-meal-1.x.json"
        },
        "temporal_relationship_to_sleep": {
            "$ref": "temporal-relationship-to-sleep-1.x.json"
        },

temporal_relationship_to_meal: Blood glucose is affected by food intake: both the Temporal relationship to meals and the Temporal relationship to sleep are important elements characterizing this quantitative measure.  

        "descriptive_statistic": { 
            "$ref": "descriptive-statistic-Y.x.json" 
        } 
    }, 
    "properties": { 
        "blood_glucose": {

blood_glucose above is the name of the actual measure.  

            "allOf": [ 
                { 
                    "$ref": "#/definitions/unit_value" 
                }, 
                { 
                    "properties": { 
                        "unit": { 
                            "enum": [ 
                                "mg/dL", 
                                "mmol/L" 
                            ] 
                        } 
                    } 
                } 
            ] 
        },

unit: blood glucose measurements are expressed most commonly in mg/dL and less commonly in mmol/L. No other units should be used and hence a value set if defined.  

        "specimen_source": {
            "$ref": "#/definitions/specimen_source"
        },
        "effective_time_frame": {
            "$ref": "#/definitions/time_frame"
        },
        "temporal_relationship_to_meal": {
            "$ref": "#/definitions/temporal_relationship_to_meal"
        },
        "temporal_relationship_to_sleep": {
            "$ref": "#/definitions/temporal_relationship_to_sleep"
        },
        "descriptive_statistic": {
            "$ref": "#/definitions/descriptive_statistic"
        }
     },
     "required": ["blood_glucose"]
 }

required: the actual value of the measure should be required.