SRFI 180: JSON
Abstract
This library describes a JavaScript Object Notation (JSON) parser and printer. It supports JSON that may be bigger than memory.
For more information see: SRFI 180: JSON
Rationale
JSON is a de facto industry standard for data exchange.
For best interoperability, the sample implementation is based on RFC 8259, and the tests are based on JSONTestSuite.
The mapping between JSON types and Scheme objects is not trivial because a given mapping might not be the best for every situation. That is the reason why this library makes public the procedure json-fold, inspired by Oleg Kiselyov's foldts.
Specification
(json-error? obj)
Returns #t if OBJ is an error object that is specific to this library.
(json-error-reason obj)
Return a string explaining the reason for the error. This should be human-readable.
(json-null? obj)
Return #t if OBJ is the Scheme symbol 'null, which represents the JSON null in Scheme. In all other cases, return #f.
json-nesting-depth-limit
Parameter holding a number that represents the maximum nesting depth of JSON text that can be read by json-generator, json-fold, and json-read. If the value returned by this parameter is reached, the implementation must raise an error that satisfies json-error?.
The default value of json-nesting-depth-limit is +inf.0.
A proper value should be set on a per-application basis to mitigate the risks of denial-of-service attacks.
json-number-of-character-limit
Parameter holding a number that represents the maximum number of characters for a given JSON text that can be read by json-generator, json-fold, and json-read. If the value returned by this parameter is reached, the implementation must raise an error that satisfies json-error?.
The default value of json-number-of-character-limit is +inf.0.
A proper value should be set on a per-application basis to mitigate the risks of denial-of-service attacks.
(json-generator [port-or-generator])
Streaming event-based JSON reader. PORT-OR-GENERATOR default value is the value returned by current-input-port. It must be a textual input port or a generator of characters. json-generator returns a generator of Scheme objects, each of which must be one of:
- 'array-start symbol denoting that an array should be constructed.
- 'array-end symbol denoting that the construction of the array for which the last 'array-start was generated and not closed is finished.
- 'object-start symbol denoting that an object should be constructed. The object's key-value pairs are emitted in sequence like those in a property list (plist) where keys are strings. That is, the generation of a key is always followed by the generation of a value. Otherwise, the JSON would be invalid and json-generator would raise an error.
- 'object-end symbol denoting that the construction of the object for which the last object-start was generated and not closed is finished.
- the symbol 'null
- boolean
- number
- string
In the case where nesting of arrays or objects reaches the value returned by the parameter json-nesting-depth-limit, the generator must raise an object that satisfies the predicate json-error?
In cases where the JSON is invalid, the generator returned by json-generator should raise an object that satisfies the predicate json-error?.
Otherwise, if PORT-OR-GENERATOR contains valid JSON text, the generator returned by json-generator must yield an end-of-file object in two situations:
- The first time the generator returned by json-generator is called, it returns an object that is a boolean, a number, a string or the symbol 'null.
- The first time the generator returned by json-generator is called, it returns a symbol that is not the symbol 'null. When the underlying JSON text is valid, it should be the symbol starting a structure: 'object-start or 'array-start. The end-of-file object is generated when that structure is finished.
In other words, the generator returned by json-generator will parse at most one JSON value or one top-level structure. If PORT is not finished, as in the case of JSON lines, the user should call json-generator again with the same PORT-OR-GENERATOR.
Author
The SRFI-180 library author is Amirouche Boubekki. It was ported to Chicken by Daniel Ziltener.
Repository
https://gitea.lyrion.ch/zilti/srfi-180
Copyright
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Version history
- 1.0.0 - Ported to Chicken 5.3.0