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 snapshot schema

This document defines a normalized input schema for external release providers. It complements the flexible publication model by making the provider boundary concrete without hard-coding Apache Trusted Releases (ATR) or any other provider into the core pipeline model.

Goals

  • keep the provider contract small and versioned,
  • support ATR, Git-hosting release APIs, and future providers,
  • preserve provider-specific detail without polluting the core contract,
  • let renderers rely on staged metadata rather than direct provider calls, and
  • keep authored site metadata authoritative for routing and identity.

Top-level snapshot shape

Recommended shape:

  • schemaVersion
  • providers[]
  • records[]

Recommended providers[] fields:

  • key
  • type
  • optional displayName
  • optional public baseUrl
  • fetchedAt

Minimal normalized records[] schema

Required fields on every record:

  • provider
  • kind
  • componentSlug
  • artifactKey

Each record should also provide at least one stable locator:

  • externalId, or
  • version, or
  • tag, or
  • ref

Recommended shared optional fields:

  • sourceKey
  • externalUrl
  • displayVersion
  • commitSha
  • releaseLine
  • releaseLineAncestors
  • supportStatus
  • maturity
  • candidateSequence
  • voteStatus
  • createdAt
  • publishedAt
  • updatedAt
  • urls
  • assets

Record kinds

Recommended shared kind values:

  • development
  • namedRef
  • lineHead
  • candidate
  • released

Kind-specific expectations:

  • development: usually carries ref
  • namedRef: should carry ref
  • lineHead: should carry releaseLine and usually ref
  • candidate: should normally carry version; candidateSequence is recommended
  • released: should normally carry version and usually tag

The pipeline should treat kind as the primary normalized lifecycle category. Fields such as maturity, supportStatus, and voteStatus add detail but do not replace kind.

Merge precedence

The provider snapshot is one input into the build, not the whole truth.

Recommended precedence rules:

  1. authored site/catalog/component metadata owns:
    • component identity
    • artifact identity
    • publication routing
    • grouping and navigation defaults
    • support-status vocabularies
  2. provider snapshots own externally observed release state:
    • discovered releases
    • candidates and vote state
    • development refs and release-line heads
    • provider-observed details for authored named refs when they can be matched
    • provider URLs and timestamps
    • downloadable assets
  3. explicit local override files, if introduced later, should override provider data in a narrow and auditable way

Provider data must not silently redefine consumer-owned URLs or artifact identity.

Planning should reject snapshots whose records point at component/artifact identities that do not exist in the resolved site config. It should also reject snapshots that exceed the planning ceilings of 50,000 normalized records or 16 MiB of encoded snapshot input.

Intentional publication of named refs remains authored in the catalog or artifact metadata. Provider data may enrich those refs, but it does not define which named refs exist as public version contexts.

Minimal optional assets[] schema

assets[] should remain lightweight and nested under a release or candidate record.

Required fields:

  • name
  • url

Recommended optional fields:

  • kind
  • mediaType
  • size
  • checksums
  • signatureUrl
  • sbomUrl
  • provenanceUrl

Useful advisory kind values include:

  • archive
  • signature
  • checksum
  • sbom
  • provenance
  • container-image
  • package

checksums should prefer a simple algorithm-keyed map such as sha512 or sha256.

Example: ATR-style snapshot

 1schemaVersion: 1
 2providers:
 3  - key: atr
 4    type: atr
 5    displayName: Apache Trusted Releases
 6    baseUrl: https://release-test.apache.org
 7    fetchedAt: 2026-04-02T12:00:00Z
 8records:
 9  - provider: atr
10    kind: candidate
11    componentSlug: spark
12    artifactKey: runtime
13    externalId: atr:candidate:spark-runtime:4.1.0:2
14    externalUrl: https://release-test.apache.org/candidates/spark-runtime/4.1.0/2
15    version: 4.1.0
16    displayVersion: 4.1.0-rc2
17    maturity: rc
18    candidateSequence: 2
19    voteStatus: open
20    releaseLine: 4.x
21  - provider: atr
22    kind: released
23    componentSlug: spark
24    artifactKey: runtime
25    externalId: atr:release:spark-runtime:4.0.0
26    version: 4.0.0
27    tag: v4.0.0

Example: GitHub-release-style snapshot

 1schemaVersion: 1
 2providers:
 3  - key: github
 4    type: github-releases
 5    displayName: GitHub Releases
 6    baseUrl: https://github.com
 7    fetchedAt: 2026-04-02T12:05:00Z
 8records:
 9  - provider: github
10    kind: released
11    componentSlug: spark
12    artifactKey: runtime
13    externalId: github:release:12345
14    externalUrl: https://github.com/apache/spark/releases/tag/v4.0.0
15    version: 4.0.0
16    tag: v4.0.0
17    publishedAt: 2026-03-10T08:00:00Z
18  - provider: github
19    kind: candidate
20    componentSlug: spark
21    artifactKey: runtime
22    externalId: github:release:12346
23    externalUrl: https://github.com/apache/spark/releases/tag/v4.1.0-rc1
24    version: 4.1.0
25    displayVersion: 4.1.0-rc1
26    maturity: rc
27    publishedAt: 2026-03-15T10:00:00Z

Validation expectations

The pipeline should reject at least:

  • unknown provider keys,
  • unknown componentSlug or artifactKey references,
  • duplicate records for the same (provider, externalId) pair when externalId exists,
  • records that provide none of externalId, version, tag, or ref, and
  • records whose kind is outside the shared normalized vocabulary, and
  • unknown extra fields outside the documented provider, record, and asset schemas.