arc-validate

Home of all the tools and libraries to create and run validation of ARCs:

• ARCExpect (polyglot guide) - portable APIs to create and execute validation packages.
• arc-validate (CLI guide) - commands for validating ARCs and managing validation packages.

Docker container

This repository provides a docker container that has the arc-validate tool pre-installed for using it in DataHUB-CI jobs.

Use the containers tagged with main for production use.

Project aim

Validation of ARCs is based on:

• ARCExpect: portable Pyxpecto package execution, result, summary, JUnit, and badge APIs for .NET, JavaScript, and Python, plus target-specific output writing on .NET and Python and .NET-only ARCTokenization and ControlledVocabulary helpers.
• Validation packages: installable F# and Python validation scripts with shared metadata contracts from AVPR.
• arc-validate: package management, execution, and CLI orchestration.

Project layout

Dependency visualization

flowchart TD

ValidationPackageModel("<b>ValidationPackage.Model:</b><br>Portable package metadata")
ValidationPackageCodecs("<b>ValidationPackage.Codecs:</b><br>Portable metadata codecs")
ARCExpect("<b>ARCExpect:</b><br>Portable contracts and .NET validation APIs")
PackageManagement("<b>PackageManagement:</b><br>internal validation-package install/cache infrastructure")
PackageRunner("<b>PackageRunner:</b><br>internal F# and Python execution")
arc-validate("<b>arc-validate:</b><br>validation CLI tool")

arc-validate --depends on--> ARCExpect
arc-validate --owns--> PackageManagement
arc-validate --owns--> PackageRunner
ARCExpect --depends on--> ValidationPackageModel
ARCExpect --depends on--> ValidationPackageCodecs
PackageManagement --depends on--> ValidationPackageModel

Loading

Recording source provenance

Validation output can optionally record the branch and commit that supplied the validated ARC:

arc-validate validate \
  --source-branch "$CI_COMMIT_REF_NAME" \
  --source-commit-hash "$CI_COMMIT_SHA"

Both options are independent and optional. When present, arc-validate writes them to validation_summary.json, standard JUnit <properties>, and non-rendered SVG <metadata>. When absent, those fields and elements are omitted. Package-based validation receives the same switches in the package process argument list; ARCExpect's .NET and Python validation pipelines consume them automatically.

See the arc-validate argument documentation for the complete distinction between CLI-only and package-process arguments. Package-defined arguments follow the first -- and are parsed by ARCExpect against the package's CWL Inputs metadata:

arc-validate validate -p example -i ./arc -- --test --echo "literal value"

arc-validate and its script runners preserve every value as a separate process argument; they do not construct or evaluate shell commands.

Libraries used

ARCExpect

• ARCTokenization
• ValidationPackage.Model
• ValidationPackage.Codecs
• Fable
• Fable.Pyxpecto
• Thoth.Json

arc-validate

• ARCExpect
• AVPRClient
• AVPRClient.Interop
• ValidationPackage.Model
• Argu
• Expecto
• Spectre.Console

Development

For how to contribute to and how to develop on this project, please read the Contributing guidelines.

Just call build.sh or build.cmd depending on your OS.

Documentation

The documentation site combines a MkDocs Material guide with an fsdocs API reference. Every available F# and Python validation-package example is a real program under docs/samples/; the guide includes those files verbatim and the build installs and runs them against freshly packed artifacts. Each verification pass also regenerates the checked-in JSON summary, JUnit report, and SVG badge shown beside the sample. JavaScript package examples remain marked “Coming soon” until that package format exists.

./build.sh RunDocsSamples # pack and execute every language sample
./build.sh BuildDocs      # build the guide and API reference into site/
./build.sh WatchDocs      # preview the MkDocs guide with live reload
./build.sh WatchApiDocs   # preview the generated F# API reference

Use the corresponding build.cmd commands on Windows.

Test

The full test setup uses the AVPR development service, running tests for the compiled arc-validate tool with validation packages from https://avpr-dev.nfdi4plants.org. Network-backed tests must not target the production registry. RunTests remains the default full suite. Push and pull-request CI uses RunAutomatedTests, which runs only the normal test projects. Run the manually dispatched AVPR integration tests workflow to execute the dedicated integration-test projects in CI. RunTests runs both sets locally.

since testing the cli tool relies on it being compiled via dotnet publish, either use the build scripts or manually publish arc-validate to the /publish folder when using e.g. TestExplorers.

build.sh RunTests

build.cmd RunTests

Build and release ARCExpect packages

To build and verify the three ARCExpect artifacts (ARCExpect for NuGet, @nfdi4plants/arcexpect for npm, and arcexpect for Python), run:

build.cmd TestPortableARCExpect

PackARCExpect creates the three artifacts without publishing them. Reviewed releases use the manually dispatched Release ARCExpect workflow against the release branch. It verifies the core and portable suites, packs once, and publishes independent NuGet, npm, and PyPI jobs through the protected release environment. See the release guide for versioning and the exact trusted-publisher configuration.