DriveWorks Pro 22

JSON Document

JSON Document

Integrating data with external systems has been further enhanced with the ability to configure, generate and transfer functional, validated JSON Documents from any valid Schema.

The DriveWorks JSON Document facilitates easier creation of JSON data.

The JSON Document creates a new JSON document which allows you to construct a generated JSON object, with rule driven properties, from a reference schema.

Learning JSON

To understand JSON the website JSON Schema is an essential resource.

Creating JSON

To create JSON schema the website JSONschema.net provides an easy to use interface for constructing JSON.

The examples, in the section below (see Example JSON Schema in the To Add a JSON Document), may also be useful.

Data Types

When the "type" property is provided in a schema, DriveWorks will attempt to coerce values to the given type.

The following data types are supported:

• string
• number
• boolean
• object
• array
• null

When DriveWorks creates the JSON the following rules will apply (in order of importance):

1. If the rule result can be parsed as a well-formed JSON string, then it will be parsed and appended as the properties value.

   The data type in the schema will be ignored and DriveWorks will not inspect the internal value of this string during document creation.

   • DriveWorks will not make any modifications to the JSON string and it will be driven as-is. It will be validated as part of the final generation stage (see Schema Vaidation below)
   • DriveWorks will try to parse anything that begins and ends with { } or [ ].
   • It's worth remembering that malformed JSON strings are effectively just strings.
2. If the rule result is driven from a table, then:
   • If the table is a single row; An object will be created as the property value, the table headers become the property names with the cell values driven into each property respectively
   • If the table is multiple rows; The property will become an array, with multiple child objects. Each child object will take the table headers as it's property names and cell value as the property value.
     These rules are recursively applied to cell values, making it possible to reference a simple table within a cell rule of a calculation table (or nest multiple calculation tables within each other) to generate increasingly complex JSON objects.
3. If the rule result is a simple value, then DriveWorks will try coerce it from the type within DriveWorks to a suitable JavaScript type as per the schema.
   • For example if a rule resulted in "1" (with quotes) and the schema specified that the property should be a number, then it is normally possible to parse the value and drive it as 1 (without quotes). If the same example stated that the property was a string type, then the quotes would remain signifying that it is a javascript string type.
   • If the target type (as specified in the schema) is a:
     • String - It will be a string - all DriveWorks values can be expressed in a string format.
     • Number - We will first try parsing the value as an integer, then a double and if all fail, output the value as a string with a warning. If the rule result is empty then we will default to 0.
     • Boolean - We will parse the value as a boolean. If parsing fails a warning will be generated and no value will be set and it will be treated as null
     • Object - Child properties will be parsed subject to these rules recursively. If no children are specified and no value is driven via a rule, null will be driven to the output.

       If a rule is attached to the parent (driving a JSON object for example) and children are also present, then we will attempt to satisfy both sets of data by merging the two. In the case where a property is specified in the rule result and in a UI node, then the rule version would win and the UI node would be omitted.

     • Array - Child nodes will be added to the output in the order in which they are specified inside the DriveWorks UI (top to bottom). When Children are specified inside DriveWorks and also driven to the parent array element via a rule, both will be driven to the array. UI nodes first and rule based nodes appended to the end. Children can be of any data type and will also be subject to recursive application of these rules. When no value is specified, an array should always be added even if it is empty (i.e. property: [ ]).
     • Null - A JavaScript null value will be driven if there is no rule, a rule is present but evaluates to "null" (case insensitive and whitespace is trimmed automatically) or any whitespace string. Any other value will be treated as a string and cause a validation warning.

Schema Validation

Some of the more advanced JSON schema concepts are not currently enforceable within the DriveWorks interface, for example, a properties value may be defined as being constrained within a minimum and maximum numerical value.

In such a case, DriveWorks will not modify a rule result and will permit a number outside of the range to be driven.

At the end of generation, and after a JSON object has been generated, the generated JSON object is passed back into a validator for a final test.

This inspection will identify any discrepancies between the generated object and the given schema and when discrepancies are found, these will be reported as warnings in the Specification Report.

Case Sensitivity

JSON is case sensitive and therefore it's important to ensure that source schema accurately reflects the desired casing of the final output document. If changes are made to the schema after populating the document with nodes and rules, data loss may occur.

To Add a JSON Document

In DriveWorks Administrator open the Project the Document is to be added to and go to Stage4: Output Rules then Documents - Files

1. Click the Add button on the command bar.
2. Choose the JSON Document item from the Documents list in the Create Document wizard.
3. Enter a name for the Document in the field below the Document and Document Template list.
4. Click Next.
5. Browse to the JSON Document that will be used as the template.

Person Example

{
    "type": "object",
    "properties": {
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "birthday": { "type": "string", "format": "date" },
        "address": {
            "type": "object",
            "properties": {
                "street_address": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" },
                "country": { "type" : "string" }
            }
        }
    }
}
            

Billing/Shipping Address Example (schema reuse)

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "address": {
            "type": "object",
            "properties": {
                "street_address": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" }
            },
            "required": ["street_address", "city", "state"]
        }
    },
    "type": "object",
    "properties": {
        "billing_address": { "$ref": "#/definitions/address" },
        "shipping_address": { "$ref": "#/definitions/address" }
    }
}
            

Edit a JSON Document

When a Text Document is added the parameters that can be set will be shown in the Document Window.

Master File

This is the location to the Master File (Schema document) selected when creating the document.

Document Name

By default the rule applied to this parameter is:

<DocumentName>&DWSpecification&".json"

To change the default rule click the Build button at the end of the Document Name field.

If the Document is not required to be created for a Specification the rule must result in one of the following:

• Delete
• Suppress
• False
• <Delete>
• <Suppress>
• <False>

Examples

Document Path

By default there is no rule applied to this parameter. Therefore the resulting Document will be saved relative to the Specification Folder.

Please see Info: Where To Store DriveWorks Data for information on where to store the data associated to a DriveWorks implementation.

Examples

Hide From Document List

When this setting is enabled (by checking the box) the Document will be hidden from the Documents list in the Specification Explorer.

Minify Output

Checking this option will condense all carriage returns and tab characters onto single lines, in the created document.

For example, the JSON below:

[
  [
    "String3",
    "",
    "",
    [
      "JSONString1",
      "JSONString2",
      "JSONString3"
    ]
  ]
]
        

Will be minified to:

[["String3","","",["JSONString1","JSONString2","JSONString3"]]]
        

This setting can also be controlled with a rule.

1. Click the Build button at the end of the Minify Output field.
2. Build the rule to determine if the resulting JSON Document is to be minified. The rule must result in either:
   • True - the document will be minified
   • False - the document will not be minified

Nodes

When the Document is first added, no Nodes are captured.

To capture the Nodes to drive:

1. Select the Root { } node from the Node list.
2. Click Edit Selected from the command bar.
3. From the Edit Target dialog, select the top level nodes to add from the Target Schema list.

   

4. Click Add.
5. Click OK.
6. To add nodes that are children of the previously added nodes, select the <NodeName> {}, from the Node List.
7. Repeat steps 2 to 5 above.

Build Rules for Nodes

To build rules for the captured Nodes;

1. Select the Node(s) from the Nodes List.
2. Select the Node from the main window and click Build, from the command bar.

   Or

   Double Click the Node from the main window.