Galaxy tool summary manifest

Galaxy Tool Summary

Deterministic per-tool manifest emitted by `galaxy-tool-cache summarize`. Bundles cache provenance, the upstream `ParsedTool` payload, and per-representation input JSON Schemas so downstream Molds can bind a single workflow step against a Galaxy tool wrapper without re-parsing XML.

5 definitions. Anchor links per definition (e.g. #has_text_model) are stable.

field	type	req	description
parsed_tool_path	string	✓	Absolute path to `<cache_key>.json` — the cached `ParsedTool` JSON the manifest was built from.
raw_tool_source_path	string \| null	✓	Absolute path to `<cache_key>.source` (raw wrapper XML/YAML) when the cache has stored it. Null in @galaxy-tool-util/cli@1.3.x — raw source storage lands in galaxy-tool-util-ts#82.

field

type

req

description

parsed_tool_path

string

✓

Absolute path to `<cache_key>.json` — the cached `ParsedTool` JSON the manifest was built from.

raw_tool_source_path

string | null

✓

Absolute path to `<cache_key>.source` (raw wrapper XML/YAML) when the cache has stored it. Null in @galaxy-tool-util/cli@1.3.x — raw source storage lands in galaxy-tool-util-ts#82.

field	type	req	description
artifacts	→ Artifacts	✓
cache_key	string	✓	`galaxy-tool-cache` cache key for the entry the manifest was built from. Stable across runs for a given (source, tool, version) triple.
input_schemas	→ InputSchemas	✓
parsed_tool	→ ParsedTool	✓	Upstream `ParsedTool` payload, validated against `parsedToolSchema` from `@galaxy-tool-util/schema`. See `[[parsed-tool]]` for the field-by-field reference.
schema_version = "1"	const "1"	✓	Manifest schema version. v1 is the shape emitted by `galaxy-tool-cache summarize` in `@galaxy-tool-util/cli@1.3.x`.
source	→ SourceRecord	✓
tool_id	string	✓	Tool id as it appears in the cached `ParsedTool`. For Tool Shed wrappers this is the short XML id, not the fully qualified `toolshed.g2.bx.psu.edu/repos/...` form.
tool_version	string \| null	✓	Tool version from the cached `ParsedTool`. Null only when the wrapper itself omits a version.
warnings	string[]	✓	Advisory diagnostics emitted while building the manifest — typically input-schema generation failures for one of the workflow representations. Empty array on a clean run.

field

type

req

description

artifacts

→ Artifacts

✓

cache_key

string

✓

`galaxy-tool-cache` cache key for the entry the manifest was built from. Stable across runs for a given (source, tool, version) triple.

input_schemas

→ InputSchemas

✓

parsed_tool

→ ParsedTool

✓

Upstream `ParsedTool` payload, validated against `parsedToolSchema` from `@galaxy-tool-util/schema`. See `[[parsed-tool]]` for the field-by-field reference.

schema_version = "1"

const "1"

✓

Manifest schema version. v1 is the shape emitted by `galaxy-tool-cache summarize` in `@galaxy-tool-util/cli@1.3.x`.

source

→ SourceRecord

✓

tool_id

string

✓

Tool id as it appears in the cached `ParsedTool`. For Tool Shed wrappers this is the short XML id, not the fully qualified `toolshed.g2.bx.psu.edu/repos/...` form.

tool_version

string | null

✓

Tool version from the cached `ParsedTool`. Null only when the wrapper itself omits a version.

warnings

string[]

✓

Advisory diagnostics emitted while building the manifest — typically input-schema generation failures for one of the workflow representations. Empty array on a clean run.

field	type	req	description
workflow_step	object \| null	✓	JSON Schema for the `workflow_step` representation — values inline as a step `tool_state`. Null when the tool has parameters that the schema generator cannot render in this representation.
workflow_step_linked	object \| null	✓	JSON Schema for the `workflow_step_linked` representation — datasets become workflow connections, scalars stay inline. Null when generation failed for this representation.

field

type

req

description

workflow_step

object | null

✓

JSON Schema for the `workflow_step` representation — values inline as a step `tool_state`. Null when the tool has parameters that the schema generator cannot render in this representation.

workflow_step_linked

object | null

✓

JSON Schema for the `workflow_step_linked` representation — datasets become workflow connections, scalars stay inline. Null when generation failed for this representation.

field	type	req	description
cached_at	string \| null	✓	ISO 8601 timestamp the cache entry was written. Null when the cache index entry predates the timestamp field.
kind	string	✓	Normalized source classification. `toolshed` covers any Tool Shed-derived entry (cache index `source: api`); `galaxy` and `local` come straight from the cache; `orphan` is for entries the cache index can no longer attribute; `unknown` is the fallback when no index entry is found.
label	string	✓	Raw `source` string from the cache index entry, e.g. `api`, `galaxy`, `local`. Pass-through for debugging; downstream Molds should branch on `kind` instead.
url	string	✓	Origin URL the cache entry was populated from. Empty string when the cache index has no recorded URL.

field

type

req

description

cached_at

string | null

✓

ISO 8601 timestamp the cache entry was written. Null when the cache index entry predates the timestamp field.

kind

string

✓

Normalized source classification. `toolshed` covers any Tool Shed-derived entry (cache index `source: api`); `galaxy` and `local` come straight from the cache; `orphan` is for entries the cache index can no longer attribute; `unknown` is the fallback when no index entry is found.

label

string

✓

Raw `source` string from the cache index entry, e.g. `api`, `galaxy`, `local`. Pass-through for debugging; downstream Molds should branch on `kind` instead.

url

string

✓

Origin URL the cache entry was populated from. Empty string when the cache index has no recorded URL.

This page is auto-rendered from the JSON Schema authored in this repo. Each $def becomes a section below with a stable anchor ID — research notes and Mold bodies can deep-link individual shapes via [[galaxy-tool-summary#SourceRecord]].

Source-of-truth chain:

packages/foundry/src/schemas/galaxy-tool-summary/galaxy-tool-summary.schema.json — the canonical JSON, hand-edited alongside the Mold/cast loop around summarize-galaxy-tool. Mold frontmatter still cites it as content/schemas/galaxy-tool-summary.schema.json; cast and Astro resolve that back to the package source.
packages/foundry/scripts/sync-schema.mjs runs at prebuild, regenerating the typed galaxy-tool-summary.schema.generated.ts const wrapper from the canonical JSON.
Published as part of @galaxy-foundry/foundry (orphan schema bundled in the unified CLI). Site rendering imports the schema directly from this package via site/src/lib/schema-registry.ts; the published CLI also ships foundry validate-galaxy-tool-summary for cast skills and downstream consumers.

At runtime in cast skills: validation should happen through the CLI command:

foundry validate-galaxy-tool-summary manifest.json

Library validation exists for TypeScript consumers, but generated skills should prefer command-shaped validation so failures are easy to reproduce outside the agent runtime.

Why manifest-shaped

This schema describes the deterministic JSON emitted by galaxy-tool-cache summarize <tool_id> --version <ver> from @galaxy-tool-util/cli@1.3.x — not a curated Foundry-flavored summary. The CLI handles the deterministic, side-effect-bearing work (cache lookup, source classification, effect/JSONSchema translation of the parameter bundle); the manifest is the contract Foundry consumers bind to.

The shape:

source — where the cache entry came from (toolshed, galaxy, local, orphan, unknown), with the raw cache-index label, origin URL, and cached-at timestamp.
artifacts — filesystem paths to <cache_key>.json and (later) <cache_key>.source so consumers can reload or pass-through the raw bytes. Local debugging only; not stable across machines. raw_tool_source_path is null until galaxy-tool-util-ts#82 ships the raw-source storage path.
parsed_tool — upstream ParsedTool payload, owned by @galaxy-tool-util/schema. Validated against parsedToolSchema; see parsed-tool for the inner shape. The Foundry schema does not duplicate this model.
input_schemas — generated JSON Schemas for the workflow_step and workflow_step_linked representations, suitable for direct binding by [[implement-galaxy-tool-step]]. Either entry is null when generation fails, in which case warnings[] carries the reason.

Scope and v2 follow-ups

v1 mirrors what galaxy-tool-cache summarize actually emits today. It does not attempt to surface curated requirements, containers, command, or stdio — those fields are not yet on upstream ParsedTool and remain out of scope until Galaxy upstream lands them and @galaxy-tool-util/schema mirrors them. Track:

galaxy-tool-util-ts#82 — raw <cache_key>.source storage; flips artifacts.raw_tool_source_path from always-null to optionally populated.
Galaxy upstream ParsedTool extension (requirements, containers, stdio) — once it lands and is mirrored in @galaxy-tool-util/schema, the parsed_tool subtree gains those fields automatically because this schema delegates to upstream parsedToolSchema.

A v2 of this manifest can layer Foundry-curated fields on top of (not in place of) the upstream parsed_tool, bumping schema_version to 2. Downstream Molds should branch on the integer to stay compatible during the transition.

Galaxy tool summary manifest