Flat JSON versus JSON with nested structures

The structure of some z/OS-based log records can be complex. Records can be divided into sections that repeat, and sections can contain subsections.

In some cases, you might need to convert log records to JSON that retains the original nested structures. In other cases, you might prefer flat JSON, where each input record is represented as a flat sequence of key-value (KV) pairs, without nested structures.

Flat JSON

By default, the JSON command writes flat JSON: JSON without nested structures. All fields are first-level properties, so you can refer to them simply by name. You don't need to qualify field names with any antecedent names. For example (shown with line breaks and indenting for readability):

{
  "time": "2015-12-31T13:59:00.123456Z",
  "type": "smf-xx",
  "smfxxa1": 1.3,
  "smfxxa2": "MYID",
  "smfxxb1": 2.4
}

Flat JSON is useful when you need KV pairs but you don't want nested structures. Some analytics platforms ingest KV-pair format data faster than delimited data formats such as CSV, because KV pairs enable field extraction to be reliably deferred until search time; the correct field names are embedded in the raw ingested data.

JSON with nested structures

If you specify the FLAT(NO) parameter, the JSON command writes JSON with nested structures. Log data is nested in a data property. Inside the data property, fields are nested in sections. For example:

{
  "time": "2015-12-31T13:59:00.123456Z",
  "type": "smf-xx",
  "data": {
    "dsecta": {
      "smfxxa1": 1.3,
      "smfxxa2": "MYID"
    }
    "dsectb": {
      "smfxxb1": 2.4
    }
  }
}

where:

  • dsecta and dsectb are data sections (DSECTs) in the z/OS® assembler mappings of the original log records
  • smfxxa1, smfxxa1, and smfxxa3 are field names

In some contexts, nested structures in JSON are useful. For example:

  • Encapsulating event-specific data in a common data property can simplify parsing. All objects have the same high-level properties, including time, type, and data. You can use the value of the type property to determine how to parse the contents of the data property.
  • Nesting fields in section properties enables you to reproduce the original log record structure; for example, if you want to present log data in a user interface with fields arranged under section headings.

However, in other contexts, nesting can have undesirable consequences, such as having to qualify field names with their antecedent property names, requiring you to remember which section each field belongs to. For example, referring to a response time field might mean using the verbose field reference data.dfhtask.response instead of just the field name response.