Updraft ConfigConfiguration StableSince v1.0

Updraft::Config::Lookup

Extracts a single value from an Updraft::Config::Document and exposes it as a template attribute, with an optional default, a type assertion, and a clear failure when the path is not there.

Required properties 2 of 8

Ref returns Resolved value30

Fn::GetAtt 3 attributes

Replacement risk None no property forces replacement

Minimal template

Every required property, nothing else

Resources:
  RetentionDays:
    Type: Updraft::Config::Lookup
    Properties:
      Document: !Ref AppConfig
      Path: /retention/days

{
  "Resources": {
    "RetentionDays": {
      "Type": "Updraft::Config::Lookup",
      "Properties": {
        "Document": { "Ref": "AppConfig" },
        "Path": "/retention/days"
      }
    }
  }
}

Overview #

A lookup pulls one value out of a document. It is intentionally small: a path, an optional default, and a type assertion. Everything harder — merging, redaction, validation — belongs to the document.

The type assertion is the part worth understanding. A configuration file is untyped text until something decides what a value means, and the usual failure is that nothing does: a port number arrives as the string "5432", gets concatenated into a connection string, and works; then a retention value arrives as the string "30", gets compared against a number, and silently evaluates false. Declaring Type moves that failure from runtime to deploy time, where it names the path and both types.

Paths #

Paths are RFC 6901 JSON Pointers. The rules that matter in practice:

Pointer	Selects
`/retention/days`	The `days` key inside the `retention` object.
`/servers/0/host`	The `host` key of the first array element.
`/featureFlags/*`	Every value at that level, as a list.
`/a~1b`	A top-level key literally named `a/b`.
`/a~0b`	A top-level key literally named `a~b`.

Turning a map into a list #

A wildcard path plus Type: StringList is the idiomatic way to feed a StringList parameter or a comma-separated property.

Document

allowedOrigins:
  app: https://app.acme.example
  admin: https://admin.acme.example
  status: https://status.acme.example

Lookup

Resources:
  Origins:
    Type: Updraft::Config::Lookup
    Properties:
      Document: !Ref AppConfig
      Path: /allowedOrigins/*
      Type: StringList

!Ref Origins → https://admin.acme.example,https://app.acme.example,https://status.acme.exampleordered by key, not by document order

Properties

Expand a row for the full reference; nested types open in place

Document StringThe document ID returned by Ref on an Updraft::Config::Document. Required No interruption — updates in place
Written as !Ref AppConfig in practice. Referencing the document this way also establishes the dependency, so the lookup cannot run before the document has been read.
Type
String
Required
Yes
Update behaviour
No interruption
Example values
- doc-2f8a1c94
Path StringJSON Pointer to the value, with an optional trailing wildcard for collection lookups. Required No interruption — updates in place
Array elements are addressed by index: /servers/0/host. A trailing /* collects every value at that level into a list, which is how you turn a map of feature flags into a StringList.
Type
String
Required
Yes
Update behaviour
No interruption
Pattern
^/([^/~]|~[01])*(/([^/~]|~[01])*)*$ RFC 6901 JSON Pointer. `~0` escapes a literal `~`, `~1` escapes a literal `/`.
Length
1 – 512
Example values
- /retention/days
- /tenants/acme/region
- /featureFlags/*
A key containing a slash is not a path segment
JSON Pointer separates segments with /, so a key that contains a slash — very common for parameter-style keys like /acme/db/host — must escape it as ~1. Looking up the key a/b at the document root is /a~1b, not /a/b; the latter descends two levels and finds nothing.
Default StringValue to use when the path is absent. Supplying it makes the lookup non-fatal. No interruption — updates in place
Written as a string and then coerced according to Type. A Default of "0" with Type: Number yields the number zero, not the string.
Type
String
Required
No
Update behaviour
No interruption
Example values
- 30
Note
Default applies when the path is absent. It does not apply when the path is present and null — use TreatNullAsMissing for that.
Required BooleanWhether an absent path with no Default fails the stack operation. No interruption — updates in place
Whether an absent path with no Default fails the stack operation.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
true
Sensitive BooleanMarks the resolved value as sensitive, keeping it out of events and drift output. No interruption — updates in place Write-only
A sensitive lookup still exposes Value, because a resource that could not return its value would be useless — but the value is omitted from CloudFormation events, from DescribeStackResources, and from drift detection output.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
false
Warning
This does not make the value secret. Anything that can read the stack’s resolved template or the resource it feeds can still see it. For real secrets, keep the value in Secrets Manager and reference it with a dynamic reference, so it is never materialised in the template at all.
Transform Array of StringOrdered transformations applied to the resolved value. No interruption — updates in place
Applied left to right, after coercion. Only meaningful for String.
Type
Array of String
Required
No
Update behaviour
No interruption
Items
0 – 4
Allowed values
- Trim
- Lower
- Upper
- Base64Encode
- Base64Decode
- UrlEncode
Example values
- ["Trim","Lower"]
TreatNullAsMissing BooleanWhether an explicit null at the path counts as absent. No interruption — updates in place
A YAML key written as days: with nothing after it parses to null. Whether that means “unset, use the default” or “explicitly nothing” depends on the document’s conventions, so it is a decision this property makes visible instead of guessing.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
false
Type StringAsserts and coerces the value's type. No interruption — updates in place
The assertion runs before coercion. A value that cannot be coerced fails the stack operation naming the path and both types, rather than passing a malformed value downstream.
StringList accepts a JSON array of scalars or a wildcard path result and renders it comma-separated, ready for an SSM StringList parameter. Json returns the subtree verbatim as a JSON string.
Type
String
Required
No
Update behaviour
No interruption
Default
String
Allowed values
- String
- Number
- Boolean
- StringList
- Json

Property	Type	Required	Update	Description
Document	`String`	Yes	None	The document ID returned by Ref on an Updraft::Config::Document.
Path	`String`	Yes	None	JSON Pointer to the value, with an optional trailing wildcard for collection lookups.
Default	`String`	No	None	Value to use when the path is absent. Supplying it makes the lookup non-fatal.
Required	`Boolean`	No	None	Whether an absent path with no Default fails the stack operation.
Sensitive	`Boolean`	No	None	Marks the resolved value as sensitive, keeping it out of events and drift output.
Transform	`Array of String`	No	None	Ordered transformations applied to the resolved value.
TreatNullAsMissing	`Boolean`	No	None	Whether an explicit null at the path counts as absent.
Type	`String`	No	None	Asserts and coerces the value's type.

Generated from the schema. The first pair shows only required and conditionally-required properties — a template you can paste and deploy. Property keys are ordered alphabetically here rather than required-first, because that is the order a template file conventionally uses.

Type: Updraft::Config::Lookup
Properties:
  Document: doc-2f8a1c94
  Path: /retention/days

{
  "Type": "Updraft::Config::Lookup",
  "Properties": {
    "Document": "doc-2f8a1c94",
    "Path": "/retention/days"
  }
}

Every property, three levels deep:

Type: Updraft::Config::Lookup
Properties:
  Default: '30'
  Document: doc-2f8a1c94
  Path: /retention/days
  Required: true
  Sensitive: false
  Transform:
  - String
  TreatNullAsMissing: false
  Type: String

{
  "Type": "Updraft::Config::Lookup",
  "Properties": {
    "Default": "30",
    "Document": "doc-2f8a1c94",
    "Path": "/retention/days",
    "Required": true,
    "Sensitive": false,
    "Transform": [
      "String"
    ],
    "TreatNullAsMissing": false,
    "Type": "String"
  }
}

updates in place some interruption replacement create-only read-only write-only

Return values

What other resources can read from this one

Ref

Returns the resolved value directly — !Ref RetentionDays is the value, not a handle. This is deliberate: a lookup exists to be substituted into another property, and requiring Fn::GetAtt for the common case would be noise.

!Ref MyResource → 30

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
Found	`Boolean`	Whether the path existed in the document. False when the Default was used.	`true`
ResolvedType	`String`	The value’s type as found in the document, before coercion. Useful when a lookup fails a type assertion.	`Number`
Value	`String`	The resolved value, coerced and transformed. Lists are comma-separated.	`30`

Required permissions

For the principal running the stack operation

This type makes no AWS API calls. It is computed entirely from its own properties during the stack operation, so it needs no permissions beyond those CloudFormation already holds to manage the stack.