Validate SDL from Python¶
Read a local scenario and obtain a validated Scenario for your application.
Before you start¶
Use Python 3.14 and RAES 11.0.2 in a virtual environment.
Save the first scenario
as first-scenario.sdl.yaml in your working directory.
You need read access to that file. No runtime identity is required.
Read and validate a file¶
Use parse_sdl_file when your app stores a scenario as a file:
from pathlib import Path
from raes import parse_sdl_file
scenario = parse_sdl_file(Path("first-scenario.sdl.yaml"))
print(scenario.name)
The file example prints first-scenario. It does not compile or execute the scenario.
For imports, apply your existing module trust and resolution policy.
Validate text already in memory¶
Set sdl_text to your SDL text. For this example, use the downloaded file’s contents.
Use parse_sdl when you already have SDL text:
from raes import parse_sdl
scenario = parse_sdl(sdl_text)
Given only text, parse_sdl has no file location for resolving imports, so
it raises SDLParseError for SDL with top-level imports. Use
parse_sdl_file for a scenario that imports modules.
Both functions check the file shape and its meaning by default. Treat parse errors as authoring failures. Show the error message to the author. Keep semantic checks on unless your workflow has a clear reason to inspect the file shape alone.
See the API reference for signatures and model details.
Admit an import-free experiment family¶
Use admit_scenario_family to pass a parsed scenario without imports to the
experiment APIs:
from raes import admit_scenario_family, parse_sdl
family = admit_scenario_family(parse_sdl(sdl_text))
The function returns a semantically validated ExpandedScenario. The experiment
selection validator, binding-target resolver, scenario selector, and trial
compiler accept this family. Build family digest references from the returned
object with canonical_sdl_digest(family).
Admission checks current content and preserves source diagnostics and realization
intent. It does not select outcomes or grant permission to execute. Unresolved
imports and other document phases are rejected. For a family with imports, use
the existing parse_sdl_file composition path.
Treat the admitted family as read-only. Python still permits edits.
After edits, reparse the SDL and admit the new Scenario. If an edit changes
an omitted default field on the input, admission also asks you to reparse.
This prevents serialization from silently losing that edit. The parser return
types remain unchanged.
Transform an admitted artifact¶
Transformation functions operate on already parsed models and never write files. A successful result contains a newly admitted output and a portable report; a refusal contains no output.
Rename one declaration by its exact canonical address. In this scenario, the
content entry index-page refers to the node web:
from raes import RenameSDLDeclarationRequest, parse_sdl, rename_sdl_declaration
sdl_text = """
name: rename-example
nodes:
web:
type: compute
os: linux
resources:
ram: 2 GiB
cpu: 1
content:
index-page:
type: file
target: web
path: /var/www/index.html
"""
scenario = parse_sdl(sdl_text)
result = rename_sdl_declaration(
scenario,
RenameSDLDeclarationRequest(
target_address="nodes.web",
new_local_name="frontend",
),
)
if result.succeeded:
transformed = result.output
print(transformed.content["index-page"].target) # frontend
else:
for diagnostic in result.report.diagnostics:
print(diagnostic.code)
Success prints frontend. A refusal returns diagnostics and no output artifact.
The rename updates resolved references, module exports, and any explicitly
supplied external-concept binding documents as one all-or-none operation. An
alias, collision, stale linked artifact, or invalid target is refused. Renaming
a node does not rename its infrastructure entry, and each infrastructure
key must name a node. The rename therefore refuses a node that has an
infrastructure entry, such as web in first-scenario.sdl.yaml, with
artifact-transformation.target-invalid.
Loss is rejected by default. Remove the unreferenced index-page content
declaration with a policy that permits that loss:
from raes import (
ArtifactTransformationPolicy,
RemoveSDLDeclarationRequest,
remove_sdl_declaration,
)
from raes_contracts.contracts import ArtifactTransformationLossKind
result = remove_sdl_declaration(
scenario,
RemoveSDLDeclarationRequest(target_address="content.index-page"),
policy=ArtifactTransformationPolicy(
allowed_loss_kinds=(
ArtifactTransformationLossKind.DECLARATION_REMOVED,
)
),
)
if result.succeeded:
print("index-page" in result.output.content) # False
else:
for diagnostic in result.report.diagnostics:
print(diagnostic.code)
Success prints False. The original scenario still contains index-page.
Review the report before saving the result under a new filename.
On refusal, correct the target or explicit loss policy. Do not save a missing output.
Use canonicalize_portable_contract() to reconstruct an isolated portable
contract under its closed model, and compare_canonical_artifacts() for exact
canonical identity before and after an operation. Canonical identity is not a
claim of behavioral or backend equivalence. Consumers remain responsible for
file transactions, pack layout, persistence, and user-interface behavior.
Finish¶
The examples create in-memory models only. No backend cleanup is needed. Remove the downloaded example when you no longer need it. Read the SDL API reference for exact signatures. Read artifact boundaries before treating identity as behavioral equivalence. Continue with compilation and plan inspection.