diff --git a/CONFIG_FORMAT.md b/CONFIG_FORMAT.md
index d3baa1b..44e8774 100644
--- a/CONFIG_FORMAT.md
+++ b/CONFIG_FORMAT.md
@@ -1,23 +1,84 @@
-# Entity Manager
+# Config Files
 
-Entity manager is a runtime configuration application which parses configuration
-files (in JSON format) and attempts to detect the devices described by the
-configuration files. It also can, based on the configuration, attempt to load
-install devices into sysfs. It takes these configurations and produces a best
-representation of the files on dbus using the xyz.openbmc_project.Configuration
-namespace. It also produces a system.json file for persistence.
+## Intent
+
+Configuration files are intended to represent the minimum amount of
+configuration required to describe a given piece of hardware.  As such, they are
+intended to be simple, and are guided by the following principles.
+
+1. Configuration files should be easy to write.  If a tradeoff is to be made
+   between a config file being complex to write, and a reactor being complex to
+   write, the reactor will be the one to hold the complexity.  Why?
+    - Configuration files will get replicated and built to support hundreds of
+      systems over time, and scale linearly with the number of systems.  In
+      contrast, reactors tend to scale as a logarithm of system count, with each
+      new system supported adding fewer and fewer reactors.  As such, pushing
+      the complexity to the reactors leads to fewer lines of code overall, even
+      if the reactor itself contains more complex actions.
+    - Reactor writers tend to be domain experts on their subsystem, and
+      intimately understand the constraints that are emplaced on that subsystem.
+      Config file writers are generally building support for a wide range of
+      reactors on a single piece of hardware, and will generally have less
+      knowledge of each individual reactors constraints.
+
+2. Configuration files should trend toward one config file per physical piece
+   of hardware, and should avoid attempting to support multiple variations of a
+   given piece of hardware in a single file, even at the risk of duplicating
+   information.  Why?
+    - Hardware constraints, bugs, and oddities are generally found over time.
+      The initial commit of a configuration file is far from the final time that
+      changes will be submitted.  Having each individual piece of hardware in
+      its own file minimizes the change needed between different components when
+      bugs are found, or features are added.
+    - Having separate config files reduces the number of platforms that need to
+      be tested for any given config file change, thus limiting the "blast
+      radius" of particular kinds of changes, as well as making an explicit log
+      of what changed for a specific platform.
+    - Having one config file per piece of hardware makes it much easier and
+      clear for a user to determine if a piece of hardware is supported.
+    - Note: This is a "guideline" not a "rule".  There are many cases of
+      hardware that despite having different part numbers, are actually
+      physically identical, and as such, the config files will never differ.
+        - Example: SAS modules and cards made by the same company, on the same
+          process, and branded with different manufacturers and part numbers.
+        - Non-Example: Power supplies.  While all pmbus power supplies appear
+          similar, there tend to be significant differences in featuresets,
+          bugs, and OEM supported firmware features.  As such, they require
+          separate config files.
+
+3. Configuration files are not a long-term stable ABI.  Why?
+    - Configuration files occasionally need to modify their schema in pursuit of
+      simplicity, or based on a greater understanding of the system level
+      constraints.
+    - The repo will ensure that all schema changes are enacted such that the
+      files in the repo will not be broken as a result of the schema change, and
+      will be carried forward.  The recommended way to avoid merge problems is
+      to upstream your configurations.
+    - Note: This drives the requirement that config files shall not be checked
+      into OpenBMC meta layers.
+
+4. Configurations should represent only the things that are _different_ and
+   undetectable between platforms.  Why?
+    - There are many behaviors that the BMC has that are very easily detected
+      at runtime, or where the behavior can be identical between different
+      platforms.  Things like timeouts, protocol versions, and communcation
+      channels can generally be represented with a default that works for all
+      platforms, and doesn't need to be an entity-configurable parameter.  In
+      general, reducing the config files to _only_ the differences reduces
+      complexity, and explicitly bounds where dicsussion is needed for platform
+      differences, and where a difference is "supported" and "reasonable" to
+      maintain in the long run.
 
 ## Configuration Syntax
 
 In most cases a server system is built with multiple hardware modules (circuit
 boards) such as baseboard, risers, and hot-swap backplanes. While it is
 perfectly legal to combine the JSON configuration information for all the
-hardware modules into a single file if desired, it is also possible to divide
-them into multiple configuration files. For example, there may be a baseboard
-JSON file (describes all devices on the baseboard) and a chassis JSON file
-(describes devices attached to the chassis). When one of the hardware modules
-needs to be upgraded (e.g., a new temperature sensor), only such JSON
-configuration file needs to be be updated.
+hardware modules into a single file if desired, it is recommended to divide them
+into multiple configuration files. For example, there may be a baseboard JSON
+file (describes all devices on the baseboard) and a chassis JSON file (describes
+devices attached to the chassis).  Other examples of entities might be
+removable power supplies, fans, and PCIe add in cards.
 
 Within a configuration file, there is a JSON object which consists of multiple
 "string : value" pairs. This Entity Manager defines the following strings.
@@ -40,24 +101,22 @@
 | "$address"   | When the "probe" is successful, this template string is substituted with the (7-bit) I2C address of the FRU device. |
 | "$index"        | A run-tim enumeration. This template string is substituted with a unique index value when the "probe" command is successful. This allows multiple identical devices (e.g., HSBPs) to exist in a system but each with a unique name. |
 
-
-
 ## Configuration HowTos
 
 If you're just getting started and your goal is to add sensors dynamically,
 check out [My First Sensors](docs/my_first_sensors.md)
 
+## Configuration schema
+
+The config schema is documented in [README.md](schemas/README.schema)
 
 ## Configuration Records - Baseboard Example
 
-Required fields are name, probe and exposes.
-
-The configuration JSON files attempt to model the actual hardware modules
-which make up a complete system. An example baseboard JSON file shown below
-defines two fan connectors and two temperature sensors of TMP75 type. These
-objects are considered valid by BMC when the probe command (reads and compares
-the product name in FRU) is successful and this baseboard is named as "WFP
-baseboard".
+The configuration JSON files attempt to model the actual hardware modules which
+make up a complete system. An example baseboard JSON file shown below defines
+two fan connectors and two temperature sensors of TMP75 type. These objects are
+considered valid by BMC when the probe command (reads and compares the product
+name in FRU) is successful and this baseboard is named as "WFP baseboard".
 
 ```
 {