product: maestro audience: test-developer authority: normative

Package Structure

Directory layout

{package-name}/
├── package.json              ← Package manifest (required)
├── README.md                 ← Package documentation (recommended)
├── validate.py               ← Two-level YAML validation script
├── .vscode/
│   └── settings.json         ← VS Code YAML schema wiring
├── docs/                     ← Maestro documentation (this folder)
│   └── Accordion/            ← Accordion hardware docs (if applicable)
├── tests/
│   ├── my-test.yaml          ← YAML test definitions
│   └── sub-sequence.yaml     ← Reusable sequences
├── assemblies/               ← .NET test DLLs (optional)
│   └── MyTests.dll
├── python_modules/           ← Python test scripts (optional)
│   └── my_instruments.py
├── wheels/                   ← Vendored pip wheels for offline install (optional)
│   └── requests-2.32.3-py3-none-any.whl
└── data/                     ← Supporting files (optional)
    ├── calibration.bin
    └── config.json

package.json schema

{
  "name": "my-package-name",
  "version": "1.0.0",
  "author": "Author Name",
  "authorEmail": "author@example.com",
  "description": "Short description",
  "lifecycleStatus": "NotReleased",
  "supportedProductIds": ["PCB-100"],
  "publishedDate": "2025-01-15T00:00:00Z",
  "requirements": {}
}

Field	Required	Type	Rules
`name`	✅	string	`^[A-Za-z0-9][A-Za-z0-9_\-]{0,63}$`
`version`	✅	string	Semantic version: `^\d+\.\d+\.\d+`
`author`	✅	string	Author or team name
`authorEmail`	—	string	Contact email
`description`	✅	string	Shown in Package Browser
`lifecycleStatus`	—	string	`NotReleased` \| `Evaluation` \| `Released` \| `Obsolete`
`supportedProductIds`	—	string[]	Board/product part numbers
`publishedDate`	—	ISO 8601	Publication date
`requirements`	—	object	Runtime prerequisites

`requirements` fields

Field	Type	Description
`minDotNetVersion`	string	e.g. `"10.0"`
`minPythonVersion`	string	e.g. `"3.11"`
`pipPackages`	string[]	e.g. `["requests>=2.32.0"]` — auto-installed by runner

pipPackages drives automatic installation. For production (air-gapped) stations, vendor wheel files in wheels/ — see sdk/python-dependencies.md.

Supporting files (`data/` directory)

Place calibration tables, firmware images, lookup files, certificates, or any other non-code supporting files in data/. The runner sets the working directory to the package root when executing a step — use relative paths:

// .NET
var calPath = Path.Combine("data", "calibration.bin");

# Python
import os
cal_path = os.path.join("data", "calibration.bin")

MUST NOT use absolute paths or Assembly.Location — the package may be deployed to different directories.

Test file discovery

The engine automatically discovers all *.yaml / *.yml files inside the installed package directory. You DO NOT need to list test files anywhere — place them under tests/.

VS Code authoring setup

Every scaffolded package includes files for zero-setup authoring support:

File	Purpose
`tat-test-schema.json`	JSON Schema — field descriptions, type checking, unknown-field detection
`.vscode/settings.json`	Wires schema to `tests/*.yaml` automatically
`validate.py`	Two-level validation — run before every commit

Install the redhat.vscode-yaml extension, then open the package folder as a workspace root (File → Open Folder).

Feature	How to use
Field autocomplete	`Ctrl+Space`
Inline validation	Red squiggles on unknown fields or type mismatches
Hover documentation	Hover over any field name

Two validation levels

Level	Tool	What it catches	Requires stack?
1 — Structural	`tat-test-schema.json` / `validate.py`	Unknown fields, missing required fields, wrong types	No
2 — Semantic	`validate.py` → API	Template variable resolution, limit ordering, step logic	Yes

tat-test-schema.json and validate.py are read-only reference files — DO NOT edit them. They are updated and re-copied with each TAT platform release.