6. Socorro JSON Schemas

This folder contains JSON Schema files describing the documents that Socorro generates. At the moment only the Processed Crash (the one generated by Socorro’s processors) is described.

These files will be used as a “contract” between Socorro and other systems to which we might send our data.

6.1. Changing The Schema

You can change the schema but if you do, remember to increment the $target_version.

The JSON Schema should contain a key called $target_version.

  • It’s important this is an integer that goes up
  • Don’t change this if you’re…
    • Adding more keys at the root level
    • Editing comments (content of description values)
  • Do change this if you’re…
    • Adding more keys inside a nested object
    • Changing the type definition of an existing key in any way
    • Add or remove keys from a required sub-key. For example, if a key was required but you’ve now removed it. This is applicable at any nested level.

Yes, if you add more keys, don’t change the version. For example, if you want to add a new field to the root like this:

+ "addons_checksum": {
+     "type": ["string", "null"],
+     "description": "Sample specimen"
+ }

then don’t change the version.

However, if you add a key inside a nested structure, you have to bump the $target_version number by 1. For example:

@@ -286,8 +286,12 @@
     "json_dump": {
         "type": "object",
         "description": "The dump as a JSON object.",
         "properties": {
+            "for_example": {
+                "type": ["string", "null"],
+                "description": "Brand spanking new field inside json_dump"
+            },
             "crash_info": {
                 "type": "object",
                 "properties": {
                     "address": {

Also, if you change the type definition, for example:

"addons_checksum": {
-   "type": ["string", "null"],
+   "type": ["integer", "null"],
    "description": "Sample specimen"
},

Then you have to increment the $target_version number by 1.

6.2. Testing Schema Changes

If you desire to edit the crash_report.json file, it’s recommended that you test that it still validates. For example, if you add a change like this:

+"memory_max_length": {
+   "type": ["integer", "null"],
+   "description": "Max. amount of memory length for a crash"
+},

Then, you should test that at least 100 randomly picked crashes have a type on that field that is either integer or null. To do that, from a checkout of socorro run:

$ python socorro/schemas/validate_and_test.py

That will download 100 crashes, run the JSON Schema validator against those crashes with your local crash_report.json file.

Note

The validate_and_test.py, by default, does a Super Search query for basically product=Firefox and takes the 100 most recent crash IDs. This might miss out on some more “rare” crashes whose additional values might better test your JSON Schema changes. To remedy that, go to Super Search in your browser, make a search that you know includes good crash IDs to test and paste that URL like this:

$ python socorro/schemas/validate_and_test.py \
      "https://crash-stats.mozilla.com/search/?dom_ipc_enabled=%21__null__&memory_images=%3E10&version=54.0a1" \
      "https://crash-stats.mozilla.com/api/SuperSearch/?memory_private=%3E100&product=Firefox&date=%3E%3D2017-02-24T16%3A14%3A00.000Z&date=%3C2017-03-03T16%3A14%3A00.000Z"