Version: Current

Objects and Interpolation

Objects represent external artifacts used by a CRADLE scenario.

An object is typically:

declared in metadata()
defined in a matching object("name") block
associated with an instance when required
referenced by an event through runObject()

Object locations can also use interpolation such as ${uriRemote} to reuse repository values defined in scenario metadata.

Object properties

The current CRADLE reference documents the following object-related properties:

Property	Arguments	Status	Description
`object`	Object name	Structural	Declares or references an object.
`location`	URI or repository-relative location	Structural	Defines the location of the corresponding artifact.
`heuristic`	Framework, identifier	Compiler extension	Associates the object with an external classification or framework identifier.

Declare an object

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

For example:

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

Here, InitializationScript is the object's shared identifier. This declaration registers the name, but it does not say where the artifact is located. The location belongs in a separate object definition.

Define an object

Each declared object should have a matching named object block.

For example:

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

The definition must use the same object name as the declaration in metadata().

The relationship is:

Declare the objectmetadata() registers the name InitializationScript.

↓

Define the objectobject("InitializationScript") assigns its location().

↓

Resolve the artifactThe location identifies the external file used by the scenario.

important

Object names must match their declarations and references exactly.

Object locations

Use location() to define where the artifact can be found.

For example:

object("InitializationScript") >
    location("https://172.18.178.10:4443/scripts/initialize.sh").

The location can also be built from a repository value defined in metadata:

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

This avoids repeating the complete repository path in every object definition.

Remote repository interpolation

A common object location uses:

${uriRemote}

For example:

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

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

In this example:

${uriRemote}

refers to:

https://172.18.178.10:4443

The resulting artifact location is conceptually:

https://172.18.178.10:4443/scripts/initialize.sh

The base repository is defined once and reused by the object definition.

Why use interpolation

Interpolation helps separate repository configuration from individual artifact paths.

Without interpolation:

object("InitializationScript") >
    location("https://172.18.178.10:4443/scripts/initialize.sh").

object("CollectEvidence") >
    location("https://172.18.178.10:4443/scripts/collect-evidence.sh").

With interpolation:

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

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

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

Changing the repository base then requires changing only:

repositoryRemote("https://172.18.178.10:4443")

rather than every object location.

Multiple objects

A scenario can declare multiple objects.

For example:

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

Each object should have a corresponding definition:

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

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

object("CleanupScript") >
    location("${uriRemote}/scripts/cleanup.sh").

Each object has a unique name and location.

Associate an object with an instance

Instances can reference declared objects using object().

For example:

instance("Client") >
    os("ubuntu", "20.04"),
    object("InitializationScript").

The referenced object should exist in metadata:

metadata() >
    object("InitializationScript").

and should have a matching object definition:

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

The relationship is:

metadata() declaration

↓

object definition

↓

instance association

Reference an object from an event

Events use runObject() to identify the object involved in the event.

For example:

event("initialize_client") >
    instance("Client"),
    needRoot(false),
    subject("bash", ""),
    runObject("InitializationScript", "").

The object name:

InitializationScript

should match the metadata declaration and object definition.

Conceptually:

metadata()

↓

object("InitializationScript")

↓

instance("Client")

↓

event("initialize_client")

↓

runObject("InitializationScript", "")

Object parameters

runObject() accepts a second argument for optional parameters.

For example:

runObject("InitializationScript", "")

uses no additional parameters.

Where parameters are required, use a structured map with typed values.

For example:

runObject(
    "InitializationScript",
    {
        mode = "safe",
        count = 1
    }
)

The meaning of these parameters depends on the object and the execution environment.

Hello World object

The Hello World scenario declares its object in metadata:

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

The object is then associated with the router instance:

instance("router") >
    os("linux", "20.04"),
    object("HelloWorld").

The object definition is:

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

The complete reference path is therefore:

metadata() declares HelloWorld

↓

object("HelloWorld") defines its location

↓

instance("router") associates the object

note

This repository and object path match the canonical HelloWorld.cradle file. Confirm that the repository is authorized and reachable before deployment.

Local repositories

CradleXC also recognizes:

repositoryLocal("...")

as a compiler extension.

This can provide a local base location for artifacts where supported.

For example:

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

The source material provided for the current documentation does not define a complete local interpolation contract equivalent to ${uriRemote}.

For that reason, this page does not prescribe a local interpolation variable.

note

Use local repository behavior only when it is documented for the CradleXC release and environment you are using.

Heuristic annotations

Objects can also include heuristic metadata.

The documented form is:

heuristic("framework", "identifier")

For example:

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

This associates the object with an external classification or framework identifier.

Multiple heuristic annotations can be added by repeating heuristic() where supported.

For example:

object("InitializationScript") >
    location("${uriRemote}/scripts/initialize.sh"),
    heuristic("framework-a", "ID-001"),
    heuristic("framework-b", "ID-002").

Heuristic annotations do not replace the object definition.

See Heuristics for more information.

Reference consistency

Object names can appear in several places.

For example:

metadata() >
    object("InitializationScript").

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

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

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

All four references use:

InitializationScript

A mismatch can break the relationship.

For example:

metadata() >
    object("InitializationScript").

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

The two names are different.

Use:

runObject("InitializationScript", "")

instead.

important

Object names are cross-references. Keep spelling and capitalization consistent everywhere the object is declared, defined, associated or executed.

Repository security

Repository values should identify artifact locations without embedding sensitive credentials.

Avoid values such as:

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

or URLs containing access tokens.

Prefer repository configuration that keeps authentication information outside the CRADLE scenario.

important

Do not store passwords, access tokens or other secrets directly in .cradle source files.

Object and backend responsibilities

A CRADLE object describes an artifact and its location.

How that artifact is represented or consumed in target-specific files can depend on the selected backend.

The relationship is:

CRADLE object definition

↓

CradleXC

↓

Backend plugin

↓

Target-specific artifact reference

The CRADLE language therefore identifies the artifact without defining every target-specific implementation detail.

Schema and compiler behavior

The current CRADLE reference sources are not completely aligned for object-related behavior.

Property	Current behavior
`object` in metadata	Required by the current schema for declared scenario objects.
`object` in an instance	Associates a declared object with the instance.
`location`	Defines the artifact location.
`heuristic`	Recognized by CradleXC as a compiler extension.
`repositoryLocal`	Recognized by CradleXC as a compiler extension.

note

Validate object behavior against the CradleXC release you are using rather than relying on the schema alone.

Validate object references

Validate the scenario with:

cxc validate -i <scenario.cradle>

For example:

cxc validate -i scenarios/HelloWorld.cradle

When investigating an object-related issue, check:

whether the object is declared in metadata()
whether the matching object("name") definition exists
whether location() is present where required
whether object names match exactly
whether instance associations use the correct name
whether runObject() uses the correct object name
whether repository values are configured correctly

Common mistakes

Object is declared but not defined

This declaration:

metadata() >
    object("InitializationScript").

should have a corresponding definition:

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

Object definition uses a different name

Incorrect:

metadata() >
    object("InitializationScript").

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

Use matching names:

metadata() >
    object("InitializationScript").

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

Event references the wrong object

Incorrect:

runObject("InitScript", "")

when the declared object is:

InitializationScript

Use:

runObject("InitializationScript", "")

Repository variable is misspelled

If the documented interpolation value is:

${uriRemote}

avoid using an inconsistent value such as:

${remoteUri}

unless that variable is explicitly supported by the CRADLE release you are using.

Next steps

Continue with Includes for scenario composition features, or Heuristics to learn how classification metadata can be attached to supported CRADLE elements.

Object properties​

Declare an object​

Define an object​

Object locations​

Remote repository interpolation​

Why use interpolation​

Multiple objects​

Associate an object with an instance​

Reference an object from an event​

Object parameters​

Hello World object​

Local repositories​

Heuristic annotations​

Reference consistency​

Repository security​

Object and backend responsibilities​

Schema and compiler behavior​

Validate object references​

Common mistakes​

Object is declared but not defined​

Object definition uses a different name​

Event references the wrong object​

Repository variable is misspelled​

Related documentation​

Next steps​

Object properties

Declare an object

Define an object

Object locations

Remote repository interpolation

Why use interpolation

Multiple objects

Associate an object with an instance

Reference an object from an event

Object parameters

Hello World object

Local repositories

Heuristic annotations

Reference consistency

Repository security

Object and backend responsibilities

Schema and compiler behavior

Validate object references

Common mistakes

Object is declared but not defined

Object definition uses a different name

Event references the wrong object

Repository variable is misspelled

Related documentation

Next steps