Metadata

The metadata() block defines scenario-level information and declares the external objects used by the scenario.

A typical metadata block looks like:

metadata() >
    name("ExampleEnvironment"),
    eventType("sequence"),
    repositoryRemote("https://172.18.178.10:4443"),
    object("InitializationScript").

Metadata properties

Property	Arguments	Status	Description
name	Scenario name	Schema required	Human-readable identifier for the scenario.
eventType	sequence	Schema required	Selects the supported sequential event model. CradleXC defaults to sequence when omitted.
repositoryRemote	URI	Optional	Defines the base location for remotely stored artifacts.
repositoryLocal	Location	Optional	Defines the base location for locally available artifacts.
ssh_credential	Username, password	Optional	Supplies SSH credentials when the selected workflow requires them.
object	Object name	Optional	Declares an artifact used by the scenario. Repeat for multiple objects.
heuristic	Framework, identifier	Optional	Associates a classification or framework identifier with the scenario.

Scenario name

Use name() to identify the scenario.

metadata() >
    name("ExampleEnvironment").

For example:

name("HelloWorld")

The name is used as the human-readable identifier for the scenario.

important

Use a stable scenario name and keep its spelling and capitalization consistent wherever it is referenced.

Event type

Use eventType() to define the event model used by the scenario.

The supported value is:

sequence

For example:

metadata() >
    eventType("sequence").

Sequential events

A sequential event model uses:

eventType("sequence")

This indicates that the scenario uses sequential event handling.

The Hello World scenario uses this form:

metadata() >
    name("HelloWorld"),
    eventType("sequence"),
    repositoryRemote("https://172.18.178.10:4443"),
    object("HelloWorld").

Event dependencies

Keep eventType("sequence") and express explicit ordering relationships with dependsOn() inside event definitions.

Detailed dependency behavior is covered in Events and Dependencies.

note

CradleXC currently defaults to sequence when eventType() is omitted.

Remote artifact repository

Use repositoryRemote() to define the base location for remotely stored artifacts.

For example:

metadata() >
    repositoryRemote("https://172.18.178.10:4443").

Objects can reference this repository through interpolation.

For example:

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

Here:

${uriRemote}

refers to the configured remote repository location.

This allows the repository base path to be defined once and reused by object definitions.

important

Repository values identify artifact locations. Do not place credentials, access tokens or other secrets directly in the repository URI.

Local artifact repository

CradleXC also recognizes:

repositoryLocal("...")

for locally available artifacts.

For example:

metadata() >
    repositoryLocal("/path/to/artifacts").

Objects can reference this value with ${uriLocal}.

SSH credentials

When a workflow requires SSH credentials, provide the username and password as two strings:

metadata() >
    ssh_credential("cradle", "replace-with-a-secret").

Avoid committing real credentials to source control.

Scenario heuristics

Metadata can carry scenario-level heuristic annotations:

metadata() >
    heuristic("ttp", "T1566.001").

See Heuristic Annotations for the supported frameworks and validation behavior.

Declare objects

Objects used by the scenario are declared in metadata().

For example:

metadata() >
    object("InitializationScript").

Multiple objects can be declared by repeating the property:

metadata() >
    name("ExampleEnvironment"),
    eventType("sequence"),
    repositoryRemote("https://172.18.178.10:4443"),
    object("InitializationScript"),
    object("CollectEvidence"),
    object("CleanupScript").

Each declared object should have a corresponding named object definition.

For example:

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

and:

object("CollectEvidence") >
    location("${uriRemote}/scripts/collect-evidence.sh").

Declaration and definition

Declaring an object in metadata() does not define its location.

For example:

metadata() >
    object("InitializationScript").

declares the object.

The corresponding object block defines it:

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

Conceptually:

metadata()

↓

object("InitializationScript") declaration

↓

object("InitializationScript") definition

↓

Artifact location

important

Object names must match exactly between metadata declarations, object definitions, instance associations and event references.

Complete example

The following metadata block defines a scenario with one remote repository and one external object:

metadata() >
    name("ExampleEnvironment"),
    eventType("sequence"),
    repositoryRemote("https://172.18.178.10:4443"),
    object("InitializationScript").

The associated object definition is:

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

The relationship is:

Element	Value
Scenario name	ExampleEnvironment
Event type	sequence
Remote repository	https://172.18.178.10:4443
Declared object	InitializationScript
Object location	${uriRemote}/scripts/initialize.sh

Hello World metadata

The Hello World example uses:

metadata() >
    name("HelloWorld"),
    eventType("sequence"),
    repositoryRemote("https://172.18.178.10:4443"),
    object("HelloWorld").

This:

1. names the scenario HelloWorld
2. selects sequential event handling
3. defines the remote artifact repository
4. declares the HelloWorld object

The corresponding object is:

object("HelloWorld") >
    location("${uriRemote}/TTP/HelloWorld/artifact/HelloWorld.sh").

note

This value matches the canonical HelloWorld.cradle file. Use only an authorized and reachable artifact repository in your own scenario.

Repository interpolation

A repository value can be reused through interpolation.

For example:

metadata() >
    repositoryRemote("https://172.18.178.10:4443"),
    object("InitializationScript").

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

The object location is constructed from:

${uriRemote}

plus:

/scripts/initialize.sh

Conceptually:

Repository basehttps://172.18.178.10:4443

+

Artifact path/scripts/initialize.sh

combine↓

Resolved artifact locationhttps://172.18.178.10:4443/scripts/initialize.sh

Detailed object and interpolation behavior is covered in Objects and Interpolation.

Metadata and other scenario elements

Metadata provides scenario-level values that are used by other sections.

A common relationship is:

metadata()

↓

Declared object

↓

Object definition

↓

Instance association

↓

Event reference

For example:

metadata() >
    object("InitializationScript").

instance("Client") >
    object("InitializationScript").

event("initialize_client") >
    runObject("InitializationScript", "").

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

The same object name connects all four parts.

Schema and compiler behavior

The current parser, validator and compiled representation handle metadata as follows:

Property	Current behavior
name	Required and must be non-empty.
eventType	Defaults to sequence when omitted; sequence is the supported value.
repositoryRemote	Optional. Supplies ${uriRemote} during object-location resolution.
repositoryLocal	Optional. Supplies ${uriLocal} during object-location resolution.
ssh_credential	Optional. Preserved in compiled scenario output.
object	Optional and repeatable. Each declared name must have a matching object definition.
heuristic	Optional and repeatable. Preserved as scenario metadata.

Validate metadata

Validate the scenario with:

cxc validate -i <scenario.cradle>

For example:

cxc validate -i scenarios/HelloWorld.cradle

If validation reports an issue, check:

• the metadata() block syntax
• required properties
• quoted values
• object declarations
• object name consistency
• repository values

For general syntax rules, see Syntax and Types.

Common mistakes

Object declaration does not match the definition

Incorrect:

metadata() >
    object("InitializationScript").

object("InitialisationScript") >
    location("${uriRemote}/scripts/initialize.sh").

The names differ.

Use the same spelling:

metadata() >
    object("InitializationScript").

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh").

Object reference does not match metadata

If metadata contains:

object("InitializationScript")

avoid referencing a different name:

runObject("InitScript", "")

Use:

runObject("InitializationScript", "")

Credentials embedded in repository URLs

Avoid:

repositoryRemote("https://username:password@example.com/repository")

Repository metadata should identify the artifact location without embedding credentials.

Related documentation

• Syntax and Types
• Objects and Interpolation
• Events and Dependencies
• First Scenario
• Deployment IR

Next steps

Continue with Instances and Roles to learn how systems are declared and configured within a CRADLE scenario.