Describe what chunks, systems & strata actually are, and link to schemas

The spec was trying to be technically precise about describing the
structure of the .morph files. The JSON-Schema format is much better
than prose for precisely describing structure of JSON/YAML documents, so
we should link to the schemas.

The text of the spec can then be rewritten a bit so it describes the
intention and meaning of the different .morph files a bit more clearly.

More rewriting would be useful. It's also unfortunate that we have go
as far as 4th-level headings (####), reorganising a bit could fix that.

Change-Id: Ic502db0b5723a46f72d9cf375df623ad89b4686d

1 files changed, 42 insertions, 8 deletions

diff --git a/spec.mdwn b/spec.mdwn
index 8e43b13..c7574d7 100644
--- a/spec.mdwn
+++ b/spec.mdwn
@@ -92,7 +92,16 @@ Within this document, consider 'building' to be the act of running a series of
 commands in a given 'environment', where the commands and how to build the
 environment are completely specified by the definitions and the build tool.
 
-For chunks, use the following fields:
+#### Chunks
+
+A 'chunk' definition describes an individual component, which can be built from
+a Git repository by executing the given sequence of commands.
+
+The structure of a 'chunk' definition is described using [JSON-Schema] in the
+[spec.git] repo:
+<http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/chunk.json-schema>
+
+The fields mean the following:
 
 * `build-system`: if the program is built using a build system known to
   `morph`, you can set this field and avoid having to set the various
@@ -169,7 +178,17 @@ For chunks, use the following fields:
   created, named according to the definition, and containing all files;
   optional
 
-For strata, use the following fields:
+#### Strata
+
+A 'stratum' is a group of related chunks. A stratum can contain only chunks.
+Certain information about how to build a chunk is defined in the containing
+stratum, rather than in the chunk definition.
+
+The structure of a 'stratum' definition is described using [JSON-Schema] in the
+[spec.git] repo:
+<http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/stratum.json-schema>
+
+The fields mean the following:
 
 * `build-depends`: a list of strings, each of which refers to another
   stratum that the current stratum depends on. This list may be omitted
@@ -199,14 +218,23 @@ For strata, use the following fields:
   of a workaround for the lack of distinction between build and runtime
   dependencies.
 
-For systems, use the following fields:
+#### Systems
+
+In the Baserock model, a 'system' is the top level entity that you actually
+build and execute. Systems contain one or more strata.
+
+The structure of a 'system' definition is described using [JSON-Schema] in the
+[spec.git] repo:
+<http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/system.json-schema>
+
+The fields mean the following:
 
 * `strata`: a list of key/value mappings, similar to the 'chunks' field of a
   stratum. Two fields are allowed (are both required?):
     - `name`: name of the artifact when the stratum is build
     - `morph`: path to a stratum .morph file relative to the top of the containing repo
 
-Example chunk (simplified commands):
+#### Example chunk (simplified commands):
 
     name: eglibc
     kind: chunk
@@ -218,7 +246,7 @@ Example chunk (simplified commands):
     install-commands:
     - cd o && make install_root="$DESTDIR" install
 
-Example stratum:
+#### Example stratum:
 
     name: foundation
     kind: stratum
@@ -244,7 +272,7 @@ Example stratum:
       - fhs-dirs
       - linux-api-headers
 
-Example system:
+#### Example system:
 
     name: base
     kind: system
@@ -265,8 +293,12 @@ post-processing a filesystem tree with one or more 'configure extensions', then
 performing an operation to convert and/or transfer the filesystem tree
 using a 'write extension'.
 
+The structure of the 'cluster' definitions is described using [JSON-Schema] in
+the [spec.git] repo:
+<http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/cluster.json-schema>
+
 A cluster morphology defines a list of systems to deploy, and for each system a
-list of ways to deploy them. Use the following field:
+list of ways to deploy them. The fields are used as follows:
 
 * **systems**: a list of systems to deploy;
     the value is a list of mappings, where each mapping has the
@@ -377,7 +409,9 @@ The following environment variables can be used in chunk configure/build/install
 
 FIXME: The `TARGET` and `TARGET_STAGE1` fields are specific to building GNU/Linux based systems, they shouldn't be mandated in the spec.
 
+[JSON-Schema]: https://www.json-schema.org/
 [Morph]: http://wiki.baserock.org/Morph/
 [YBD]: http://wiki.baserock.org/ybd/
-[morph.git]: git://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/morph
+[morph.git]: git://git.baserock.org/cgit/baserock/baserock/morph.git/
+[spec.git]: git://git.baserock.org/cgit/baserock/baserock/spec.git/
 [YAML]: http://yaml.org/