resource-yaml-creation

name	resource-yaml-creation
description	Guidance for creating ado resource YAML files (discoveryspace, operation, actuatorconfiguration, samplestore, document). Covers metadata conventions, dynamic reference resolution with --use-latest/--with/--set, space design principles, avoiding duplicate resources, document reports, and validation. Use when creating or editing any ado resource YAML file.

Creating ado Resource YAML Files

For CLI command syntax, see using-ado-cli. For full problem formulation workflow, see formulate-discovery-problem.

Metadata Fields

Every resource YAML should include a metadata block. The CLI uses these for display (ado get --details) and filtering (ado get --label, ado get --filter).

metadata:
  name: my_space # short human-readable identifier
  description: | # longer explanation of purpose
    Optimize learning rate and batch size for ResNet training.
  labels:
    project: my_project # arbitrary key=value pairs for filtering
    team: ml_team

• name and description are shown by ado get --details
• labels support filtering: uv run ado get spaces --label project=my_project
• --filter supports path-based filtering across any field: uv run ado get spaces --filter 'config.metadata.name=my_space'

The provisional label

Set provisional at creation time when a space or operation is known not to be meant for keeping long-term:

metadata:
  labels:
    provisional: true
    provisonal_reason: testing

Use provisional_reason to record the reason with one of the following:

• testing — created to test some new functionality.
• debug — created to debug a problem.
• temporary — generic indicator that it's not meant to be kept.

Dynamic Reference Resolution

Resource YAMLs often reference other resources by ID. Leave these as placeholders and resolve them at creation time — do not hard-code IDs.

--use-latest

Queries the current context's metastore to find the most recently created resource of the given type.

# Create space, then operation that references it — no manual ID copy
uv run ado create space -f space.yaml
uv run ado create operation -f operation.yaml --use-latest space

--with

Creates a dependency inline and injects its ID automatically.

# Create space + actuatorconfiguration + operation in one command
# Note: You cannot use --with store=store.yaml or store_id here
# The space must use default store or have a valid store_id in the YAML
uv run ado create operation -f operation.yaml \
  --with space=space.yaml \
  --with actuatorconfiguration=config.yaml

Note: Can also specify resources ids to --with

uv run ado create operation -f operation.yaml \
  --with space=space-abcd-1234

--set

Overrides individual fields in the YAML at creation time without editing the file. Useful for environment-specific values or quick one-off changes.

# Override the sample store identifier
uv run ado create space -f space.yaml --set sampleStoreIdentifier=my_store

# Override a nested field using dot notation
uv run ado create operation -f operation.yaml --set parameters.budget=100

--set takes path=JSON_document pairs and can be used multiple times.

Validation

Always validate before creating:

uv run ado create RESOURCETYPE -f FILE --dry-run

--dry-run validates the YAML without creating the resource.

Templates

Use ado template to generate a starter YAML for any resource type:

# Generic discoveryspace template
uv run ado template discoveryspace

# Space template pre-filled for a specific experiment
uv run ado template discoveryspace --from-experiment my_experiment

# Operation template for a specific operator
uv run ado template operation --operator-name ray_tune

# ActuatorConfiguration template for a specific actuator
uv run ado template actuatorconfiguration --actuator-identifier my_actuator

Resource-Specific Guidance

DiscoverySpace

See formulate-discovery-problem for further details on creating discovery spaces.

Before creating (ado create space), check if a matching space already exists:

# Match by space config (entity space + experiments)
uv run ado get spaces --matching-space space.yaml

# Match by space ID
uv run ado get spaces --matching-space-id space-abc123

# Filter by label
uv run ado get spaces --label project=my_project --details

Reuse an existing space rather than creating a new one — it means the new operation benefits from measurements already collected.

Constitutive properties vs. parameterization:

• Declare a property as a constitutive property domain in the entity space when you want to explore a range of values for that property.
• Use experiment parameterization when you want to change the default value of an optional experiment property but keep it fixed across all entities. Do not add a single-valued domain to the entity space just to override a default.

# Correct: parameterization overrides experiment default, keeps it out of space
experiments:
  - actuatorIdentifier: trainer
    experimentIdentifier: train_model
    parameterization:
      - property:
          identifier: optimizer
        value: adam # overrides default "sgd"

# Incorrect: single-valued domain should be parameterization instead
entitySpace:
  - identifier: optimizer
    propertyDomain:
      variableType: DISCRETE_VARIABLE_TYPE
      values: [adam] # single value — use parameterization instead

Creating a space with a fresh samplestore:

uv run ado create space -f space.yaml --new-sample-store

ActuatorConfiguration

Before creating, check if a compatible configuration already exists:

uv run ado get actuatorconfigurations --details
uv run ado get actuatorconfigurations --label actuator=my_actuator

Reuse an existing actuator configuration when appropriate rather than creating duplicates.

SampleStore

You rarely need to create a samplestore explicitly. Every project comes with a default samplestore that is suitable for most use cases.

Create a new samplestore only when you explicitly want a clean slate with no shared measurement history.

uv run ado create samplestore -f samplestore.yaml

Document

Use document resources to persist markdown or HTML reports in the metastore. Set contentType to markdown (default) or html. See the document resource documentation.

The description above is sufficient for creating document resources. Only consult the source for advanced options not covered here: read docs/resources/document.md if the source repo is available, otherwise see https://ibm.github.io/ado/latest/resources/document/. Examining skills store their reports this way: put the body in content, optionally set contentType, and list related resources in relatedResources with id and role (parent = report is about that resource; child = resource created in response to the document).

# <descriptive>_document.yaml  (temp file, not committed)
metadata:
  name: "<descriptive name>"
  description: "<one-line summary>"
contentType: markdown  # or html
content: |
  <full report text>
relatedResources:
  - id: <related resource id>
    role: parent

uv run ado create document -f <descriptive>_document.yaml
uv run ado delete document DOCUMENT_ID

Validate with uv run ado create document -f FILE --dry-run before creating.

Querying existing documents (paths are under config.; string candidates must be single-quoted — see query-ado-data):

# By related resource id
uv run ado get document -q 'config.relatedResources.id=RESOURCE_ID'

# By metadata name
uv run ado get document -q 'config.metadata.name=NAME'

Fetch a document's body with uv run ado get document DOCUMENT_ID -o yaml.

When replacing a report, delete the existing document only after the user agrees and the new report has been created (or immediately before creating the replacement, if the skill's replace policy says so).

Related Resources

• using-ado-cli — CLI command syntax and shortcuts
• formulate-discovery-problem — full problem formulation workflow
• AGENTS.md — YAML testing and linting guidance