JSON format files are text files written in JavaScript Object Notation (JSON). JSON has become popular for interchange of data, including vector spatial data using GeoJSON format. Manifold can import and link JSON files. Manifold can also export tables to JSON files.
Current Manifold
builds have a limit of 2 GB per JSON or GeoJSON file. This limitation
will be removed in upcoming builds, allowing use of JSON and GeoJSON files
that exceed 2 GB. Note that GeoJSONL and JSONL files can be of any
size, so long as that any single line (any single object) is no larger
than 2 GB.
Tech Tip: If you have a choice, it is much better to use JSONL instead of JSON. JSONL has no real limit on the size of read and written data, it is significantly faster, with other benefits as well, all because the format is friendlier.
Manifold provides six different dataports for importing, linking, or exporting text files containing data in JSON formats:
GeoJSON - Spatial data consisting of simple geographic features and attributes. The Manifold GeoJSON dataport imports open standard GeoJSON files, including automatically reading TopoJSON when a GeoJSON file contains TopoJSON. Geometry collections within GeoJSON data are expanded automatically.
GeoJSON Servers - Web servers providing spatial data in GeoJSON format. Create a data source using the GeoJSON server dataport to link to data in GeoJSON format files provided by web URLs. The GeoJSON web dataport allows refreshing tables to re-read the latest data from the web. The GeoJSON server dataport is read-only.
GeoJSONL - GeoJSON format that uses newline-delimited JSON. Also known as GeoJSONSeq, line-oriented GeoJSON, GeoJSON Text Sequences, Line-delimited GeoJSON, and Newline-delimited GeoJSON.
JSON - Free form data utilizing JSON format. Top-level structures within JSON data that look like lists of records are imported as tables. Other top-level structures are imported as comments. Manifold can export to JSON as well.
JSON Servers - Web servers providing spatial data in generic JSON format. Create a data source using the JSON server dataport to link to data in generic JSON format files provided by web URLs. The JSON web dataport allows refreshing tables to re-read the latest data from the web. The JSON server dataport is read-only.
JSONL - Newline-delimited JSON, also known as JSON Lines.
The GeoJSON and JSON dataports, since GeoJSON is a well-specified standard, while a generic JSON file need not follow any standard for data organization. As a practical matter, JSON files are thus useful for interchanging tables in relatively calm use of JSON, such as arrays.
JSON files normally use a file name extension of .json. GeoJSON files normally use a file name extension of .geojson but also, occasionally, will use a file name extension of .json. When GeoJSON files use the .json extension that can cause confusion, since non-geo JSON files ending in .json are often used to convey non-spatial format, or to convey spatial format in tabular, not spatial form.
Importing GeoJSON files that end in .json using the JSON dataport results in a text table. No harm done, but it is better to import them directly as drawings by following the simple procedure given in the GeoJSON topic.
To import a JSON format file:
Choose File - Import from the main menu.
Navigate to the desired .json file
Double-click the file to import it.
Depending on the contents of the file, comments and/or tables will appear in the Project pane.
To import multiple JSON format files:
Choose File - Import from the main menu.
Navigate to the folder containing desired .json files.
Ctrl-click each desired file to highlight it.
Press the Import button.
Depending on the contents of the file, comments and/or tables will appear in the Project pane for each imported file.
The most efficient way to import a JSON file into a project is to use File - Import. If we like, we could use either File - Link or File - Create - New Data Source, to link the JSON file into the project, leaving the data resident in the JSON file. That is not recommended since JSON is a text format that is much slower than fast binary formats, and far slower than native Manifold project storage.
We will import a .json file that contains a list of customers. The example JSON file we use is artificial test data and is does not represent real names and email addresses.
Choose File - Import.
Navigate to the desired .json file and double-click it to import it. Manifold knows from the .json extension to use the JSON dataport to import.
The file imports as a table. Double-click the table to open it. It appears with gray background, indicating it is read-only, since it does not have an index, not something to expect in a JSON file.
We make the table read/write by adding an index. That is easy to do, a one-click operation: launch Edit-Schema and in the Schema dialog press the Add Identity button to add a key field and index to the table, and then press Save Changes to save changes to the table and to close the Schema dialog.
Given the habit of some authors to publish GeoJSON files using a .json file extension instead of a .geojson file extension, it is probably only a matter of time before we double-click on a .json file, which automatically imports it as a JSON file, when instead it is a GeoJSON file. It is easy to tell when that happens, and easy to fix.
Suppose we take the DistrictofColumbia.json file used in the Example: Import GeoJSON File topic, and instead of importing it as a GeoJSON file we just double-click it in the Import dialog to import it as a JSON file.
Instead of getting a drawing, we will get a table, usually called features, that when opened will be seen to contain for each record a geometry field full of JSON text that gives the coordinates for point, line or area objects. That is our immediate tip-off that we imported a GeoTIFF file as a JSON file. We can fix that by re-importing the file using the procedure given in the GeoJSON topic, choosing GEOJSON Files (*.geojson) for the type of import.
JSON files vary wildly - In the above example we imported a JSON file that used JSON in a relatively simple way, to store a table. If the file had only three records, we could open it in Notepad (JSON files are plain text files) and see:
[{"id":1,"first_name":"Hermina","last_name":"Stanworth","email":"hstanworth0@dailymotion.com","gender":"Female"},
{"id":2,"first_name":"Ellyn","last_name":"Wildash","email":"ewildash1@yellowbook.com","gender":"Female"},
{"id":3,"first_name":"Karna","last_name":"Collison","email":"kcollison2@accuweather.com","gender":"Female"}]
JSON files can, and sometimes do, structure data using arrangements that make little sense except to software written by the original authors. In such cases, Manifold will use all sensible means to extract data that looks like it should be a table from the JSON file, and toss all other top level objects into comments components.
File - Create - New Data Source
Example: Import GeoJSON File - Import vector footprints for all buildings in the District of Columbia, using a GeoJSON file published as open data by Microsoft.