From f28abd489cc7ebd9f2d14f584052a93607d78985 Mon Sep 17 00:00:00 2001
From: Katharina Fey <kookie@spacekookie.de>
Date: Thu, 28 Feb 2019 20:33:22 +0100
Subject: Adjusting the way that schemas work

---
 README.md | 36 +++++++++++++++++++++---------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 8e78484..1d92cd7 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,12 @@ defining what data types exist and how they are layed out.
 The file extention for a `g3f` file is `.g3f` by default, 
 however this implementation is not opinionated on that.
 
+Another important point:
+it should be considered part of the spec that writes are
+done in-place to existing data.
+No data should be overwritten if not explicitly desired
+by the application using the `g3f` library!
+
 ### Header
 
 At the top of every `g3f` file is a header.
@@ -47,14 +53,15 @@ It looks something like this
 {impl "g3f-reference"}
 {impl_version "0.8.5"}
 
-{schemas} 
-# ...
+{data}
 ```
 
 A few notes here:
 
-- `g3f` is a flat format. When declaring a new top-level block (i.e. `{schemas}`) this ends the `{header}` block.
-- A block can enforce a schema (i.e. here we enforce that all required fields from `builtin/header` are present)
+- `g3f` is a flat format. When declaring a new top-level block
+  (i.e. `{data}`) this ends the `{header}` block.
+- A block can enforce a schema (i.e. here we enforce that all 
+  required fields from `builtin/header` are present)
 - Nodes always have a single data value. Supported types are
   - string (`"1.0.0"`)
   - int (`42`)
@@ -63,23 +70,22 @@ A few notes here:
   - list<...> (`[ ... ]` - Elements are not comma-separated!)
   - ref (`some_id` - not quoted!)
   - type (`<...>` refers to some type information
-  - NULL (`<>` which is an empty type/name marker)
+  - schema (`<schema>` as a literal)
 - `#` is a line comment. There are no block-comments
 
 ### Schemas
 
 As previously mentioned `g3f` is a strongly typed file format.
 Schemas are IDs that can be referenced by other IDs.
-But because `g3f` is completely flat, it's impossible to define
-schema blocks inside the `{schema}` block itself.
-
-Instead it uses the `NULL` markers to define the existence of schemas.
-Schemas are then later defined in-line with the rest of the data. 
+Because `g3f` is completely flat, it's impossible to have a `{schemas}`
+block in which to define schemas.
+Instead inside the header it's possible to use the `<schema>` type marker
+to pre-declare schema data which will later be defined by blocks.
 
 ```g3f
-{schemas}
-{node <>}
-{link <>}
+{header}
+{node <schema>}
+{links <schema>}
 
 {node}
 {id <int>}
@@ -100,7 +106,7 @@ if you want your file format to be completely dynamic and terrible.
 ```g3f
 {<>:node}
 {id 0}
-{links [ 1 ]:}
+{links [ 1 ]}
 
 {<>:node}
 {id 1}
@@ -131,7 +137,7 @@ struct node_t {
 struct node_t * nodes = [ node_t { ... }, node_t { ... } ];
 ```
 
-Because `g3f` has no hirarchy structure, and there's no in-file format references between the two nodes,
+Because `g3f` has no hierarchical structure, and there's no in-file format references between the two nodes,
 the deserialised returns a list of nodes.
 Building a graph in memory is then your responsibility.
 However, `g3f` can handle a few scenarios for you.
-- 
cgit v1.2.3