jsonImportOptions

Import options object for JSON files

Since R2026a

Description

You can specify how MATLAB^® imports structured, tabular data from JSON files by using a JSONImportOptions object. Customize the data import process, such as how to handle errors and missing data, by setting properties of the object. To import data from a JSON file using your customized options, use the readtable or readtimetable function with the filename and the JSONImportOptions object as input arguments.

Creation

You can create a JSONImportOptions object using either of these two functions:

• Use jsonImportOptions (described here) when you want to define the import properties based on your import requirements.

• Use detectImportOptions when you want to detect and populate the import properties based on the contents of a specified JSON file.

Syntax

opts = jsonImportOptions

opts = jsonImportOptions(NumVariables=numVars)

opts = jsonImportOptions(___,PropertyName=Value)

Description

opts = jsonImportOptions creates a JSONImportOptions object for data with one variable.

opts = jsonImportOptions(NumVariables=numVars) creates a JSONImportOptions object for data with the specified number of variables.

opts = jsonImportOptions(___,PropertyName=Value) sets properties for the JSONImportOptions object using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, you can specify the variables and rows of the JSON file data to import.

Input Arguments

numVars — Number of variables

positive integer scalar

Number of variables, specified as a positive integer scalar. Use this argument to specify the expected number of variables to import.

Output Arguments

opts — JSON file import options

JSONImportOptions object

JSON file import options, returned as a JSONImportOptions object.

Properties

Variable Properties

VariableNames — Variable names

string array | character vector | cell array of character vectors

Variable names, specified as a string array, character vector, or cell array of character vectors. The VariableNames property contains the names of the variables to import. If you use the detectImportOptions function to create the import options object, you can see the detected variable names by querying this property using opts.VariableNames.

If the data contains N variables, but you do not specify variable names, then the VariableNames property contains ["Var1","Var2",...,"VarN"].

To support invalid MATLAB identifiers as variable names, such as variable names that include spaces or non-ASCII characters, set the VariableNamingRule property to "preserve".

Example: opts = jsonImportOptions(VariableNames=["Length","Width","Depth"]) creates a JSONImportOptions object for data with the specified variable names.

Example: opts.VariableNames(3) = "Height" changes the name of the third variable to Height.

VariableNamingRule — Rule for variable names

"preserve" (default) | "modify"

Rule for variable names, specified as one of these values:

• "preserve" — Preserve variable names that are not valid MATLAB identifiers, such as variable names that include spaces or non-ASCII characters.

• "modify" — Convert invalid variable names (as determined by the isvarname function) to valid MATLAB identifiers.

Variable and row names do not have to be valid MATLAB identifiers. They can include any characters, including spaces and non-ASCII characters. Also, they can start with any character, not just letters.

Variable names are not refreshed when you change VariableNamingRule from "modify" to "preserve".

VariableTypes — Data types of variables

string array | character vector | cell array of character vectors

Data types of variables, specified as a string array, character vector, or cell array of character vectors containing valid data type names. The VariableTypes property designates the data types of the variables to import. If you use the detectImportOptions function to create the import options object, you can use the detected variable data types by querying this property using opts.VariableTypes.

To update the VariableTypes property, see the setvartype function. For example, opts = setvartype(opts,"Height","double") changes the data type of the variable Height to double.

Example: opts = jsonImportOptions(VariableNames=["Length","Width","Height"],VariableTypes=["double","double","single"])

SelectedVariableNames — Subset of variables to import

string array | character vector | cell array of character vectors | array of numeric indices

Subset of variables to import, specified as a string array, character vector, cell array of character vectors, or array of numeric indices. Use the SelectedVariableNames property to import only the variables of interest.

SelectedVariableNames must be a subset of names contained in the VariableNames property. By default, SelectedVariableNames contains all the variable names from the VariableNames property, which means that all variables are imported.

To support invalid MATLAB identifiers as variable names, such as variable names that include spaces or non-ASCII characters, set the VariableNamingRule property to "preserve".

Example: opts.SelectedVariableNames = ["Width","Height"] selects only two variables, Width and Height, for the import operation.

Example: opts.SelectedVariableNames = [1 5] selects only two variables, the first variable and the fifth variable, for the import operation.

VariableOptions — Type-specific variable import options

array of VariableImportOptions objects

Type-specific variable import options, specified as an array of VariableImportOptions objects. The array contains an object corresponding to each variable specified in the VariableNames property. Each object in the array contains properties that support the importing of data with a specific data type.

VariableImportOptions objects support these data types: numeric, text, logical, datetime, and categorical.

To query the current (or detected) options for a variable, use the getvaropts function. For example, getvaropts(opts,"Height") returns the VariableImportOptions object for the Height variable.

To set and customize options for a variable, use the setvaropts function. For example, opts = setvaropts(opts,"Height",FillValue=0) sets the FillValue property for the variable Height to 0.

VariableSelectors — JSON Pointers for variables to read

string array | character vector | cell array of character vectors

JSON Pointers for variables to read, specified as a string array, character vector, or cell array of character vectors that the reading function uses to select table variables. You must specify VariableSelectors as valid RFC 6901 JSON Pointers. For more information, see the IETF definition of JSON Pointer.

An asterisk (*) in a VariableSelectors value indicates an entire array at that corresponding level is selected.

To read keys as variables, include the string "Keys" with VariableSelectors. For example, VariableSelectors=["Keys" "/ID" "/Name/FirstName"].

An empty string ("") refers to the whole JSON file.

Example: opts.VariableSelectors = "/enginetemp"

Example: opts.VariableSelectors = ["/enginetemp1","/enginetemp2"]

Table Properties

RowNamesSelector — JSON Pointer for rows to read

string scalar | character vector

JSON Pointer for rows to read, specified as a string scalar or character vector that the reading function uses to select the names of the table rows. You must specify RowNamesSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

Example: opts.RowNamesSelector = "/engineID"

TableSelector — JSON Pointer for table to read

string scalar | character vector

JSON Pointer for the table to read, specified as a string scalar or character vector that the reading function uses to select the output table data. You must specify TableSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

An empty string ("") refers to the whole JSON file.

Example: opts.TableSelector = "/engineID"

VariableDescriptionsSelector — JSON Pointer for variable descriptions

string scalar | character vector

JSON Pointer for variable descriptions, specified as a string scalar or character vector that the reading function uses to select the table variable descriptions. You must specify VariableDescriptionsSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

Example: opts.VariableDescriptionsSelector = "/statuses/metadata"

VariableUnitsSelector — JSON Pointer for variable units

string scalar | character vector

JSON Pointer for variable units, specified as a string scalar or character vector that the reading function uses to select the table variable units. You must specify VariableUnitsSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

Example: opts.VariableUnitsSelector = "/statuses/metadata/units"

Replacement Rules

ImportErrorRule — Rule for import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Rule for import errors, specified as one of the values in this table. An import error occurs when detectImportOptions or jsonImportOptions cannot convert a text element to the expected data type.

Import Error Rule	Behavior
"fill"	Replace the data where the error occurred with the contents of the FillValue property. You can set the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting the FillValue property, see setvaropts.
"error"	Display an error message and cancel the import operation.
"omitrow"	Omit rows where errors occur.
"omitvar"	Omit variables where errors occur.

MissingRule — Rule for missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Rule for missing data, specified as one of the values in this table. Data is considered missing if an expected JSON node does not exist.

Missing Rule	Behavior
"fill"	Replace missing data with the contents of the FillValue property. You can set the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting the FillValue property, see setvaropts.
"error"	Display an error message and cancel the import operation.
"omitrow"	Omit rows that contain missing data.
"omitvar"	Omit variables that contain missing data.

RepeatedNodeRule — Rule for variables containing arrays

"addcol" (default) | "ignore" | "error"

Rule for variables containing arrays, specified as one of the values in this table. This rule applies when the VariableSelectors property contains a JSON Pointer that points to an array. The array entries are considered repeated nodes.

Repeated Node Rule	Behavior
"addcol"	Add columns for the repeated nodes (array entries) under the variable header in the table. "addcol" does not create a separate variable in the table for the repeated node (for each array entry).
"ignore"	Skip the repeated nodes.
"error"	Display an error message and cancel the import operation.

JSON Parsing

AllowComments — Allow comments

true or 1 (default) | false or 0

Allow comments in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Comments do not cause an error during import. Comments in the file are not considered data and are not read into MATLAB. Comments can start with "//" for single-line comments or start with "/*" and end with "*/" for multi-line comments.

• Numeric or logical 0 (false) – Comments cause an error during import.

AllowInfAndNaN — Read Inf and NaN values

true or 1 (default) | false or 0

Read Inf and NaN values in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Inf and NaN values (including Infinity, -Inf, and -Infinity) are read into MATLAB.

• Numeric or logical 0 (false) – Inf and NaN values cause an error during import.

AllowTrailingCommas — Read trailing commas

true or 1 (default) | false or 0

Read trailing commas in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Trailing commas after a JSON array or JSON object do not cause an error during import.

• Numeric or logical 0 (false) – Trailing commas cause an error during import.

Examples

Import Subset of JSON File Using Import Options

Import a subset of a JSON file by creating a JSONImportOptions object, specifying the variables to import, and then reading the data. For example, you can import specific variables of the sample students.json file, which contains this content.

type students.json

[
    {
        "ID": "S11305",
        "Name": {
            "FirstName": "Priya",
            "LastName": "Thompson"
        },
        "Age": 18.0,
        "Year": "Freshman",
        "Address": {
            "Street": "591 Spring Lane",
            "City": "Natick",
            "State": "MA"
        },
        "Major": "Computer Science",
        "Minor": "English Literature"
    },
    {
        "ID": "S23451",
        "Name": {
            "FirstName": "Conor",
            "LastName": "Cole"
        },
        "Age": 18.0,
        "Year": "Freshman",
        "Address": {
            "Street": "4641 Pearl Street",
            "City": "San Francisco",
            "State": "CA"
        },
        "Major": "Microbiology",
        "Minor": "Public Health"
    },
    {
        "ID": "S119323",
        "Name": {
            "FirstName": "Morgan",
            "LastName": "Yang"
        },
        "Age": 21.0,
        "Year": "Senior",
        "Address": {
            "Street": "30 Highland Road",
            "City": "Detroit",
            "State": "MI"
        },
        "Major": "Political Science"
    }
] 

Import just the FirstName variable from the JSON file into a table. First, create the JSONImportOptions object and specify the variable to import using the VariableSelectors and TableSelector name-value argument. Then, read the data as a table.

opts = jsonImportOptions(VariableSelectors="/Name/FirstName",TableSelector="");
T = readtable("students.json",opts)

T=3×1 table
       Var1   
    __________

    {'Priya' }
    {'Conor' }
    {'Morgan'}

Tips

• JSON Pointers are zero-based. For more information, see the IETF definition of JSON Pointer.

Version History

Introduced in R2026a