Declarative JSON data manipulation for OCaml
ocaml-json: side-by-side RFC 8259 spec annotation in mlis
Mirror the yaml.mli polish: cite the JSON grammar by section in the
public docs so a reader holding RFC 8259 / ECMA-404 open can map
either direction.
- [Sort.t] (sort.mli): each case carries its RFC 8259 § (§3 for
null/true/false literals, §4 for object, §5 for array, §6 for
number, §7 for string).
- [Value.t] / [name] / [member] / [object'] (value.mli): point at
the same sections; note that the RFC says object member order is
insignificant but we preserve it for layout fidelity.
- IO sections (json.mli): cite RFC 8259 §2 [JSON-text] (whitespace +
value + whitespace) for both decoders and encoders.
- Codec section headers (codec.mli): one short paragraph per
Numbers / Strings / Arrays / Objects / Nulls naming the relevant
RFC §, anchoring the listed combinators to the grammar they target.
No code changes; .mli docs only.
+64
-27
+29
-6
lib/codec.mli
+29
-6
lib/codec.mli
···
184
184
*)
185
185
end
186
186
187
-
(** {2:option Nulls and options} *)
187
+
(** {2:option Nulls and options}
188
+
189
+
JSON's [null] (RFC 8259 §3) is a single literal value with no native
190
+
[option] analogue; the codecs below pick a convention for mapping OCaml
191
+
[option] / unit-like sentinels onto it. *)
188
192
189
193
val null : ?kind:string -> ?doc:string -> 'a -> 'a t
190
194
(** [null v] maps JSON nulls to [v]. On encodes any value of type ['a] is
···
202
206
(** [option t] maps JSON nulls to [None] and other values by [t]. [doc] and
203
207
[kind] are given to the underlying {!val-any} map. *)
204
208
205
-
(** {2:booleans Booleans} *)
209
+
(** {2:booleans Booleans}
210
+
211
+
[true] / [false] literals (RFC 8259 §3). *)
206
212
207
213
val bool : bool t
208
214
(** [bool] maps JSON booleans to [bool] values. See also {!Base.bool}. *)
209
215
210
-
(** {2:numbers Numbers} *)
216
+
(** {2:numbers Numbers}
217
+
218
+
JSON's number grammar (RFC 8259 §6) does not constrain precision; the codecs
219
+
below pick OCaml-side representations and document how each handles JSON's
220
+
open-ended integer range. *)
211
221
212
222
val number : float t
213
223
(** [number] maps JSON nulls or numbers to [float] values. On decodes JSON null
···
297
307
{b Warning.} The behaviour of this function is platform dependent, it
298
308
depends on the value of [Sys.int_size]. *)
299
309
300
-
(** {2:enums Strings and enums} *)
310
+
(** {2:enums Strings and enums}
311
+
312
+
JSON strings (RFC 8259 §7): a sequence of Unicode code points enclosed
313
+
in [" "], with [\] escapes for control characters and [\uXXXX] for
314
+
BMP code points (or surrogate pairs for non-BMP). *)
301
315
302
316
val string : string t
303
317
(** [string] maps unescaped JSON strings to UTF-8 encoded [string] values. See
···
332
346
encoding uses only lower case hexadecimal digits to encode the byte
333
347
sequence. *)
334
348
335
-
(** {1:arrays Arrays and tuples} *)
349
+
(** {1:arrays Arrays and tuples}
350
+
351
+
JSON arrays (RFC 8259 §5): an ordered sequence of values enclosed in [[ ]]
352
+
with [,] separators. Element order is significant. *)
336
353
337
354
(** Mapping JSON arrays. *)
338
355
module Array : sig
···
472
489
(** [tn ~n t] maps JSON arrays of exactly [n] elements of type [t] to [array]
473
490
values. This is {!val-array} limited by [n]. *)
474
491
475
-
(** {1:objects Objects} *)
492
+
(** {1:objects Objects}
493
+
494
+
JSON objects (RFC 8259 §4): an unordered set of [name : value] members
495
+
enclosed in [{ }] with [,] separators. The RFC says member order is
496
+
insignificant; we preserve it for layout fidelity. The RFC also says
497
+
duplicate names ["SHOULD" be unique] (§4) but does not forbid them; the
498
+
object combinators reject duplicates by default — see [Object.case]. *)
476
499
477
500
(** Mapping JSON objects. *)
478
501
module Object : sig
+9
-2
lib/json.mli
+9
-2
lib/json.mli
···
641
641
(** {1:decode Byte-stream decoding}
642
642
643
643
These functions decode bytes directly to typed OCaml values through a codec.
644
-
Use {!Value.of_string} if you specifically want a generic {!type-t} tree. *)
644
+
Input is expected to conform to the JSON grammar
645
+
({{:https://www.rfc-editor.org/rfc/rfc8259}RFC 8259} §2: a single
646
+
[JSON-text] = whitespace + value + whitespace). Use {!Value.of_string} when
647
+
you want the generic {!type-t} tree instead. *)
645
648
646
649
val of_reader :
647
650
?meta:meta ->
···
668
671
(** [of_string_exn] is like {!val-of_string} but raises {!Json.exception-Error}.
669
672
*)
670
673
671
-
(** {1:encode Byte-stream encoding} *)
674
+
(** {1:encode Byte-stream encoding}
675
+
676
+
Output is RFC 8259 §2 conforming. Indentation and whitespace introduced by
677
+
[?indent] / [?preserve] are JSON-grammar whitespace ([\\t \\n \\r \\u0020])
678
+
per RFC 8259 §2. *)
672
679
673
680
val to_writer :
674
681
?buf:Bytes.t ->
+10
-9
lib/sort.mli
+10
-9
lib/sort.mli
···
6
6
(** JSON value sorts, used as labels in error contexts and path frames.
7
7
8
8
A {e sort} is the closed enumeration of node categories the JSON grammar
9
-
defines (RFC 8259): null, bool, number, string, array, object. A {e kind} is
10
-
the specific human-readable label for one instance, built from a sort plus
11
-
an identifier, e.g. ["member email"] or ["list of users"]. *)
9
+
defines: the six values an RFC 8259 §3 / ECMA-404 §5 [JSON-text] can
10
+
represent. A {e kind} is the specific human-readable label for one instance,
11
+
built from a sort plus an identifier — e.g. ["member email"] or
12
+
["list of users"]. *)
12
13
13
14
type t =
14
-
| Null
15
-
| Bool
16
-
| Number
17
-
| String
18
-
| Array
19
-
| Object (** The type for JSON value sorts. *)
15
+
| Null (** [null] literal (RFC 8259 §3). *)
16
+
| Bool (** [true] / [false] literals (RFC 8259 §3). *)
17
+
| Number (** Number value (RFC 8259 §6 [number] grammar). *)
18
+
| String (** String value (RFC 8259 §7 [string] grammar). *)
19
+
| Array (** Array structure (RFC 8259 §5). *)
20
+
| Object (** Object structure (RFC 8259 §4). *)
20
21
21
22
val to_string : t -> string
22
23
(** [to_string sort] is the lowercase JSON name of [sort]. *)
+16
-10
lib/value.mli
+16
-10
lib/value.mli
···
1
1
(** Generic JSON values.
2
2
3
-
The core AST: atoms ([Null], [Bool], [Number], [String]) plus [Array] and
4
-
[Object] built from them. Each value carries metadata (source location,
5
-
surrounding whitespace) for error reporting and layout-preserving recode.
3
+
The AST mirrors the six JSON values of
4
+
{{:https://www.rfc-editor.org/rfc/rfc8259}RFC 8259} §3 (also ECMA-404 §5):
5
+
atoms ([Null], [Bool], [Number], [String]) plus the two structures ([Array],
6
+
[Object]). Each node carries metadata (source location, surrounding
7
+
whitespace) for error reporting and layout-preserving recode.
6
8
7
9
{!Json.Value} re-exports this module as the value-facing part of the public
8
10
API. *)
···
13
15
(** An AST node: a payload plus metadata. *)
14
16
15
17
type name = string node
16
-
(** A JSON member name (string plus its source location). *)
18
+
(** A JSON object member name (RFC 8259 §4): a string-typed node. *)
17
19
18
20
type member = name * t
19
-
(** A JSON object member: a name bound to a value. *)
21
+
(** A JSON object member (RFC 8259 §4): a [name : value] pair. *)
20
22
21
23
and object' = member list
22
-
(** A JSON object: an ordered list of members. *)
24
+
(** A JSON object (RFC 8259 §4): an ordered list of members. The RFC says member
25
+
order is insignificant; we preserve it for layout fidelity. *)
23
26
24
27
and t =
25
-
| Null of unit node
26
-
| Bool of bool node
28
+
| Null of unit node (** [null] literal (RFC 8259 §3). *)
29
+
| Bool of bool node (** [true] / [false] literals (RFC 8259 §3). *)
27
30
| Number of float node
31
+
(** Number value (RFC 8259 §6). The spec leaves precision to the
32
+
implementation; we store as IEEE-754 [float]. *)
28
33
| String of string node
29
-
| Array of t list node
30
-
| Object of object' node (** *)
34
+
(** String value (RFC 8259 §7), held as raw UTF-8 bytes. *)
35
+
| Array of t list node (** Array (RFC 8259 §5). Order is preserved. *)
36
+
| Object of object' node (** Object (RFC 8259 §4). *)
31
37
32
38
type 'a cons = ?meta:Meta.t -> 'a -> t
33
39
(** The type for constructors that lift an OCaml ['a] into a JSON value,