diff --git a/stackspec/schema/StackSpecContainerConfigIntegrations.yml b/stackspec/schema/StackSpecContainerConfigIntegrations.yml
index fbdd812f..4a3b7ff2 100644
--- a/stackspec/schema/StackSpecContainerConfigIntegrations.yml
+++ b/stackspec/schema/StackSpecContainerConfigIntegrations.yml
@@ -97,10 +97,25 @@ properties:
             - destination
           properties:
             source:
+              description: 
+                Endpoint serving the file(s) to provision into the container.
+
+                The following query parameters are recognized by Cycle and are
+                stripped before the request is made upstream
+                  - cycle-cache (duration string) — how long Cycle may serve its
+                    cached copy of the file before re-fetching from the origin.
+                    Accepts a duration such as 30m, 10h, or 2d.
+                  - cycle-version (string) — an opaque version identifier for the
+                    file. Changing it invalidates the cached copy.
+                Both may be combined with any query parameters the origin expects.
               oneOf:
                 - $ref: StackVariable.yml
                 - type: string
+              examples:
+                - https://example.com/config/app.conf?cycle-cache=10h&cycle-version=v2.1.1           
             destination:
+              description:
+                File path for the files to be downloaded to on the container instance(s).
               oneOf:
                 - type: string
                 - $ref: StackVariable.yml
diff --git a/stackspec/schema/StackVariable.yml b/stackspec/schema/StackVariable.yml
index 882f24c3..7b0ff029 100644
--- a/stackspec/schema/StackVariable.yml
+++ b/stackspec/schema/StackVariable.yml
@@ -1,5 +1,20 @@
 title: StackVariable
-description: A variable specified in a stack spec.
+description:
+  A variable specified in a stack spec. At deploy time the placeholder is replaced with the value supplied for that variable.
+
+  Two substitution forms are available
+
+  - "{{stack-variable}}" — **string substitution.** The value is inserted as a
+    JSON string. Passing 1 yields "1".
+  - "{{$stack-variable}}" — **literal substitution.** The value is inserted
+    verbatim, including the surrounding quotes, so it keeps its own JSON type.
+    Given instances "{{$stack-variable}}" and a passed value of 1, the
+    resulting JSON is instances 1 — a number, not a string. Use this form for
+    numbers, booleans, arrays, and objects.
+
+  In both forms the placeholder must be wrapped in quotes wherever it appears in
+  the JSON. An unquoted placeholder is not valid JSON/YAML and will break the
+  surrounding document before substitution can run.
 pattern: '"?\{\{(\$)?([a-z0-9-]+)\}\}"?'
 type: string
 examples: