*! version 0.0.7 27APR2017

I/O operations with JSON Data

help for jsonio

jsonio -- A Stata JSON Serializer/Deserializer built on
the Jackson Java library. For the most up to date version of this program, visit
Stata JSON on Github

Description

jsonio provides a simple user interface to serialize/deserialize JSON data.
When serializing the data in memory, jsonio preserves as much of the meta data as possible
(e.g., variable/value labels, etc...). When deserializing JSON, users currently have
two options available to load the data using either the key-value interface
or flattening the payload into a single row vector with the row-value
interface. Additionally, users are able to use simple string expressions to return a subset
of the data in both of these interfaces.

Syntax

jsonio kv|rv|out
[varlist] [if] [in] , [ elements(string)
noURL filenm(string)
obid(real) metaprint(string)
what(string) stubname(string)]

Subcommands

kv is a subcommand for jsonio that is used to
load data from the JSON file into the active dataset as a key/value pair.
This method defines two variables in the dataset - key and value. If the type of each
datum is not constant across all elements the values will be loaded as a string.
However, if the values are of a single type, they will be loaded into the dataset with
the appropriate type casting applied.

rv is a subcommand for jsonio that is used to load
the JSON data into the data set in memory as a single row vector. Unlike the
key/value interface, all values are automatically cast to the
correct type for you. While the key-value interface stores the generation string in
a single variable (key), this is not possible with this interface. Instead, each
of the datum is loaded as a variable with the name specified by stubname
and an ID/Iterator value appended as a suffix. Additionally, the generation string
is stored as the variable label for the variable. Unless a user passes
an observation ID value, this method will write the data to the first row only. The
benefit, however, is that it automatically joins the data to the appropriate observation
if you are looping over observations to make calls to an API or to read a sequence of JSON
data from files.

out is a subcommand used to serialize the data set currently
in memory to a JSON file.

Options

elements this option provides a method that can be used to query
specific elements from the JSON data. In the process of flattening the JSON data,
the names of elements are modified to include their full lineage (e.g., show all of
the parent nodes up to the root). The naming convention used for this purpose is
similar to *nix-based file systems where the "/" character by itself indicates the
root level of the data. When multiple objects are included in the same JSON data,
the branches/nodes can be identified by appending '_#' to the name, where the number
indicates the order in which the node appeared in the data.

terminal nodes typically will not include any modification, since the
generation string up to that point will be capable of uniquely identifying the
data element. However, when the terminal node is an element from an Array object,
you can identify distinct elements using the name 'element_#'. This only applies
to cases where the terminal nodes are elements from an array.

For example, the Google Directions API may include specific way points
in the JSON Payload like:

{

"geocoded_waypoints" : [

{

"geocoder_status" : "OK",

"place_id" : "ChIJGzE9DS1l44kRoOhiASS_fHg",

"types" : [ "locality", "political" ]

},

{

"geocoder_status" : "OK",

"place_id" : "ChIJGwVKWe5w44kRcr4b9E25-Go",

"types" : [ "neighborhood", "political" ]

},

{

"geocoder_status" : "OK",

"place_id" : "ChIJy1hS39qd44kRzRM2FsiFNoU",

"types" : [ "locality", "political" ]

},

{

"geocoder_status" : "OK",

"place_id" : "ChIJ9SKkJkCa44kRkKR4K5p3zlg",

"types" : [ "locality", "political" ]

}

]

}

To retrieve the first of the two highlighted elements from the example
above, you would pass "/geocoder_status_3/types/element_1" and the value that
would be returned would be "locality".

nourl because the program can handle data from files or
API calls/requests, you need to specify the source type of the data. If the
option is not specified, the program will assume the data are to be retrieved
from a request to the URL passed to it. If the data are stored on a file
system, you can use this option to make the program read the data from a
file instead of a URL.

filenm this parameter serves two purposes. For the
key-value and row-value modes, this specifies the location of the JSON to
ingest. If the JSON is stored in a file, be sure to use the nourl
option. If the JSON is from a webservice/URL, place the URL in this
parameter and do not set the nourl option. For the out mode, this
specified the location where the resulting JSON object will be saved. If this
parameter is not used, the resulting JSON object
will be printed to the Stata console.

obid has two uses depending on the interface. If you are
serializing data currently loaded in memory, this option will cause the
program to convert only that observation to a JSON object. If you are using
the row-value interface to load JSON data, this indicates the observation
where the data should be stored.

metaprint[("varnames", "varlabels", "labelnames", "vallabs")]
an optional argument used to serialize metadata from the Stata dataset to JSON
objects. The table below defines what each argument returns.

Argument Result

varnames Will serialize the variable names as a JSON object.
varlabels Will serialize variable labels as a JSON object.
labelnames Will serialize value label names as a JSON object
vallabs Will serialize value labels as a JSON object

what is an argument used to define what will be serialized.
The acceptable parameter values are data and record. Passing a
value of data to this argument will trigger the program to serialize the
entire dataset. Passing a value of record to this argument will serialize
a single record from the dataset. Passing a value of all to this
argument will serialize all of the metadata and the data set into a single
JSON object. If this argument is empty and the metaprint argument has a
valid value, the metaprint argument will define what to serialize.

stubname is used to define the base to use when
constructing variable names in row-value mode. If unspecified, the default
value "jsonvar" will be used. This will result in variable names of the
form:

stubname#

where the value of # indicates the traversal order of the data
(or of the queried subset of the data).

Examples

Serialize the last record of the auto dataset

sysuse auto, clear

jsonio out, what(record) obid(74)

Serialize the auto dataset

sysuse auto, clear

jsonio out, what(data)

jsonio out, what(all)

Serialize the auto dataset to a file

sysuse auto, clear

jsonio out, what(data) file(autoDTA.json)

jsonio out, what(all) file(autoDTA-withMetaData.json)

Serialize the auto dataset metadata

sysuse auto, clear

jsonio out, metaprint(varnames)

jsonio out, metaprint(varlabels)

jsonio out, metaprint(labelnames)

jsonio out, metaprint(vallabs)

Additional examples are available at http://github.com/wbuchanan/StataJSON

Author

William R. Buchanan, Ph.D.

Director, Office of Data, Research, & Accountability

Fayette County Public Schools

Billy.Buchanan at fayette [dot] kyschools [dot] us