api+json: Create schema-version field

resolve #27

Author: KSXGitHub

src/app/sub.rs

@@ -2,7 +2,7 @@ use crate::{
     args::Fraction,
     data_tree::{DataTree, DataTreeReflection},
     fs_tree_builder::FsTreeBuilder,
-    json_data::{JsonData, UnitAndTree},
+    json_data::{JsonData, SchemaVersion, UnitAndTree},
     os_string_display::OsStringDisplay,
     reporter::ParallelReporter,
     runtime_error::RuntimeError,
@@ -121,7 +121,10 @@ where
                 .par_convert_names_to_utf8() // TODO: allow non-UTF8 somehow.
                 .expect("convert all names from raw string to UTF-8")
                 .into();
-            let json_data = JsonData { unit_and_tree };
+            let json_data = JsonData {
+                schema_version: SchemaVersion,
+                unit_and_tree,
+            };
             return serde_json::to_writer(stdout(), &json_data)
                 .map_err(RuntimeError::SerializationFailure);
         }

src/json_data.rs

@@ -1,3 +1,7 @@
+pub mod schema_version;
+
+pub use schema_version::SchemaVersion;
+
 use crate::{
     data_tree::Reflection,
     size::{Blocks, Bytes},
@@ -25,6 +29,8 @@ pub enum UnitAndTree {
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]
 pub struct JsonData {
+    /// The `"schema-version"` field.
+    pub schema_version: SchemaVersion,
     /// The `"unit"` field and the `"tree"` field.
     #[cfg_attr(feature = "json", serde(flatten))]
     pub unit_and_tree: UnitAndTree,

src/json_data/schema_version.rs

@@ -0,0 +1,46 @@
+#[cfg(feature = "json")]
+use derive_more::Display;
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+#[cfg(feature = "json")]
+use std::convert::TryFrom;
+
+/// Content of [`SchemaVersion`].
+pub const SCHEMA_VERSION: &str = "2021-06-05";
+
+/// Verifying schema version.
+#[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "json", serde(try_from = "String", into = "&str"))]
+pub struct SchemaVersion;
+
+/// Error when trying to parse [`SchemaVersion`].
+#[cfg(feature = "json")]
+#[derive(Debug, Display)]
+#[display(
+    fmt = "InvalidSchema: {:?}: input schema is not {:?}",
+    input,
+    SCHEMA_VERSION
+)]
+pub struct InvalidSchema {
+    /// The input string.
+    pub input: String,
+}
+
+#[cfg(feature = "json")]
+impl TryFrom<String> for SchemaVersion {
+    type Error = InvalidSchema;
+    fn try_from(input: String) -> Result<Self, Self::Error> {
+        if input == SCHEMA_VERSION {
+            Ok(SchemaVersion)
+        } else {
+            Err(InvalidSchema { input })
+        }
+    }
+}
+
+impl<'a> From<SchemaVersion> for &'a str {
+    fn from(_: SchemaVersion) -> Self {
+        SCHEMA_VERSION
+    }
+}