JSON, XML and Web Access

Rules of thumb: use jsondecode when you already hold the text (a web response, a string in a script); use readstruct or readtable when the data is in a file and you want MATLAB to guess the types; use the web* functions for simple REST calls and the matlab.net.http classes only when those cannot express the request.

value = jsondecode(txt) parses JSON text given as a character vector or string scalar. The documentation states the rule that governs everything else: JSON supports fewer data types than MATLAB, so jsondecode converts each JSON type to the MATLAB type in this table.

Three consequences follow, and they are the source of most surprises. First, the shape is not what the JSON looks like: a JSON array of numbers becomes a column vector (N-by-1), and an array of arrays becomes a matrix whose rows are the inner arrays. Second, numbers are always double and strings are always character vectors, even though string arrays are the modern text type (see Strings and Character Arrays); convert with string(...) afterwards. Third, the same JSON key can decode to different types depending on its neighbours: an array of objects with identical fields is a structure array you index with s(2).id, while one object with an extra field turns the whole result into a cell array you index with s{2}.id.

The following script was run in Octave 11.3.0. It decodes one object that contains most of the types in the table, and it shows the class and size of each field.

Octave 11.3.0 output (MATLAB prints the same classes and sizes according to the table above):

Read it against the table. v is 3-by-1, the null inside the numeric array became NaN, the lone null became an empty array (size 0-by-0), the mixed array became a cell array, the objects with equal fields became a 2-by-1 structure array, and the objects with different fields became a 2-by-1 cell array.

Field names. JSON allows any text as a key; MATLAB structure fields must be valid names. jsondecode passes every name through matlab.lang.makeValidName, so a key such as 1st reading is changed. In Octave 11.3.0 the keys 1st reading and a-b became the fields x1stReading and a_b; the MATLAB documentation says the same function is used. The documentation draws the consequence in its limitations: if you decode and then encode a value, MATLAB does not guarantee that the result is identical to the original text, and altered field names are one reason.

Source: MATLAB documentation: jsondecode

txt = jsonencode(data) returns a character vector in JSON format, and txt = jsonencode(data,Name=Value) accepts two name-value arguments:

The mapping of the documentation, restricted to the types you meet most often:

Not supported: complex numbers and sparse arrays, hidden properties, and recursive structures such as graphics objects that hold references to their parents and children. Round trips lose information: JSON does not distinguish double from int32, so an int32 encoded and decoded comes back as double, and a 1-by-N vector comes back as N-by-1. Text escapes follow the documentation tips: use newline to produce \n, pass strings through sprintf for tabs, and a double quote inside the text is escaped with a backslash.

These cases were run in Octave 11.3.0:

Octave 11.3.0 output:

A column vector encodes like a row vector ([1,2,3]), which is why shape is lost; the round trip of the int32 vector returns a double column. The MATLAB documentation writes the name-value pairs as PrettyPrint=true; Octave 11.3.0 accepted the comma form used above.

A scalar object as a one-element array. A structure encodes as an object, but some services expect an array even for one record. Put the structure in a cell array with {}, which the documentation recommends for this case. Octave 11.3.0 output of the following:

Records or columns? A structure array (or a table) encodes as an array of records, [{"time":...,"sensor":"T1"},...], which is the shape most services use. A scalar structure whose fields are vectors encodes as columns, {"sensor":["T1","T2"],"temperature":[21.4,22.9]}, which is compact but gives the reader the work of zipping the columns.

Source: MATLAB documentation: jsonencode

The heatflow scenario (The heatflow scenario) keeps its settings in data/plate.json. The script below writes a file, reads it back, changes two values, adds a third sensor and writes the result. It uses only the low-level file functions (see Low-Level File I/O and the File System) plus jsondecode and jsonencode, and was run in Octave 11.3.0 on a temporary folder. In MATLAB you can also replace the reading with readstruct, as the next section shows.

Octave 11.3.0 output (the number 1.2e-5 is written by Octave as 0.000012; MATLAB may format it differently):

Source: MATLAB documentation: jsondecode, MATLAB documentation: jsonencode, MATLAB documentation: fileread

The sensors array is a structure array in memory, so adding a third element is an assignment to plate.sensors(3), and jsonencode turns it back into an array of three objects. Note that jsondecode does not validate anything: a misspelt key (widht) simply becomes another field. Check the fields you need with isfield, or with the validation tools of Argument Validation, before the simulation uses them.

Invalid JSON. jsondecode stops with an error on text that is not valid JSON; the same script, run on {"a":1,} (a trailing comma), reached the catch block in Octave 11.3.0. The wording and identifier of the MATLAB error are not shown on the reference page, so catch it with a general try/catch and report ME.message (see Errors, Warnings and Exceptions); the message varies by release.

S = readstruct(filename) creates a structure array from a file that contains well-formed XML or JSON, and detects the data types of the contents. S = readstruct(filename,Name=Value) takes options such as FileType. The file type comes from the extension (.xml, or .json since R2023b), or from FileType="xml" or FileType="json" when the extension is something else, such as .info or .txt. The filename may be a path, an http:// or https:// URL, or a remote location (Amazon S3, Azure Blob Storage, HDFS); compressed .zip, .gz and .tar files are accepted since R2025a.

The documentation’s JSON example, music.json, has an object with nested objects and an array of objects. Its result shows how the mapping differs from jsondecode: the top-level result is always a structure, and arrays of objects whose elements have different keys become a uniform structure array with every key present in the type, where the keys missing from an element are filled with missing.

Not run here (the example of the reference page; the display is copied from it). The difference from jsondecode is practical: with readstruct you can write S.Ensemble.Instrumentation(2).Pianotype and get a string or missing, whereas jsondecode returns a cell array of structures with different fields that you must test element by element. The price is that readstruct needs a file or URL, not text in memory, and returns text as string values, as the displays of the reference page show.

JSON parsing options (R2023b). ParsingMode="strict" makes the parser follow the JSON standard exactly, and AllowTrailingCommas=true tolerates a comma after the last element. The documentation’s example reads music.json, which has trailing commas, with both: S = readstruct("music.json",ParsingMode="strict",AllowTrailingCommas=true). Other options select part of the file: StructSelector takes an XPath expression for XML, and RegisteredNamespaces registers a prefix for a namespace.

XML mapping. Elements become fields, repeated sibling elements become a structure array, an attribute is a field of its element, and the text of an element that also has attributes or children is stored in a field named Text. The reference page shows that <Instrument type="wind">Trumpet</Instrument> becomes a structure with the fields type and Text. The suffix that marks an attribute can be set with AttributeSuffix.

Tables (R2026a). readtable reads files with the extension .json since R2026a and, by default, creates one table variable for each object key it detects, named after the key. The documentation’s example reads only the street of each student from a file that holds an array of objects with nested address objects: detectImportOptions creates a JSONImportOptions object, and its VariableSelectors name-value argument takes a JSON Pointer (a path such as /Address/Street) to the keys that become variables.

Not run here (the example of the readtable reference page). For the thermocouple log, the same mechanism applies to a JSON file with one object per reading, [{"Time":"...","SensorID":"S1","Temperature":21.4},...]. Writing is documented for writetable: the extension .json selects JSON, FileType, PrettyPrint and PreserveInfAndNaN apply, and writetable lists "Write JSON files" in R2026a.

Timetables (R2026a). readtimetable and writetimetable gained JSON in the same release: readtimetable recognises the .json extension (or FileType="json" for another extension) and reads the data as a timetable, and the version history of writetimetable lists "Write JSON files" in R2026a. As with other formats, readtimetable takes the row times from the first datetime or duration variable unless RowTimes names another, so the thermocouple log written as one object per reading becomes the timetable used on Timetables.

Dictionaries (R2024b). d = readdictionary(filename) reads a JSON file whose content is one object of keys and values and creates a dictionary (see Dictionaries and containers.Map). With the documentation’s citytemps.json ({"Boston": 55, "New York": 62, ...}) the result is a dictionary (string ⟼ double) with five entries. When the values have different types, as in msginfo.json, the dictionary uses the type cell for its values and each value is wrapped in a cell. A null becomes missing. The name-value arguments include FileType, DateLocale, ValueType (for example "string" to import all values as strings), DictionaryNodeName (start at the first node with that name) and DictionarySelector (a JSON Pointer to the starting element). writedictionary is the inverse; the supported-formats table lists both.

Not run here; the file is an example in the style of the documentation’s citytemps.json, and the display is what the reference page shows for that file.

Sources: MATLAB documentation: readtable, MATLAB documentation: writetable, MATLAB documentation: readtimetable, MATLAB documentation: writetimetable, MATLAB documentation: readdictionary, MATLAB documentation: Supported File Formats for Import and Export

DOMnode = xmlread(filename) parses an XML file and returns a Document Object Model node, a tree you walk with getElementsByTagName, getChildNodes and similar methods. It is the right tool when the structure of the document matters (mixed content, comments, namespaces), and the wrong one for plain data, where readstruct or readtable give you MATLAB types directly. The reference page includes a parsing function, parseXML, that converts the tree into a structure array with the fields Name, Attributes, Data and Children. The matching writer is xmlwrite. In new code, prefer readstruct, readtable and writestruct.

Which engine builds the tree. For most of its history xmlread returned a Java DOM (the Java API for XML Processing, JAXP), so it needed MATLAB’s Java virtual machine. In R2026b it uses the MATLAB API for XML Processing (MAXP, the matlab.io.xml.dom classes) by default, and XMLEngine="jaxp" restores the Java DOM. The two engines return objects with different methods, so older code that calls Java org.w3c.dom helpers may need rewriting, as the reference page warns. xmlwrite accepts MAXP nodes since R2026a; before that it took only a JAXP node. Anything that still produces a Java DOM, such as XMLEngine="jaxp", a node built with com.mathworks.xml.XMLUtils or webread with ContentType="xmldom", needs a Java runtime, which R2026b does not install with MATLAB: install one with the MATLAB Support for OpenJDK add-on and select it with jenv, and check usejava("jvm") first. readstruct and writestruct return and take MATLAB structures and need no Java DOM.

Sources: MATLAB documentation: xmlread, MATLAB documentation: xmlwrite, MATLAB Support for OpenJDK

data = webread(url) reads content from a web service and converts it to a MATLAB type according to the content type of the response. Only http and https are supported. Query parameters are given as name-value pairs after the URL, data = webread(url,"firstName","John","lastName","Smith"), and the function builds the query string, encodes the special characters and appends it to the URL. A weboptions object adds the other request options, and the output type can be forced with its ContentType property:

The reference page notes that webread also supports HTTP POST (set RequestMethod to "post"), but it puts its queries in the URL, and for POST it only supports the application/x-www-form-urlencoded media type; use webwrite to send a body. webread does not examine the document to find its encoding: if the text is garbled, set CharacterEncoding in weboptions (for example "UTF-8").

The following request fetches the latest temperature readings from a heatflow data service. The address is a placeholder, HEATFLOW_API_KEY is read from the environment (see Secrets and Protecting Code), and nothing was sent while writing this page.

Not run here (placeholder address; no network access was used). The expression "Bearer " + key builds the header value; the two-column string array is the HeaderFields format of the documentation. If the service answers with something other than JSON the call fails or returns another type, so name the type you expect with ContentType and handle a failure:

Not run here. Catch the failure and report ME.message; the identifiers and messages for HTTP status codes and timeouts are not listed on the webread reference page and vary by release, so do not match on them.

response = webwrite(url,PostName1,PostValue1,...) form-encodes the pairs in the body of an HTTP POST request. response = webwrite(url,data) posts data and weboptions controls the media type through MediaType. The documented rules are:

To post one record as a JSON array, wrap it in braces, webwrite(url,{record},options), for the reason given in the jsonencode section above. The PUT, PATCH and DELETE methods are chosen with the RequestMethod property of weboptions.

Not run here (placeholder address; no network access). The reading is wrapped in braces so that the service receives an array of one object. KeyName and KeyValue add the key to the request header; the key comes from the environment, not from the source file.

outfilename = websave(filename,url) saves the response to a file and returns its full path. It saves the content as it is and ignores ContentType and ContentReader, so it is the choice for images, archives and large files, and for keeping the raw JSON before decoding it. The documentation’s pattern for JSON is to save, then read with fileread and jsondecode:

Not run here. Saving first is also a good habit for reproducibility: the file is the record of what the service answered at that moment.

Sources: MATLAB documentation: webwrite, MATLAB documentation: websave

The documentation says directly that some interactions with a web service are more complex than the webread, webwrite and websave functions can express. The HTTP interface provides classes for messages, header fields and other entities defined in the IETF standards, and its sections cover sending and receiving messages with redirection and digest authentication, data type conversion, cookies, progress monitors, streaming consumers and providers, multipart form messages and manual redirects. Only HTTP 1.1 is supported by this interface and by the web* functions.

The building blocks of a request are matlab.net.http.RequestMessage (its properties are RequestLine, Method, Header and Body, and send transmits it), matlab.net.http.MessageBody, the header field classes of the matlab.net.http.field namespace such as ContentTypeField and AcceptField, matlab.net.http.MediaType, matlab.net.http.RequestMethod and matlab.net.URI. The reference page of RequestMessage builds a message without sending it, and the pattern is:

Not run here, and send is commented out on purpose: no request was made. The first four lines follow the documentation’s example; the address in the last line is a placeholder. Reach for this interface for custom headers that weboptions cannot express, for streaming a large response, for uploading multipart forms or for reading status codes and response headers; for everything else, webread is shorter.

Sources: MATLAB documentation: Call Web Services from MATLAB Using HTTP, MATLAB documentation: matlab.net.http.RequestMessage, MATLAB documentation: Web Services with MATLAB

Older books fetch web pages with urlread. It still exists, but its reference page marks it as not recommended: for http and https use webread or webwrite. Before R2016b there was no JSON support in base MATLAB, and books of that period describe File Exchange parsers or hand-written regexp loops; jsondecode and jsonencode replace them, with a fixed type mapping. XML in older books means xmlread and a recursive walk of the DOM, or File Exchange helpers; readstruct (XML R2020b, JSON R2023b), readtable for XML (R2021a) and for JSON (R2026a) and readdictionary (R2024b) are newer than any such book. The web* functions also changed: R2025a allows secretID objects as weboptions credentials, so tutorials that put Username and Password in plain text no longer describe best practice. Older code that calls webread with Name, Value pairs in weboptions still works; since R2021a the Name=Value form is preferred.