[nnpackage] Update specification (model_and_operators) (#5529)

* [nnpackage] Update specification (model_and_operators)

Added:

- Serialization Format
- Baseline Schema
- Unspecified dimension

* Remove rationale for serialization format

diff --git a/contrib/nnpackage/spec/20_model_and_operators.md b/contrib/nnpackage/spec/20_model_and_operators.md
index e939df3..7deee8d 100644 (file)
--- a/contrib/nnpackage/spec/20_model_and_operators.md
+++ b/contrib/nnpackage/spec/20_model_and_operators.md
@@ -1,7 +1,51 @@
 # Model
 
-## Model Schema
+## Serialization Format
 
-See [flatbuffers schema for nnpackage model](../schema/nnpackage_model.fbs).
+`nnpackage` uses flatbuffers to store model.
 
-# Operator
+Rationale:
+
+1. `flatbuffers` is:
+
+- space-efficient
+- explicit-schema based
+- royalty-free license open-source library
+- header-only solution (unless we use flatbuffer's reflection)
+- proven solution (used by TensorFlow-Lite)
+
+2. We've checked other solutions:
+- [`bjson (binary JSON)`](http://bjson.org/)
+- `protocol buffers`
+
+## Baseline Schema
+
+`nnpackage` schema is based on tensorflow-lite schema.
+
+Rationale:
+
+- Fundamentally, `nnpackage` and `TFLite` have same aim:
+Running pre-trained models on a device, which has relatively low computing power and memory.
+TFLite's solution is acceptable, we don't need to create same thing again.
+- We can use several infra-structures and tools from TFLite.
+
+## Extensions
+
+`nnpackage` model has some extensions that are different or missing from TFLite.
+
+### Unspecified Dimension
+
+`nnpackage` represents unspecified dimension with `-1`.
+
+Rationale:
+
+1. It should be `int` since dimension is int type flatbuffer schema. Thus '?' cannot be used.
+2. `0` is also a candidate, which is used for Android NN API.
+However, we would like to reserve `0` because `0` could be a valid dimension for a certain
+operator (e.g. `tflite.slice`).
+
+## Operator Reference
+
+## Schema Source
+
+For detail, see the schema file [flatbuffers schema for nnpackage model](../schema/nnpackage_model.fbs).