Skip to content

Commit a329fe0

Browse files
fangqfangq
committed
[spec] Update for Draft-3, add ChangeLog
1 parent d7930cd commit a329fe0

File tree

5 files changed

+159
-13
lines changed

5 files changed

+159
-13
lines changed

‎ChangeLog.txt‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
= Change Log =
2+
3+
Major updates are marked with a "*"
4+
5+
== JData Spec Draft-3, FangQ <q.fang (a) neu.edu> ==
6+
7+
2025-02-22 [8907586] Update .wordlist.txt
8+
2025-02-22 [eb7eed5] More examples using JSONPath
9+
2025-02-21 [b79b0a9] Support .datainfo in addition to _DataInfo_
10+
2025-02-21 [9eec3dd] Support _ArrayLabel_ to attach names to dimension and columns, like Xarray
11+
2025-02-21 [0b54719] Make appearance order for ND array constructs optional
12+
2024-10-05 [8d6ef7a] Added basic configuration for Dependabot for GitHub Actions
13+
2024-10-04 [4073b1a] Bumped Spellcheck action to contemporary version
14+
2024-04-25 [b888f19] Clarify endianness for binary JSON interface
15+
2024-04-05 [26b42ad] [lib] update jsonlab, pyjdata, pybj jsdata submodules
16+
2024-02-11 [69373ba] [feat] Support Enumeration data types via _EnumKey_ and _EnumValue_
17+
2024-01-22 [d8c3bfd] fix spelling action errors
18+
2024-01-22 [6b14df5] fix spelling action errors
19+
2024-01-22 [f2dbbae] add wordlist
20+
2024-01-22 [edd2da3] Add spellcheck action
21+
2024-01-22 [18dd229] Support `_ArrayShuffle_` for byte/bit-shuffle; add JSONPath, close #7
22+
2022-06-05 [6df9b65] update diagram
23+
2022-06-05 [37db600] Add synopsis diagram
24+
2022-06-05 [78145aa] add cheatsheet
25+
2022-06-04 [65f3a72] Update README.md
26+
2022-06-03 [282fa51] update mailing list url
27+
2022-06-01 [a861965] update various libraries to the latest git version
28+
2022-06-01 [4b3e0e5] update repo url to NeuroJSON org
29+
2022-02-23 [f41fd91] Update JData_specification.md
30+
2022-02-22 [39d8617] Update README.md
31+
2021-11-24 [54f339c] Add history info of this specification
32+
2021-11-17 [9de1d20] Update TOC
33+
2020-07-13 [10426fe] update python and matlab modules
34+
2020-06-14 [66e8d28] Format version fixed to 1, change draft version moving forward
35+
2020-06-04 [7aa3b03] Add "char" and "logical" as aliases to `uint8`
36+
2020-05-30 [22d6ea7] Fix the diag matrix param1 description
37+
2020-05-16 [85994de] Refer to the new BJData Draft-1 for the binary format, add _ArrayOrder_, support JSON Path
38+
2020-05-12 [40f5edb] Minor language fix before updating to Draft 3
39+
2020-05-04 [76abb9d] Add project banner to README
40+
2020-01-26 [bd80f81] Add MIME type support for ByteStream object; change preferred file suffixes
41+
2019-11-30 [34e8ae7] Update JData_specification.md
42+
2019-11-22 [e867f50] sync with pyjdata
43+
2019-11-21 [01e0360] add python jdata encoder and decoder
44+
2019-11-16 [e009ec3] update jsdata library to rev741
45+
2019-11-10 [de73e3d] add javascript parser
46+
2019-10-25 [6f3e578] Permit the use of _ArrayZipSize_ with _ArrayData_, rename _GraphEdges(0)_ to _GraphEdges0_
47+
2019-10-25 [3ae5215] jdataencode and jdatadecode update to jsonlab v1.9.8
48+
2019-08-20 [a9708dd] fix table transpose issue in jdatadecode
49+
50+
== JData Spec Draft-2, FangQ <q.fang (a) neu.edu> ==
51+
52+
2019-07-25 [f527b4a] update RFC links in README
53+
2019-07-25 [a6b350f] Change recommended binary JData suffix from ubjd to jbat
54+
2019-07-22 [7678245] Edward Xu's proof reading edits are fully merged
55+
2019-07-12 [04246cd] Partial proofreading by Edward Xu
56+
2019-07-10 [b0e2c44] update jsonlab to the latest git version
57+
2019-07-10 [be2b094] undo 0145358b, restore the missing UBJSON ND array header dimension type
58+
2019-07-10 [d6835b2] Change single quotes to double quotes
59+
2019-07-10 [671d0b8] Minor language change
60+
2019-07-10 [910aae9] Minor language update
61+
2019-07-10 [36481e4] _ArrayShape_ must appear before _ArrayData_
62+
2019-07-10 [04bc5fd] Requiring _ArrayData_ must be rectangular in shape
63+
2019-07-10 [8412dd3] Add the missing entry in TOC
64+
2019-07-10 [dc99b25] Support Hermitian matrices with "_ArrayShape_"
65+
2019-07-10 [144e61b] Add support to special matrices via "_ArrayShape_" descriptor
66+
2019-06-25 [9c181f3] support the new table syntax
67+
2019-06-25 [b3bd509] New table data format
68+
2019-06-21 [6cb6047] Update example compressed matrix using row-major element order
69+
2019-06-14 [3b898df] add jdataencode and jdatadecode
70+
2019-06-14 [bcbc005] Fix language grammar
71+
2019-06-12 [9003279] Update keyword list
72+
2019-06-12 [4b36cff] update ArrayCompression keyword names
73+
74+
== JData Spec Draft-1, FangQ <q.fang (a) neu.edu> ==
75+
76+
2019-06-12 [fbc2ec9] Merge branch 'Draft_1' of https://github.com/fangq/jdata
77+
2019-06-12 [e4836e8] update sample script outputs
78+
2019-06-12 [2d93802] shorten keywords form ArrayCompression to ArrayZip
79+
2019-06-12 [dc98eeb] show example of data compression, complete ubjson debug output
80+
2019-06-11 [8ef08e3] merge Draft_1 with master to correct UBJSON format bug and add samples
81+
2019-06-11 [c55452d] add debug output to understand the binary jdata output
82+
2019-06-11 [a83dd0f] add matlab demo script and small samples on basic features
83+
2019-06-08 [0145358] Fix the extra UBJSON optimized header field
84+
2019-06-04 [5b16687] fix typo in the README
85+
2019-06-04 [8725b85] remove extra commas
86+
2019-06-04 [341be6e] update RFC links in README
87+
2019-06-04 [b6c029d] update RFC links in README
88+
2019-06-04 [f8fc8f1] Draft 1 (v0.6) - Request for Comments
89+
2019-06-04 [d075c19] prepare for RFC commit
90+
2019-06-04 [a64dd18] Add missing keywords in the summary
91+
2019-06-04 [c29df5e] update README for Draft 1 RFC link
92+
2019-06-04 [cf54ba0] Bump version number to 0.6, name it as Draft 1
93+
2019-06-04 [1b6eba8] Add link to UBJSON [H] marker format
94+
2019-06-04 [9eff439] Fix typos in the byte-stream section
95+
2019-06-04 [91e2d4a] Fix the TOC level for Byte-stream section
96+
2019-06-04 [f4f574a] Support generic byte-stream data via _ByteStream_
97+
2019-06-04 [6caf0c1] Support weighted graphs in both _GraphEdges_ and _GraphMatrix_
98+
2019-06-04 [6f2b644] **Major change** N-D array serialization uses row-major instead of column-major
99+
2019-05-31 [3c922f2] Add optional _ArrayCompressionLevel_ and _ArrayCompressionOptions_ flags
100+
2019-05-31 [27e539c] _ArrayData_ as 2D array grouping indices; _ArrayIsComplex_/_ArrayIsSparse_ must be logical
101+
2019-05-23 [1fde391] Minor language update
102+
2019-05-23 [e3bba42] Remove incorrect enclosing square brackets in modified UBJSON array header, clarify infinity handling
103+
2019-05-21 [3fc4385] Minor wording change in the Maps section
104+
2019-05-21 [30a2dd3] Minor example changes
105+
2019-05-21 [3e851a8] Update toc for Maps section
106+
2019-05-21 [764dd65] Support non-string keyed hashes/maps
107+
2019-05-15 [3eaaa40] add rfc commit url in the README
108+
2019-05-15 [52e96b0] bump version number to v0.5, ready for public comments
109+
2019-05-15 [0fcfe98] fix isometric transform example, old example was problematic as 1st dim was singlet
110+
2019-05-15 [c915010] Plus sign in +inf can be omitted
111+
2019-05-15 [31b3ef9] Minor format change
112+
2019-05-15 [0bb3969] fine tune language for UBJSON array header format
113+
2019-05-15 [b9314ac] Clarify extended UBJSON array header syntax
114+
2019-05-14 [a37c625] Add data links and anchors in the keyword summary
115+
2019-05-14 [e598599] Add the missing closing underscores
116+
2019-05-14 [ce74db1] merge with typo corrected version
117+
2019-05-14 [8b4651f] minior format updates
118+
2019-05-14 [0cc07e4] Remove the pull-request tutorial link created for another project
119+
2019-05-13 [51b4b13] Fix typos in README
120+
2019-05-13 [a9b923f] Fix typos using autocorrect
121+
2019-05-13 [c766e88] add README and license file
122+
2019-05-13 [2a7cb29] update toc, add compression endianness
123+
2019-05-13 [05787d8] add data link, conversion, and toc, very first complete draft
124+
2019-05-10 [b3c4531] support struct, tables, graphs, add summary, add index and query interfaces
125+
2019-05-10 [07638da] complete ND array, tree and linked list
126+
2019-05-09 [42fd8c8] complete the data annotation keywords and definitions of metadata
127+
2019-05-07 [aa5d8fa] define data models using both topological names and semantic names
128+
2019-05-07 [3365b37] remove .wiki file, use .md file for the rest of the development
129+
2018-10-10 [5f4cf09] Add Markdown version of the file
130+
2018-06-10 [237ebe6] Update JData.wiki
131+
2015-01-15 [63ae46f] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=7.0
132+
2015-01-14 [d4f940f] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=6
133+
2015-01-11 [c0711ec] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=5
134+
2015-01-11 [6502b43] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=4
135+
2015-01-11 [b5f9b4e] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=3
136+
2015-01-10 [6490476] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=2
137+
2015-01-10 [62766f1] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=browse&id=jsonlab/Doc/JData&revision=1

‎JData_specification.md‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
JData: A general-purpose data annotation and interchange format
22
============================================================
33

4-
- **Status of this document**: This document is currently under development.
54
- **Copyright**: (C) Qianqian Fang (2011, 2015-2025) <q.fang at neu.edu>
65
- **License**: Apache License, Version 2.0
7-
- **Format Version**: 1 (Draft 3.preview)
6+
- **Version**: V1 (Draft-3)
7+
- **URL**: https://neurojson.org/jdata/draft3
8+
- **Status**: Frozen on March 23, 2025. For future updates, please see the Development URL below
9+
- **Development**: https://github.com/NeuroJSON/jdata
10+
- **Acknowledgement**: This project is supported by US National Institute of Health (NIH)
11+
grant [U24-NS124027 (NeuroJSON)](https://neurojson.org)
812
- **Abstract**:
913

1014
> JData is a general-purpose data interchange format aimed for portability,
@@ -148,7 +152,7 @@ The [Binary JData (BJData) format](https://github.com/NeuroJSON/bjdata) was deri
148152
from the Universal Binary JSON (UBJSON) format, which is one of the binary counterparts
149153
to the JSON format. It specifically addresses the above mentioned limitations,
150154
yet adheres to a simple grammar similar to the text-based JSON. Compared to other
151-
binary JSON-like formats, such as BSON (Binary JSON, http://bson.org), CBOR (Concise
155+
binary JSON-like formats, such as BSON (Binary JSON, https://bson.org), CBOR (Concise
152156
Binary Object Representation, [RFC 7049], https://cbor.io) and MessagePack
153157
(https://msgpack.org), BJData and UBJSON files are **"quasi-human-readable"** -
154158
a unique capability that is absent from almost all other binary formats.
@@ -179,12 +183,12 @@ structures, trees and graphs. A round-trip conversion is defined between the
179183
text and binary versions of JData documents.
180184

181185
The inception of this specification started in 2011 as part of the development
182-
of the [JSONLab Toolbox](http://iso2mesh.sourceforge.net/jsonlab/) - a popular
186+
of the [JSONLab Toolbox](https://neurojson.org/jsonlab/) - a popular
183187
open-source MATLAB/GNU Octave JSON reader/writer. The majority of the
184188
[annotated N-D array constructs](#annotated-storage-of-n-d-arrays) had been implemented
185189
in the [early releases](https://sourceforge.net/projects/iso2mesh/files/jsonlab/)
186190
of JSONLab. In 2015, the initial draft of this specification
187-
was [developed in the Iso2Mesh Wiki](http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=history&id=jsonlab/Doc/JData);
191+
was [developed in the Iso2Mesh Wiki](https://iso2mesh.sourceforge.net/cgi-bin/index.cgi?action=history&id=jsonlab/Doc/JData);
188192
since 2019, the development has been migrated to Github.
189193

190194
The purpose of this document is to define the text and binary JData format
@@ -234,8 +238,8 @@ separated by 0 or multiple permitted white spaces, namely
234238
### Binary JData Storage Grammar
235239

236240
The Binary JData (BJData) format used in this specification is based on
237-
[BJData Specification (Draft 2)](https://github.com/NeuroJSON/bjdata/tree/Draft_2),
238-
which is extended from the widely used [UBJSON Specification (Draft 12)](http://ubjson.org),
241+
[BJData Specification (Draft 3)](https://neurojson.org/bjdata/draft3),
242+
which is extended from the widely used [UBJSON Specification (Draft 12)](https://ubjson.org),
239243
with the addition of the following features
240244

241245
1. BJData supports 4 new data type markers: `[u]: uint16`, `[m]: uint32`, `[M]: uint64`, `[h]: float16`
@@ -257,11 +261,16 @@ where `ndim` is the number of dimensions, and `nx`, `ny`, and `nz` ... are
257261
all non-negative numbers specifying the dimensions of the N-dimensional array.
258262
`nz/ny/nz/ndim` types must be one of the BJData integer types (`i,U,I,u,l,m,L,M`).
259263
The binary data of the N-dimensional array is then serialized in the **row-major** format
260-
(similar to C, C++, Javascript or Python) order.
264+
(similar to C, C++, Javascript or Python) order, or, in the **column-major** format
265+
as in MATLAB for FORTRAN if using the following BJData Draft-3 syntax
266+
267+
```
268+
[[] [$] [type] [#] [[] [[] [$] [nx type] [#] [ndim type] [ndim] [nx ny nz ...] []] [nx*ny*nz*...*sizeof(type)]
269+
```
261270

262271
As a special note, all BJData/UBJSON integer and floating-point types must be
263272
stored in the **Little-Endian** format, according to
264-
[BJData Specification (Draft 2)](https://github.com/NeuroJSON/bjdata/tree/Draft_2).
273+
[BJData Specification (Draft )](https://neurojson.org/bjdata/draft3).
265274

266275

267276
Data Models
@@ -1406,7 +1415,7 @@ valued byte-stream `"JData specification"` shall be stored as
14061415

14071416
In the binary JData, a byte-stream shall be encoded using a similar `"name":value` pair where the
14081417
`value` is represented by an `[H]` marker. As specified in the
1409-
[BJData Specification (Draft 2)](https://github.com/NeuroJSON/bjdata/blob/master/Binary_JData_Specification.md#high-precision),
1418+
[BJData Specification (Draft 3)](https://github.com/NeuroJSON/bjdata/blob/master/Binary_JData_Specification.md#high-precision),
14101419
the `[H]` marker is immediately followed by the length of the byte stream, then followed by
14111420
the raw binary values of the byte-stream **without Base64 encoding**. The same example above
14121421
can be stored as

‎NOTICE.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
JData Specification
22

3-
Copyright (C) 2015,2019 Qianqian Fang <q.fang at neu.edu>
3+
Copyright (C) 2015,2019-2025 Qianqian Fang <q.fang at neu.edu>
44

55
License: Apache License Version 2.0, please see LICENSE_Apache-2.0.txt for details

‎lib/matlab‎

‎lib/python/pyjdata‎

0 commit comments

Comments
 (0)