From 090544f26034b83d18905f3262a22d9d5202ca79 Mon Sep 17 00:00:00 2001
From: Rob Bocchino <bocchino@jpl.nasa.gov>
Date: Sun, 2 Nov 2025 13:21:15 -0800
Subject: [PATCH] Revise Dictionary Definitions

---
 docs/fpp-spec.html                            |  10 +-
 docs/fpp-users-guide.html                     | 142 ++++++++++--------
 .../Definitions/Dictionary-Definitions.adoc   |   6 +-
 ...-Framework-and-Dictionary-Definitions.adoc |  56 -------
 docs/users-guide/Dictionary-Definitions.adoc  |  70 +++++++++
 .../Specifying-Models-as-Files.adoc           |   4 +-
 docs/users-guide/defs.sh                      |   2 +-
 7 files changed, 163 insertions(+), 127 deletions(-)
 delete mode 100644 docs/users-guide/Defining-Framework-and-Dictionary-Definitions.adoc
 create mode 100644 docs/users-guide/Dictionary-Definitions.adoc

diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html
index 1d1a4b22a..4992759a6 100644
--- a/docs/fpp-spec.html
+++ b/docs/fpp-spec.html
@@ -4391,10 +4391,6 @@ the definition in the ground dictionary.</p>
 <div class="sect3">
 <h4 id="Definitions_Dictionary-Definitions_Semantics">5.16.1. Semantics</h4>
 <div class="paragraph">
-<p>If a type definition <em>D</em> is a dictionary definition, then the type
-defined by <em>D</em> must be a <a href="#Types_Displayable-Types">displayable type</a>.</p>
-</div>
-<div class="paragraph">
 <p>If a constant definition <em>D</em> is a dictionary definition, then the
 expression appearing in <em>D</em> must have one of the following types:</p>
 </div>
@@ -4414,6 +4410,10 @@ expression appearing in <em>D</em> must have one of the following types:</p>
 </li>
 </ul>
 </div>
+<div class="paragraph">
+<p>If a type definition <em>D</em> is a dictionary definition, then the type
+defined by <em>D</em> must be a <a href="#Types_Displayable-Types">displayable type</a>.</p>
+</div>
 </div>
 <div class="sect3">
 <h4 id="Definitions_Dictionary-Definitions_Examples">5.16.2. Examples</h4>
@@ -12037,7 +12037,7 @@ equivalent.</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-10-30 17:14:10 -0700
+Last updated 2025-11-02 13:05:24 -0800
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>
diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html
index 1f567225a..571db8928 100644
--- a/docs/fpp-users-guide.html
+++ b/docs/fpp-users-guide.html
@@ -513,12 +513,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#Defining-Enums_The-Default-Value">7.5. The Default Value</a></li>
 </ul>
 </li>
-<li><a href="#Defining-Framework-and-Dictionary-Definitions">8. Defining Framework and Dictionary Definitions</a>
-<ul class="sectlevel2">
-<li><a href="#Defining-Framework-and-Dictionary-Definitions_Framework-Definitions">8.1. Framework Definitions</a></li>
-<li><a href="#Defining-Framework-and-Dictionary-Definitions_Dictionary-Definitions">8.2. Dictionary Definitions</a></li>
-</ul>
-</li>
+<li><a href="#Dictionary-Definitions">8. Dictionary Definitions</a></li>
 <li><a href="#Defining-Ports">9. Defining Ports</a>
 <ul class="sectlevel2">
 <li><a href="#Defining-Ports_Port-Names">9.1. Port Names</a></li>
@@ -3298,72 +3293,99 @@ use appears inside the enum where it is defined.</p>
 </div>
 </div>
 <div class="sect1">
-<h2 id="Defining-Framework-and-Dictionary-Definitions">8. Defining Framework and Dictionary Definitions</h2>
+<h2 id="Dictionary-Definitions">8. Dictionary Definitions</h2>
 <div class="sectionbody">
-<div class="sect2">
-<h3 id="Defining-Framework-and-Dictionary-Definitions_Framework-Definitions">8.1. Framework Definitions</h3>
 <div class="paragraph">
-<p><strong>Framework definitions</strong> are type and constant definitions that
-are specially used by the F Prime Framework. If a model defines
-framework definitions, they must conform to the rules described
-in the the <em>FPP Specification</em>.</p>
+<p>One of the artifacts generated from an FPP model is a <strong>dictionary</strong>
+that tells the ground data system how to interpret and display
+the data produced by the FSW.
+By default, the dictionary contains representations of the following
+types and constants defined in FPP:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Types and constants that are known to the framework and that are
+needed by every dictionary, e.g., <code>FwOpcodeType</code>.</p>
+</li>
+<li>
+<p>Types and constants that appear in the definitions of the data produced
+by the FSW, e.g., event specifiers or telemetry specifiers.
+(In later sections of this manual we will explain how to define
+<a href="#Defining-Components_Events">event reports</a> and
+<a href="#Defining-Components_Telemetry">telemetry channels</a>.)</p>
+</li>
+</ul>
 </div>
 <div class="paragraph">
-<p>To write a framework definition, we write the type or constant
-and ensure that the definition follows the rules for that
-framework definition.</p>
+<p>Sometimes you will need the dictionary to include the definition of a type or
+constant
+that does not satisfy either of these conditions.
+For example, a downlink configuration parameter may be
+shared by the FSW implementation and the GDS and may be otherwise unused
+in the FPP model.</p>
 </div>
 <div class="paragraph">
-<p>For example, to write the <code>FwDpIdType</code> framework definition,
-we would write an alias <code>FwDpIdType</code> that represents an
-integer type:</p>
+<p>In this case you can mark a type or constant definition as a <strong>dictionary
+definition</strong>.
+A dictionary definition tells the FPP analyzer two things:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>The definition should be included in the model, even if it
+isn&#8217;t used anywhere in the model.</p>
+</li>
+<li>
+<p>Whenever a dictionary is generated from the model, the definition should be
+included in the dictionary.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>To write a dictionary definition, you write the keyword <code>dictionary</code>
+before the definition.
+You can do this for a constant definition, a type definition,
+or an enum definition.
+For example:</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">type FwDpIdType = U32</code></pre>
+<pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = 1
+dictionary array A = [3] U32
+dictionary struct S { x: U32, y: F32 }
+dictionary type T = S
+dictionary enum E { A, B }</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>To write the <code>Fw.DpCfg.CONTAINER_USER_DATA_SIZE</code> framework definition,
-we would define modules <code>Fw</code> and <code>DpCfg</code> and write a constant
-<code>CONTAINER_USER_DATA_SIZE</code> with an integer type:</p>
+<p>Each dictionary definition must observe the following rules:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>A dictionary constant definition must have a numeric value (integer or
+floating point),
+a Boolean value (true or false), a string value such as <code>"abc"</code>, or an
+enumerated constant value such as <code>E.A</code>.</p>
+</li>
+<li>
+<p>A dictionary type definition must define a <strong>displayable type</strong>, i.e., a
+type that the F Prime ground data system knows how to display.
+For example, the type may not be an
+<a href="#Defining-Types_Abstract-Type-Definitions">abstract type</a>.
+Nor may it be an array or struct type that has an abstract type
+as a member type.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>For example, the following dictionary definitions are invalid:</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">module Fw {
-    module DpCfg {
-        constant CONTAINER_USER_DATA_SIZE = 1
-    }
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="Defining-Framework-and-Dictionary-Definitions_Dictionary-Definitions">8.2. Dictionary Definitions</h3>
-<div class="paragraph">
-<p>An FPP model may include type and constant definitions
-that are <strong>dictionary definitions</strong>. These definitions describe
-type and constant definitions that will be output to the
-dictionary.</p>
-</div>
-<div class="paragraph">
-<p>To write a dictionary definition, prefix an array, struct,
-alias, or constant definition with the <code>dictionary</code> keyword.
-For example, to define a constant dictionary definition
-we write the following:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = 1</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>To define an array dictionary definition, we write the following:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">dictionary array a = [3] U32</code></pre>
-</div>
+<pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = { x = 1, y = 2.0 } # Error: a has struct type
+dictionary type T # Error: T is an abstract type</code></pre>
 </div>
 </div>
 </div>
@@ -12559,8 +12581,8 @@ is <code>b.fpp</code>, not <code>a.fppi</code>.</p>
 <div class="sect3">
 <h4 id="Specifying-Models-as-Files_Location-Specifiers_Dictionary-Specifiers">15.4.5. Dictionary Specifiers</h4>
 <div class="paragraph">
-<p>Dictionary specifiers define the location of constant or type
-<a href="#Defining-Framework-and-Dictionary-Definitions">dictionary definitions</a>.
+<p>A <strong>dictionary specifier</strong> defines the location of a
+<a href="#Dictionary-Definitions">dictionary definition</a>.
 To write a dictionary specifier, write a location specifier and include
 the <code>dictionary</code> keyword before the <code>constant</code> or <code>type</code> keyword.</p>
 </div>
@@ -16022,7 +16044,7 @@ serialized according to its
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-11-02 12:36:42 -0800
+Last updated 2025-11-02 13:13:09 -0800
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>
diff --git a/docs/spec/Definitions/Dictionary-Definitions.adoc b/docs/spec/Definitions/Dictionary-Definitions.adoc
index c02132cff..67067d306 100644
--- a/docs/spec/Definitions/Dictionary-Definitions.adoc
+++ b/docs/spec/Definitions/Dictionary-Definitions.adoc
@@ -8,9 +8,6 @@ the definition in the ground dictionary.
 
 ==== Semantics
 
-If a type definition _D_ is a dictionary definition, then the type
-defined by _D_ must be a <<Types_Displayable-Types, displayable type>>.
-
 If a constant definition _D_ is a dictionary definition, then the
 expression appearing in _D_ must have one of the following types:
 
@@ -19,6 +16,9 @@ expression appearing in _D_ must have one of the following types:
 * A <<Types_String-Types,string type>>.
 * An <<Types_Enum-Types,enum type>>.
 
+If a type definition _D_ is a dictionary definition, then the type
+defined by _D_ must be a <<Types_Displayable-Types, displayable type>>.
+
 ==== Examples
 
 [source,fpp]
diff --git a/docs/users-guide/Defining-Framework-and-Dictionary-Definitions.adoc b/docs/users-guide/Defining-Framework-and-Dictionary-Definitions.adoc
deleted file mode 100644
index 7cf0d8c20..000000000
--- a/docs/users-guide/Defining-Framework-and-Dictionary-Definitions.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-== Defining Framework and Dictionary Definitions
-
-=== Framework Definitions
-*Framework definitions* are type and constant definitions that 
-are specially used by the F Prime Framework. If a model defines 
-framework definitions, they must conform to the rules described 
-in the the _FPP Specification_.
-
-To write a framework definition, we write the type or constant
-and ensure that the definition follows the rules for that
-framework definition.
-
-For example, to write the `FwDpIdType` framework definition, 
-we would write an alias `FwDpIdType` that represents an
-integer type:
-
-[source,fpp]
-----
-type FwDpIdType = U32
-----
-
-To write the `Fw.DpCfg.CONTAINER_USER_DATA_SIZE` framework definition, 
-we would define modules `Fw` and `DpCfg` and write a constant
-`CONTAINER_USER_DATA_SIZE` with an integer type:
-
-[source,fpp]
-----
-module Fw {
-    module DpCfg {
-        constant CONTAINER_USER_DATA_SIZE = 1
-    }
-}
-----
-
-=== Dictionary Definitions
-
-An FPP model may include type and constant definitions
-that are *dictionary definitions*. These definitions describe
-type and constant definitions that will be output to the 
-dictionary.
-
-To write a dictionary definition, prefix an array, struct, 
-alias, or constant definition with the `dictionary` keyword.
-For example, to define a constant dictionary definition 
-we write the following:
-
-[source,fpp]
-----
-dictionary constant a = 1
-----
-
-To define an array dictionary definition, we write the following:
-[source,fpp]
-----
-dictionary array a = [3] U32
-----
diff --git a/docs/users-guide/Dictionary-Definitions.adoc b/docs/users-guide/Dictionary-Definitions.adoc
new file mode 100644
index 000000000..a8eef96c9
--- /dev/null
+++ b/docs/users-guide/Dictionary-Definitions.adoc
@@ -0,0 +1,70 @@
+== Dictionary Definitions
+
+One of the artifacts generated from an FPP model is a *dictionary*
+that tells the ground data system how to interpret and display
+the data produced by the FSW.
+By default, the dictionary contains representations of the following
+types and constants defined in FPP:
+
+* Types and constants that are known to the framework and that are
+needed by every dictionary, e.g., `FwOpcodeType`.
+
+* Types and constants that appear in the definitions of the data produced
+by the FSW, e.g., event specifiers or telemetry specifiers.
+(In later sections of this manual we will explain how to define
+<<Defining-Components_Events,event reports>> and
+<<Defining-Components_Telemetry,telemetry channels>>.)
+
+Sometimes you will need the dictionary to include the definition of a type or 
+constant
+that does not satisfy either of these conditions.
+For example, a downlink configuration parameter may be
+shared by the FSW implementation and the GDS and may be otherwise unused
+in the FPP model.
+
+In this case you can mark a type or constant definition as a *dictionary 
+definition*.
+A dictionary definition tells the FPP analyzer two things:
+
+. The definition should be included in the model, even if it
+isn't used anywhere in the model.
+
+. Whenever a dictionary is generated from the model, the definition should be
+included in the dictionary.
+
+To write a dictionary definition, you write the keyword `dictionary`
+before the definition.
+You can do this for a constant definition, a type definition,
+or an enum definition.
+For example:
+
+[source,fpp]
+----
+dictionary constant a = 1
+dictionary array A = [3] U32
+dictionary struct S { x: U32, y: F32 }
+dictionary type T = S
+dictionary enum E { A, B }
+----
+
+Each dictionary definition must observe the following rules:
+
+. A dictionary constant definition must have a numeric value (integer or 
+floating point),
+a Boolean value (true or false), a string value such as `"abc"`, or an 
+enumerated constant value such as `E.A`.
+
+. A dictionary type definition must define a *displayable type*, i.e., a
+type that the F Prime ground data system knows how to display.
+For example, the type may not be an
+<<Defining-Types_Abstract-Type-Definitions,abstract type>>.
+Nor may it be an array or struct type that has an abstract type
+as a member type.
+
+For example, the following dictionary definitions are invalid:
+
+[source,fpp]
+--------
+dictionary constant a = { x = 1, y = 2.0 } # Error: a has struct type
+dictionary type T # Error: T is an abstract type
+--------
diff --git a/docs/users-guide/Specifying-Models-as-Files.adoc b/docs/users-guide/Specifying-Models-as-Files.adoc
index 081e577c8..e1f80171e 100644
--- a/docs/users-guide/Specifying-Models-as-Files.adoc
+++ b/docs/users-guide/Specifying-Models-as-Files.adoc
@@ -399,8 +399,8 @@ is `b.fpp`, not `a.fppi`.
 
 ==== Dictionary Specifiers
 
-Dictionary specifiers define the location of constant or type
-<<Defining-Framework-and-Dictionary-Definitions,dictionary definitions>>. 
+A *dictionary specifier* defines the location of a
+<<Dictionary-Definitions,dictionary definition>>. 
 To write a dictionary specifier, write a location specifier and include 
 the `dictionary` keyword before the `constant` or `type` keyword.
 
diff --git a/docs/users-guide/defs.sh b/docs/users-guide/defs.sh
index 224ef4b5c..5815f126f 100644
--- a/docs/users-guide/defs.sh
+++ b/docs/users-guide/defs.sh
@@ -17,7 +17,7 @@ Writing-Comments-and-Annotations.adoc
 Defining-Modules.adoc
 Defining-Types.adoc
 Defining-Enums.adoc
-Defining-Framework-and-Dictionary-Definitions.adoc
+Dictionary-Definitions.adoc
 Defining-Ports.adoc
 Defining-State-Machines.adoc
 Defining-Components.adoc