Merge pull request #3 from fangq/master

Sync with NeuroJSON spec

.gitmodules

@@ -1,16 +1,19 @@
 [submodule "lib/matlab/jsonlab"]
 	path = lib/matlab/jsonlab
-	url = https://github.com/fangq/jsonlab.git
+	url = https://github.com/NeuroJSON/jsonlab.git
 [submodule "lib/matlab/zmat"]
 	path = lib/matlab/zmat
 	url = https://github.com/fangq/zmat.git
 [submodule "lib/c/ubj"]
 	path = lib/c/ubj
 	url = https://github.com/fangq/ubj.git
-[submodule "lib/python/py-ubjson"]
+[submodule "lib/cpp/json"]
+	path = lib/cpp/json
+	url = https://github.com/NeuroJSON/json
+[submodule "lib/python/pybj"]
 	path = lib/python/pybj
-	url = https://github.com/fangq/py-ubjson.git
+	url = https://github.com/NeuroJSON/pybj.git
 	branch = bjdata
 [submodule "lib/python/pyjdata"]
 	path = lib/python/pyjdata
-	url = https://github.com/fangq/pyjdata.git
+	url = https://github.com/NeuroJSON/pyjdata.git

Binary_JData_Specification.md

@@ -1,15 +1,16 @@
 Binary JData: A portable interchange format for complex binary data
 ============================================================
 
-- **Status of this document**: Request for comments.
+- **Status of this document**: Request for comments
 - **Maintainer**: Qianqian Fang <q.fang at neu.edu>
 - **License**: Apache License, Version 2.0
-- **Version**: 1 (Draft 2 - work-in-progress)
+- **Version**: 1 (Draft 2)
+- **Last Stable Release**: [Version 1 (Draft 2)](https://github.com/NeuroJSON/bjdata/blob/Draft_2/Binary_JData_Specification.md)
 - **Abstract**:
 
 > The Binary JData (BJData) Specification defines an efficient serialization 
 protocol for unambiguously storing complex and strongly-typed binary data found 
-in numerous application domains. The BJData specification is the binary counterpart
+in diverse applications. The BJData specification is the binary counterpart
 to the JSON format, both of which are used to serialize complex data structures
 supported by the JData specification (http://openjdata.org). The BJData spec is 
 derived and extended from the Universal Binary JSON (UBJSON, http://ubjson.org) 
@@ -38,8 +39,8 @@ applications. JSON presents numerous advantages, such as human readability,
 generality for accommodating complex hierarchical data, self-documentation, and 
 abundant existing free and commercial libraries. However, its utility is largely 
 restricted to the storage of lightweight textural data, and has very limited presence 
-in many data-intensive and performance-demanding applications, such as databases,
-medical imaging, and scientific data storage.
+in many data-intensive and performance-demanding applications, such as database
+backends, medical imaging, and scientific data storage.
 
 The lack of support for strongly-typed and binary data has been one of the main 
 barriers towards widespread adoption of JSON in these domains. In recent years, 
@@ -60,7 +61,7 @@ annotate and store complex data structures arising from diverse applications.
 
 The OpenJData framework first converts complex data structures, such as N-D
 arrays, trees, tables and graphs, into easy-to-serialize, portable data annotations
-via the **JData Specification** (https://github.com/fangq/jdata) and then serializes 
+via the **JData Specification** (https://github.com/NeuroJSON/jdata) and then serializes 
 and stores the annotated JData constructs using widely-supported data formats. 
 To balance data portability, readability and efficiency, OpenJData defines a 
 **dual-interface**: a text-based format **syntactically compatible with JSON**,
@@ -77,7 +78,7 @@ also allow a BJData file to store binary arrays larger than 4 GB in size, which
 is not currently possible with MessagePack (maximum data record size is limited
 to 4 GB) and BSON (maximum total file size is 4 GB).
 
-A key rationale for basing  the BJData format upon UBJSON as opposed to 
+A key rationale for basing the BJData format upon UBJSON as opposed to 
 other more popular binary JSON-like formats, such as BSON, CBOR and MessagePack, 
 is UBJSON's **quasi-human-readability** - a unique characteristic that is 
 absent from almost all other binary formats. This is because all data semantic 
@@ -93,7 +94,7 @@ inter-operate in complex applications.
 License
 ------------------------------
 
-The Binary JData Specification is licensed under the 
+The Binary JData Specification is licensed under the
 [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).
 
 
@@ -127,8 +128,8 @@ communicate their value (e.g. `string`). In addition, some values (e.g. `array`)
 have additional (_optional_) parameters to improve decoding efficiency and/or 
 to reduce the size of the encoded value even further.
 
-- The BJData specification (since Draft-2) requires that all numeric values be
-written in the **Little-Endian order**. This is a breaking feature compared to 
+- The BJData specification (since Draft-2) requires that all numeric values must be
+written in the **Little-Endian order**. This is a breaking change compared to 
 BJData Draft-1 and UBJSON Draft-12, where numeric values are in Big-Endian order.
 
 - The `array` and `object` data types are **container** types, similar to JSON
@@ -199,8 +200,7 @@ In BJData (using block-notation):
 ---
 ### <a name="value_noop"/>No-Op
 There is no equivalent to the `no-op` value in the original JSON specification. When 
-decoding, No-Op values should be skipped. Also, they can only occur as elements 
-of an `array` construct.
+decoding, No-Op values should be skipped.
 
 The intended usage of the `no-op` value is as a valueless signal between a 
 producer (most likely a server) and a consumer (most likely a client) to indicate 
@@ -528,7 +528,7 @@ shall be stored as
 ### Additional rules
 - A _count_ **must** be >= 0.
 - A _count_ can be specified by itself.
-- If a _count_ is specified the container **must not** specify an end-marker.
+- If a _count_ is specified, the container **must not** specify an end-marker.
 - A container that specifies a _count_ **must** contain the specified number of 
 child elements.
 - If a _type_ is specified, it **must** be done so before _count_.
@@ -585,12 +585,12 @@ If using both _count_ and _type_ optimizations, the marker itself represents the
 value, thus saving repetition (since these types do not have a payload). 
 Additional examples are:
 
-Strongly typed array of type `true` (Boolean) and with a _count_ of 512:
+Strongly-typed array of type `true` (Boolean) and with a _count_ of 512:
 ```
 [[][$][T][#][I][512]
 ```
 
-Strongly typed object of type `null` and with a _count_ of 3:
+Strongly-typed object of type `null` and with a _count_ of 3:
 ```
 [{][$][Z][#][i][3]
     [i][4][name] // name only, no value specified.
@@ -613,3 +613,7 @@ specification (Draft 12) developed by Riyad Kalla and other UBJSON contributors.
 The initial version of this MarkDown-formatted specification was derived from the 
 documentation included in the [Py-UBJSON](https://github.com/Iotic-Labs/py-ubjson/blob/dev-contrib/UBJSON-Specification.md) 
 repository (Commit 5ce1fe7).
+
+This specification was developed as part of the NeuroJSON project (http://neurojson.org) 
+with funding support from the US National Institute of Health (NIH) under
+grant [U24-NS124027](https://reporter.nih.gov/project-details/10308329).

README.md

@@ -1,48 +1,58 @@
-![](http://openjdata.org/img/openjdata_banner.png)
+![](https://neurojson.org/wiki/upload/neurojson_banner_long.png)
 
 # Binary JData Format Specification Development Guide
 
 We use this repository to gather feedback from the community regarding the 
 ["Binary JData Format Specification"](Binary_JData_Specification.md), or 
-Binary JData format. Such feedback is crucial to finalize this file 
-specification and help improve it in the future once disseminated. 
+Binary JData (**BJData**) format. Such feedback is crucial to finalize this file 
+specification and help improve it in the future once disseminated.
 
-The latest version of the Binary JData specification can be found in the file named 
+The latest version of the BJData specification can be found in the file named 
 [Binary_JData_Specification.md](Binary_JData_Specification.md). The specification is written
 in the [Markdown format](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) 
 for convenient editing and version control.
 
-This specification was based upon the Universal Binary JSON (UBJSON) Specification
+This specification was derived from the Universal Binary JSON (UBJSON) Specification
 [Draft 12](https://github.com/ubjson/universal-binary-json/tree/master/spec12)
 developed by Riyad Kalla and other UBJSON contributors. The MarkDown version 
 of this specification was derived from the documentation included in the 
 [Py-ubjson](https://github.com/Iotic-Labs/py-ubjson/blob/dev-contrib/UBJSON-Specification.md)
-repository (Commit 5ce1fe7).
+repository (Commit 5ce1fe7). **The BJData format is no longer backward compatible with UBJSON.**
+
+Libraries that support this specification include
+- Python: **pybj** (PIP:  https://pypi.org/project/bjdata/, Github: https://github.com/NeuroJSON/pybj)
+- MATLAB/Octave: **JSONLab** (Debian/Ubuntu/Fedora: `sudo apt-get install octave-jsonlab`, Github: https://github.com/fangq/jsonlab)
+- C: **ubj** (Github: https://github.com/fangq/ubj)
+- C++: **JSON for Modern C++** (with this patch https://github.com/nlohmann/json/pull/3336)
+
+**Acknowledgement**: This specification was developed as part of the NeuroJSON project
+(http://neurojson.org), with funding support from the US National Institute of Health (NIH) under
+grant [U24-NS124027](https://reporter.nih.gov/project-details/10308329) (PI: [Qianqian Fang](http://fanglab.org)).
 
 ## How to participate
 
 You can use a number of methods to provide your feedback to the working 
 draft of this file specification, including
 
-- [Create an "Issue"](https://github.com/OpenJData/bjdata/issues)
+- [Create an "Issue"](https://github.com/NeuroJSON/bjdata/issues)
   - This is the most recommended method to provide detailed feedback or 
     discussion. An "Issue" in github is highly versatile. One can ask a 
     question, report a bug, provide a feature request, or simply propose
     general discussions. Please use URLs or keywords to link your discussion 
     to a specific line/section/topic in the document.
-- [Write short comments on Request for Comments (RFC) commits](https://github.com/OpenJData/bjdata/commit/2f352210f928af9efd89f47c845d8e68c5b9bbc2)
+- [Write short comments on Request for Comments (RFC) commits](https://github.com/NeuroJSON/bjdata/commit/3f12e5ddaf75863ed9a69714dbd00e1258660118)
   - A milestone version of the specification will be associated with an
     RFC (Request for comments) commit (where the entire file is removed
     and re-added so that every line appears in such commit). One can
     write short comments as well as post replies on this RFC page. 
-  - The latest RFC commit is based on **Draft 1 (version v0.5)**. Please use
-    [this link](https://github.com/OpenJData/bjdata/commit/2f352210f928af9efd89f47c845d8e68c5b9bbc2) to comment.
+  - The latest stable release is **[Version 1 Draft 2](https://github.com/NeuroJSON/bjdata/tree/Draft_2)**. Please use
+    [this link](https://github.com/NeuroJSON/bjdata/commit/3f12e5ddaf75863ed9a69714dbd00e1258660118) to comment.
   - To add a comment, you need to first register a github account, and then 
     browse the above RFC page. When hovering your cursor over each line, a 
     "plus" icon is displayed, clicking it will allow one to comment on a 
     specific line (or reply to other's comments).
   - The RFC page can get busy if too many comments appear. Please consider 
-    using the [Issues section](https://github.com/OpenJData/bjdata/issues) if this happens.
+    using the [Issues section](https://github.com/NeuroJSON/bjdata/issues) if this happens.
   - One can browse the commit history of the specification document. If
     anyone is interested in commenting on a particular updated, you can also
     comment on any of the commit page using the same method.
@@ -57,15 +67,15 @@ please follow the below steps
 
 - Fork this repository and make updates, then create a pull-request
   - Please first register an account on github, then, browse the 
-    [JData repository](https://github.com/OpenJData/bjdata);
+    [JData repository](https://github.com/NeuroJSON/bjdata);
     on the top-right of this page, find and click the "Fork" button.
   - once you fork the JData project to your own repository, you may edit the
     files in your browser directly, or download to your local folder, and 
     edit the files using a text editor;
   - once your revision is complete, please "commit" and "push" it to your forked
-    git repository. Then you should create a pull-request against the upstream
-    repository (i.e., `OpenJData/bjdata`). Please select "Compare cross forks" and 
-    select `"OpenJData/bjdata"` as "base fork". Please write a descriptive title for
+    git repository. Then you should create a pull-request (PR) against the upstream
+    repository (i.e., `NeuroJSON/bjdata`). Please select "Compare cross forks" and 
+    select `"NeuroJSON/bjdata"` as "base fork". Please write a descriptive title for
     your pull-request. The project maintainer will review your updates
     and choose to merge to the upstream files or request revision from you.