WOLFRAM

Wolfram Language & System Documentation Center

UBJSON (.ubj)

Background & Context

    • MIME type: application/ubjson.
    • Data interchange binary format.
    • Supports full UBJSON syntax.
    • UBJSON identifies UBJSON objects with Wolfram Language associations.
    • UBJSON is an acronym derived from Universal Binary JSON.
    • Binary format with big-endian order for numeric values.
    • There is a one-to-one transformation between JSON and UBJSON.
    • UBJSON is specified at http://ubjson.org/.

Import & Export

  • Import["file.ubj"] imports a UBJSON file as a combination of nested lists and associations.
  • ImportString["string","UBJSON"] imports a UBJSON string of bytes.
  • Export["file",expr,"UBJSON"] exports a combination of nested lists and associations to a UBJSON file.
  • ExportString[expr,"UBJSON"] exports to a UBJSON string of bytes.
  • The "UBJSON" format identifies UBJSON objects with associations in the Wolfram Language.
  • "UBJSON" identifies UBJSON lists [e1,e2,…] with Wolfram Language lists {e1,e2,…}.
  • Single-character strings in the Wolfram Language are represented in UBJSON as characters. Multi-character strings in the Wolfram Language are represented as UBJSON strings.
  • Machine-precision integers are represented as the smallest UBJSON integer type they fit in.
  • Big integers are represented as a UBJSON string of digits.
  • Machine-precision numbers in the Wolfram Language are represented by the smallest compatible UBJSON float type.
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Summary"summary of the file
    "Rules"list of rules for all available elements

Options

  • Export options:
  • "ConversionFunction"Nonefunction to apply for additional conversions
    "ConversionRules"{}rules to apply to override or add conversions
  • The setting for "ConversionRules" is used to replace subexpressions before built-in conversions are performed.
  • The setting for "ConversionFunction" is applied to subexpressions for which no built-in conversion is defined.

Examples

Basic Examples  (7)

Export a List to the UBJSON format:

Wolfram Language code: bytes = ExportString[{1, 2, 3}, "UBJSON"];

Import as an expression:

Wolfram Language code: ImportString[bytes, "UBJSON"]

Export an Association to the UBJSON format:

Wolfram Language code: bytes = ExportString[<|"x" -> 1, "y" -> 2.5|>, "UBJSON"];

Import as an expression:

Wolfram Language code: ImportString[bytes, "UBJSON"]

Exporting an integer produces an output of variable size:

Wolfram Language code: ExportString[2 ^ 7 - 1, "UBJSON"]//StringLength
Wolfram Language code: ExportString[2 ^ 15 - 1, "UBJSON"]//StringLength
Wolfram Language code: ExportString[2 ^ 31 - 1, "UBJSON"]//StringLength
Wolfram Language code: ExportString[2 ^ 63 - 1, "UBJSON"]//StringLength

Exporting a big integer produces an output of size proportional to the number of digits:

Wolfram Language code: ListPlot[Table[ {exponent, StringLength[ExportString[10 ^ exponent, "UBJSON"]]}, {exponent, 20, 40, 2}]]

Exporting a ByteArray produces a compact, strongly typed, UBJSON array output:

Wolfram Language code: ExportString[ByteArray[Range[255]], "UBJSON"]//StringLength

Export the same data as a regular List:

Wolfram Language code: ExportString[Range[255], "UBJSON"]//StringLength

Exporting a string of one ASCII character produces a UBJSON character:

Wolfram Language code: ExportString["A", "UBJSON"]

Exporting non-ASCII characters produces a UBJSON string output:

Wolfram Language code: ExportString["", "UBJSON"]//StringLength

Exporting a string produces a UBJSON string:

Wolfram Language code: ExportString["hello", "UBJSON"]//StringLength

Use conversion rules to transform quantities to associations:

Wolfram Language code: data = ExportString[{Quantity["42.195", "Kilometers"], Quantity["21.097", "Kilometers"], Quantity["10", "Kilometers"]}, "UBJSON", "ConversionRules" -> {Quantity[magnitude_, unit_] :> <|"magnitude" -> magnitude, "unit" -> unit|>}];

Import as an expression:

Wolfram Language code: ImportString[data, "UBJSON"]