diff --git a/examples/fodo.pals.yaml b/examples/fodo.pals.yaml
index 80932be..f8a84c0 100644
--- a/examples/fodo.pals.yaml
+++ b/examples/fodo.pals.yaml
@@ -9,32 +9,36 @@
 # - definition of a FODO channel that:
 #   - repeats a line (fodo_cell) three times
 #
-- drift1:
-    kind: Drift
-    length: 0.25
+PALS:
+  version: null  # later, we will put the version of the PALS standard here
 
-- quad1:
-    kind: Quadrupole
-    MagneticMultipoleP:
-      Bn1: 1.0
-    length: 1.0
-
-- fodo_cell:
-    kind: BeamLine
-    line:
-    - drift1
-    - quad1
-    - drift2:
+  lattices:
+    - drift1:
         kind: Drift
-        length: 0.5
-    - quad2:
-        inherit: quad1
+        length: 0.25
+  
+    - quad1:
+        kind: Quadrupole
         MagneticMultipoleP:
-          Bn1: -1.0
-    - drift1
-
-- fodo_channel:
-    kind: BeamLine
-    line:
+          Bn1: 1.0
+        length: 1.0
+  
     - fodo_cell:
-        repeat: 3
+        kind: BeamLine
+        line:
+        - drift1
+        - quad1
+        - drift2:
+            kind: Drift
+            length: 0.5
+        - quad2:
+            inherit: quad1
+            MagneticMultipoleP:
+              Bn1: -1.0
+        - drift1
+  
+    - fodo_channel:
+        kind: BeamLine
+        line:
+      - fodo_cell:
+          repeat: 3
diff --git a/source/conventions.md b/source/conventions.md
index ff93f86..1856170 100644
--- a/source/conventions.md
+++ b/source/conventions.md
@@ -83,7 +83,26 @@ associated standards, there are packages that implement translation between latt
 representational internal format defined by the package.
 
 While the standard itself is language agnostic, this document that describes the standard
-needs to use some syntax and this syntax is based upon YAML. Non-YAML syntax used here is:
+needs to use some syntax and this syntax is based upon YAML.
+
+%---------------------------------------------------------------------------------------------------
+(s:palsroot)=
+## PALS Root Object
+
+The root of the PALS schema is given by this dictionary:
+```{code} YAML
+PALS:
+  version: null  # version schema: defined later
+
+  lattices:
+    - ...  # a list of lattice elements and commands
+```
+
+%---------------------------------------------------------------------------------------------------
+(s:matching)=
+## Matching Syntax
+
+Non-YAML syntax used here is:
 
 1. The {math}`N^{th}` item in a list is referred to using square brackets enclosing the index: `[N]`.
 For example:
@@ -142,13 +161,27 @@ Optional string parameters have a default value of blank unless otherwise stated
 
 %---------------------------------------------------------------------------------------------------
 (s:includefiles)=
-## Include Files
+## Include Lattice Files
 
-A lattice file can include other lattice files using an include statement.
-```{code} yaml
-include: <file-name>
+A lattice file can include other lattices (elements and commands) using an include statement.
+
+Example:
+```{code} YAML
+PALS:
+  # ...
+
+  lattices:
+    # the elements and commands of base-lattice.pals.yaml
+    - include: "./base-lattice.pals.yaml"
+
+    # the elements and commands of extra-lattice.pals.yaml
+    - include: "./base-lattice.pals.yaml"
+
+    # a list of additional lattice elements and commands
+    - ...
 ```
-where `<file-name>` is the name of the file to be included.
+where the include file names above are examples.
+Includes simply insert the `lattices` block of the `include` file(s).
 
 %---------------------------------------------------------------------------------------------------
 (s:names)=