IMPORTANT: Developer documentation for the current development branch. This content is unreleased, may change without notice, and must not be treated as Buildish release documentation.

Provider input types

Normalized provider snapshot contracts consumed by the pipeline.

Back to the reference overview.

Type index

ProviderAsset — Downloadable asset attached to one provider release or candidate record.
ProviderDescriptor — Metadata about one provider that contributed records to the snapshot.
ProviderRecord — Normalized provider fact about one release, candidate, or ref context.
ProviderSnapshotDocumentV1 — Provider-derived normalized snapshot from site/provider-snapshot.json.

ProviderAsset

Downloadable asset attached to one provider release or candidate record.

category: provider
ownership: provider-derived
file contract: (inner type)

Field	Type	Required	Description
`name`	NonEmptyString	yes	Filename or display label of the downloadable asset.
`url`	UrlString	yes	Canonical download URL for the asset.
`kind`	NonEmptyString	no	Short asset kind label, for example `binary`, `source`, `signature`, or `sbom`.
`mediaType`	NonEmptyString	no	Declared media type for the asset payload when the provider exposes it.
`size`	NonNegativeInteger	no	Asset size in bytes when the provider exposes it.
`checksums`	dict[Identifier, NonEmptyString]	no	Checksum values keyed by algorithm name, such as `sha512` or `sha256`.
`signatureUrl`	UrlString	no	URL of the detached signature file, if available.
`sbomUrl`	UrlString	no	URL of the asset’s software bill of materials, if available.
`provenanceUrl`	UrlString	no	URL of provenance or attestation metadata associated with this asset, if available.

Selected field examples

name: Example: "spark-4.0.0-bin.tgz"
url: Example: "https://downloads.example.org/spark-4.0.0-bin.tgz"
kind: Example: "binary"
mediaType: Example: "application/gzip"
size: Example: 125004321

ProviderDescriptor

Metadata about one provider that contributed records to the snapshot.

category: provider
ownership: provider-derived
file contract: (inner type)

Field	Type	Required	Description
`key`	ProviderKey	yes	Stable provider identifier referenced by every record emitted from this provider.
`type`	NonEmptyString	yes	Provider implementation type, such as `github`, `git`, or another fetcher-specific backend name.
`displayName`	NonEmptyString	no	Human-readable provider label shown in diagnostics or rendered metadata.
`baseUrl`	ProviderBaseUrl	no	Base URL for the provider service when records can link back to a human-browsable origin.
`fetchedAt`	TimestampString	yes	Timestamp when this provider snapshot section was fetched or refreshed.

Selected field examples

key: Example: "github-releases"
type: Example: "github"
displayName: Example: "GitHub Releases"
baseUrl: Example: "https://github.com/apache"
fetchedAt: Example: "2026-04-03T18:00:00Z"

ProviderRecord

Normalized provider fact about one release, candidate, or ref context.

category: provider
ownership: provider-derived
file contract: (inner type)

Field	Type	Required	Description
`provider`	ProviderKey	yes	Provider key that identifies which fetched provider emitted this record.
`kind`	RecordKind	yes	Record kind, such as exact release, release candidate, development ref, line head, or named ref.
`componentSlug`	Slug	yes	Component slug that this provider record belongs to.
`artifactKey`	ArtifactKey	yes	Artifact key that this provider record belongs to.
`sourceKey`	SourceKey	no	Optional source binding key when the provider record came from one named catalog source.
`externalId`	NonEmptyString	no	Provider-specific stable identifier used to deduplicate and revisit the same upstream record.
`externalUrl`	UrlString	no	Human-browsable upstream URL for the release, tag, or ref record.
`version`	VersionString	no	Exact version string for release and candidate records when the provider exposes one.
`displayVersion`	NonEmptyString	no	Human-readable version label when the raw version string needs a friendlier presentation.
`tag`	NonEmptyString	no	Exact provider tag associated with this record when tags are available.
`ref`	RefString	no	Exact source-control ref associated with this record, especially for development, line-head, or named-ref contexts.
`commitSha`	NonEmptyString	no	Resolved commit SHA for the record when the provider exposes it.
`namedRefKey`	NonEmptyString	no	Catalog-authored named-ref key that this provider record enriches when the record represents a named ref.
`releaseLine`	NonEmptyString	no	Release-line key that groups this record with related versions such as `4.0`.
`releaseLineAncestors`	list[NonEmptyString]	no	Ancestor release-line keys, ordered from nearest to farthest, used when lineage matters to selection or rendering.
`supportStatus`	NonEmptyString	no	Support-status key or label associated with this record.
`publicationState`	PublicationState	no	Publication state for the record, such as published, withdrawn, or tombstoned.
`maturity`	NonEmptyString	no	Maturity label such as preview, beta, or stable that readers can use to judge readiness.
`candidateSequence`	NonNegativeInteger	no	Numeric ordering hint for release candidates, usually the `rc` sequence number.
`voteStatus`	NonEmptyString	no	Vote status label for a candidate release when the provider exposes release-vote state.
`createdAt`	TimestampString	no	Timestamp when the upstream record was first created.
`publishedAt`	TimestampString	no	Timestamp when the upstream record became publicly available.
`updatedAt`	TimestampString	no	Timestamp of the most recent upstream update observed for this record.
`urls`	dict[NonEmptyString, UrlString]	no	Additional named URLs related to the record, such as notes, signatures, vote threads, or changelogs.
`assets`	list[ProviderAsset]	no	Downloadable assets attached to the record, including checksums and related provenance links when available.

Selected field examples

provider: Example: "github-releases"
componentSlug: Example: "spark"
artifactKey: Example: "runtime"
sourceKey: Example: "apache-spark"
externalId: Example: "github:release:runtime-4.0.0"
version: Example: "4.0.0"
displayVersion: Example: "4.0.0 GA"
tag: Example: "v4.0.0"
ref: Example: "refs/heads/main"
commitSha: Example: "6f0fd1f7b2c4a6d8e9f00123456789abcdef0123"
namedRefKey: Example: "preview"
releaseLine: Example: "4.0"
releaseLineAncestors: Example: ["4.x","stable"]
supportStatus: Example: "supported"
maturity: Example: "stable"
candidateSequence: Example: 1
voteStatus: Example: "passed"

ProviderSnapshotDocumentV1

Provider-derived normalized snapshot from site/provider-snapshot.json.

category: provider
ownership: provider-derived
file contract: site/provider-snapshot.json

Field	Type	Required	Description
`schemaVersion`	Literal[1]	yes	Schema version for the provider snapshot document.
`providers`	list[ProviderDescriptor]	yes	Provider descriptors for every provider that contributed records to this snapshot.
`records`	list[ProviderRecord]	yes	Normalized provider records for releases, candidates, tags, refs, and related downloadable assets.

Example: Provider snapshot with one released record and one downloadable asset.

 1{
 2  "schemaVersion": 1,
 3  "providers": [
 4    {
 5      "key": "github-releases",
 6      "type": "github",
 7      "displayName": "GitHub Releases",
 8      "baseUrl": "https://github.com/apache/spark",
 9      "fetchedAt": "2026-04-03T18:00:00Z"
10    }
11  ],
12  "records": [
13    {
14      "provider": "github-releases",
15      "kind": "released",
16      "componentSlug": "spark",
17      "artifactKey": "runtime",
18      "externalId": "spark-4.0.0",
19      "externalUrl": "https://github.com/apache/spark/releases/tag/v4.0.0",
20      "version": "4.0.0",
21      "publishedAt": "2026-04-03T18:00:00Z",
22      "assets": [
23        {
24          "name": "spark-4.0.0-src.tgz",
25          "url": "https://downloads.apache.org/spark/spark-4.0.0-src.tgz",
26          "checksums": {
27            "sha256": "abc123"
28          }
29        }
30      ]
31    }
32  ]
33}