Working with JSON

This section describes how you can import JSON files into  Designer Cloud, convert them to tabular format, wrangle them, and then export them back in the same JSON format.

The basic workflow is described by way of example. In the example workflow, the JSON file must be imported into  Designer Cloud, a new column must be inserted into the JSON, and the resulting JSON must be exported in the same structure.

JSON Input and Output

Input: 

• It is easier to work with JSON in which each row of the file is a record. When a record spans multiple rows, additional steps are required in the application to render it into tabular format. The example uses multi-row JSON records.

Output:

• Designer Cloud can generate a JSON file as an output for your job. Characteristics of generated JSON files:
  
  • Newline-delimited: The end of each record is the \n character. If your downstream system is expecting comma-delineated records except for the last one, additional work is required outside of the application.
  • Non-nested: Each record in the generated file is flat. 
    • For multi-level JSON hierarchies, you can nest columns together and leave the top level as a set of columns in the data grid. However, on output, the second and lower hierarchies appear as quoted string values in the output. Additional cleanup is required outside of the application. 

Example

This example dataset contains information on books. In this case:

• The data is submitted as one attribute per row. A single JSON record spans many rows.
• The total number of books is three.
• The JSON data has two hierarchies.

"book": {
  "id": "bk101",
  "author": "Guy, Joe",
  "title": "Json Guide",
  "genre": "Computer",
  "price": "44.95",
  "publish_date": "2002-04-26",
  "characteristics": {
    "cover_color": "black",
    "paper_stock": "20",
    "paper_source": "new"
  },
  "description": "An in-depth look at creating applications."
},
"book": {
  "id": "bk102",
  "author": "Nelson, Rogers",
  "title": "When Doves Cry",
  "genre": "Biography",
  "price": "24.95",
  "publish_date": "2016-04-21",
  "characteristics": {
    "cover_color": "white",
    "paper_stock": "15",
    "paper_source": "recycled"
  },
  "description": "Biography of a prince."
},
"book": {
  "id": "bk103",
  "author": "Fitzgerald, F. Scott",
  "title": "The Great Gatsby",
  "genre": "Fiction",
  "price": "9.95",
  "publish_date": "1925-04-10",
  "characteristics": {
    "cover_color": "blue",
    "paper_stock": "20",
    "paper_source": "new"
  },
  "description": "Classic American novel."
}

JSON Workflow

1. Import the JSON file.

   NOTE: During import, you should deselect the Detect Structure option. You are likely to need to rebuild the initial parsing steps to consume the file properly. Details are provided later.

2. If needed, convert loose JSON to a single JSON record per row. 
3. Unnest the data into columns.
   1. Each level in the JSON hierarchy must be un-nested in a separate step.
4. When all of the JSON data is in tabular form, perform any  Wrangle transformations. 
5. If you need to retain the hierarchy, you must nest the lower levels of the JSON hierarchy back into their original form. Leave the top level un-nested.
   1. If it is ok to write out flat JSON records, you can export without nesting the data again.
6. Run the job, generating a JSON output. 

Step - Import the file 

1. Through the Import Data page, navigate and select your JSON file for import. 
2. When the file has been loaded, click Edit settings for the dataset card in the right panel. In the Import Settings dialog, deselect the Detect Structure checkbox.
3. Complete the rest of the import process. For more information, see Import Data Page. 
4. Add the JSON-based imported dataset to a flow and create a recipe for it. For more information, see Flow View Page.
5. Select the recipe, and click Edit Recipe.... 

Step - Convert to one JSON record per row

1. In the Transformer page, you should see your loosely formatted JSON in a single column. Each row contains a separate attribute, and a single record spans multiple rows.
2. Open the Recipe panel on the right side. The initial parsing steps for the data are displayed. For more information, see Initial Parsing Steps.
3. In Recipe panel, delete all steps except the first one.
4. The first one is a Break into rows transformation. This transformation can only appear in the first step of a recipe. 
5. Select the step, and click the Pencil icon to edit it.

6. In the Transform Builder, the Split on value is probably the \n character.

7. The above signals to the application to break up the data into individual rows on the newline (\n) character. This transformation then breaks up your loose JSON on every single attribute. You must modify the Split on value so that it captures only the first attribute of each JSON record. For the above dataset, the Split on value must be the following, noting the space after the colon:
   
   

   "book": 

8. Click Add to save the step again. 
9. The above dataset should now have four rows, with the first one an empty row. This empty row is caused by the insertion of the \n in front of the first reference to the above string. In the column histogram, select the black bar, which selects the empty row. In the Suggestions panel, locate the Delete rows suggest, and click Add. The row is removed.
10. You now have individual rows for each JSON record.

Step - Convert JSON to Object type

The next step involves converting your JSON records to a column of Object type values. The Object data type is a means of rendering records into key-value pairs. However, its structure is a little different from JSON. The following steps convert your JSON to an Object data type.

• For more information, see Object Data Type.

1. Since JSON uses character indentation to convey structure, you should remove these indentations if they appear in your dataset. For our two-layered example, you can use the following transformation:
   
   

   Transformation Name	Replace text or patterns
   Parameter: Column	column1
   Parameter: Find	/\n\s*"/
   Parameter: Replace with	\"
   Parameter: Match all occurrences	true

   1. In the above, the key term is the Find pattern, which is a regular expression:

      /\n\s*"/

   2. The two forward slashes at the ends define the pattern as a regular expression.
   3. The content in the middle matches on the pattern of a newline character, an arbitrary number of spaces, and a double quote.
   4. This pattern is replaced with just the double-quote, removing the preceding part of the pattern from the dataset.
   5. For more information on matching patterns, see Text Matching.
2. In standard JSON, a comma is used to demarcate the end of a line or a record, except for the last one in a set. 

   1. In the above example, the first two records have commas at the end of them. Here is a snippet of their ends:

      ... "description":"An in-depth look at creating applications."},
      ... "description":"Biography of a prince."},
      ... "description":"Classic American novel."}

   2. To convert these records to Object type, the commas at the end of the first two rows must be removed:
      

      Transformation Name	Replace text or patterns
      Parameter: Column	column1
      Parameter: Find	`\n\},\n{end}`
      Parameter: Replace with	}
      Parameter: Match all occurrences	true

      
      

      1. The above transformation is similar to the previous one. However, in this one, the Find pattern uses a  Pattern  to indicate that the pattern should only be matched at the end of a record:
         
         

         {end}

      2. This token in the pattern prevents it from matching if there are other instances of the pattern nested within the record.
      3. For more information, see Text Matching.

3. Individual records should look similar to the following:
   

   NOTE: Below, some values are too long for a single line. Single lines that overflow to additional lines are marked with a \. The backslash should not be included if the line is used as input.

   {"id": "bk101","author": "Guy, Joe","title": "Json Guide","genre": "Computer", \
   "price": "44.95","publish_date": "2002-04-26",{"cover_color": "black", \
   "paper_stock": "20","paper_source": "new"}, \
   "description": "An in-depth look at creating applications."}

4. These records are suitable for conversion to Object data type. 
5. To change the data type for the column, click the icon to the left of the column header. Select Object.
6. The column data type is changed to Object. The step to change data type is added to your recipe, too.
7. If the column histogram now displays some mismatched records. 
   1. Review those records to determine what is malformed.
   2. Delete the recipe step that changes the data type to Object.
   3. Make fixes as necessary.
   4. Switch back to Object data type. Iterate as needed until all records are valid when the column is converted to Object type.

Step - Unnest JSON records

The next step is to convert your JSON records to tabular format. 

1. In the Recipe panel, click New Step. 
2. In the Search panel, enter unnest object elements. 
3. Specify the following transformation. Substitute the Paths to elements values below with the top-level keys in your JSON records:
   
   

   Transformation Name	Unnest object elements
   Parameter: Column	column1
   Parameter: Path to elements1	id
   Parameter: Path to elements2	author
   Parameter: Path to elements3	title
   Parameter: Path to elements4	genre
   Parameter: Path to elements5	price
   Parameter: Path to elements6	publish_date
   Parameter: Path to elements7	description
   Parameter: Remove elements from original	true

   
   
   1. In the above, each Paths to elements entry specifies a key in the JSON record. The key's associated value becomes the value in the new column, which is given the same name as the key. 

   2. So, this step breaks out the key-value pairs for the specified keys into separate columns in the dataset. 

      Tip: You can choose to remove the original from the source or not. In deeper or wider JSON files, removing can help to identify what remains to be unnested.

4. Repeat the above process for the next level in the hierarchy. In the example, this step means unnesting the characteristics node:
   
   

   Transformation Name	Unnest object elements
   Parameter: Column	column1
   Parameter: Path to elements1	characteristics.cover_color
   Parameter: Path to elements2	characteristics.paper_stock
   Parameter: Path to elements3	characteristics.paper_source
   Parameter: Remove elements from original	true

5. You can now delete column1. From the column menu to the right of column1, select Delete.

6. You have now converted your JSON to tabular format.

   Tip: If the above set of steps needs to be applied to multiple files, you might consider stopping your work and returning to Flow View. Select this recipe and click Add New Recipe. If you add successive steps in another recipe, the first one can be used for doing initial processing of your JSON files, separate from any wrangling that you may do for individual files.

   Tip: The unnesting process may have moved some columns into positions that are different from their order in the original JSON. Use the Move command from the column menu to reposition your columns.

Step - Wrangle your dataset

Your JSON data is ready for wrangling. 

In the following example, the discount column is created. If the publication date is before 01/01/2000, then the discount is 0.1 (10%):

Continue adding steps until you have transformed your data as needed and are ready to run a job on it.

Step - Nest the JSON records

If a job is run using the recipe created so far on the example data, a newline-delimited JSON file that has no hierarchies in it can be generated by the application. However, the dataset is a two-level hierarchy, so the elements in the characteristics hierarchy are written out in the following manner:

"characteristics.cover_color":"black","characteristics.paper_stock":20,"characteristics.paper_source":"new",
"characteristics.cover_color":"white","characteristics.paper_stock":15,"characteristics.paper_source":"recycled",
"characteristics.cover_color":"blue","characteristics.paper_stock":20,"characteristics.paper_source":"new",

You can take one of two approaches:

1. Generate the JSON file with a flat hierarchy. Output looks like the above. Use an external tool to unnest the second and lower hierarchies appropriately.

2. Re-nest the lower hierarchies until have you have a single flat record, containing some Object type columns that hold the underlying hierarchies. When the re-nested JSON records are exported, secondary hierarchies appear as escaped string values. More details later.

If you are re-nesting the lower hierarchies, you can use the following approach. 

1. When you re-nest, you want to nest from the lowest to top tier of the hierarchy. 
2. In the example, the following columns should be nested together: characteristics.cover_color, characteristics.paper_stock, and characteristics.paper_source:
   
   

   Transformation Name	Nest columns into Objects
   Parameter: column1	characteristics.cover_color
   Parameter: column2	characteristics.paper_stock
   Parameter: column3	characteristics.paper_source
   Parameter: Nest columns to	Object
   Parameter: New column name	characteristics

3. In the generated characteristics column, you can remove the characteristics. from the key value:
   
   

   Transformation Name	Replace text or patterns
   Parameter: Column	characteristics
   Parameter: Find	`characteristics.`
   Parameter: Replace with	(empty)

4. Now, delete the three source columns:
   
   

   Transformation Name	Delete columns
   Parameter: column1	characteristics.cover_color
   Parameter: column2	characteristics.paper_stock
   Parameter: column3	characteristics.paper_source

5. Repeat the above steps for the next level of the hierarchy in your dataset. 

   NOTE: Do not nest the columns at the top level of the hierarchy.

Step - Generate JSON output

When you are ready, you can run the job. Create or modify a publishing action to generate a JSON file for output. See Run Job Page.

When the job completes, you can click the JSON link in the Output Destinations tab of the Job Details page to download your JSON file. See Job Details Page.

Step - Final Cleanup

Outside the application, you may need to do the following:

1. Since the JSON output is newline delimited, your downstream system may need you to add commas at the end of each record but the last one. 

2. If you have re-nested JSON hierarchies into your flat records, the exported JSON for secondary hierarchies appears as quoted strings, like the following:

   "characteristics":"{\"cover_color\":\"black\",\"paper_stock\":\"20\",\"paper_source\":\"new\"}",
   "characteristics":"{\"cover_color\":\"white\",\"paper_stock\":\"15\",\"paper_source\":\"recycled\"}",
   "characteristics":"{\"cover_color\":\"blue\",\"paper_stock\":\"20\",\"paper_source\":\"new\"}",

   The quoted strings can be fixed by simple search and replace.