Provider integration end-to-end example

This example shows one way a component catalog, artifact model, and provider snapshot could combine into staged metadata.

Scenario

  • component: spark
  • artifacts:
    • runtime
    • kubernetes-operator
  • provider: ATR
  • publication host: https://spark.example.org

Example authored metadata

 1sources:
 2  spark-repo:
 3    localDir: ../spark
 4  operator-repo:
 5    localDir: ../spark-k8s-operator
 6origins:
 7  spark:
 8    baseUrl: https://spark.example.org
 9components:
10  - slug: spark
11    displayName: Apache Spark
12    publication:
13      origin: spark
14      mountPath: /
15    artifacts:
16      - key: runtime
17        source: spark-repo
18        versioning:
19          developmentRef: main
20          maintenanceRefPattern: releases/{line}
21          tagPattern: ^v[0-9]+\.[0-9]+\.[0-9]+$
22      - key: kubernetes-operator
23        source: operator-repo
24        versioning:
25          developmentRef: main
26          tagPattern: ^operator-v[0-9]+\.[0-9]+\.[0-9]+$

Example provider snapshot input

 1schemaVersion: 1
 2providers:
 3  - key: atr
 4    type: atr
 5    fetchedAt: 2026-04-02T12:00:00Z
 6records:
 7  - provider: atr
 8    kind: released
 9    componentSlug: spark
10    artifactKey: runtime
11    externalId: atr:release:spark-runtime:4.0.0
12    version: 4.0.0
13    tag: v4.0.0
14    releaseLine: 4.x
15    supportStatus: active
16  - provider: atr
17    kind: candidate
18    componentSlug: spark
19    artifactKey: runtime
20    externalId: atr:candidate:spark-runtime:4.1.0:2
21    version: 4.1.0
22    displayVersion: 4.1.0-rc2
23    maturity: rc
24    candidateSequence: 2
25    releaseLine: 4.x
26    voteStatus: open
27  - provider: atr
28    kind: lineHead
29    componentSlug: spark
30    artifactKey: runtime
31    ref: releases/4.x
32    releaseLine: 4.x
33  - provider: atr
34    kind: development
35    componentSlug: spark
36    artifactKey: runtime
37    ref: main

Example staged page front matter

For a page staged from the candidate docs:

 1pipeline:
 2  page:
 3    kind: docsPage
 4    artifactKey: runtime
 5    version:
 6      kind: candidate
 7      label: 4.1.0-rc2
 8      maturity: rc
 9      releaseLine: 4.x
10      candidateSequence: 2
11      voteStatus: open
12    provider:
13      key: atr
14      externalId: atr:candidate:spark-runtime:4.1.0:2

Example staged aggregate metadata

data/providers.json

1[
2  {
3    "key": "atr",
4    "type": "atr",
5    "fetchedAt": "2026-04-02T12:00:00Z"
6  }
7]

data/artifacts.json

 1[
 2  {
 3    "componentSlug": "spark",
 4    "key": "runtime",
 5    "providerKeys": ["atr"],
 6    "latestRelease": { "version": "4.0.0" },
 7    "latestCandidate": { "displayVersion": "4.1.0-rc2" },
 8    "releaseLines": [
 9      { "key": "4.x", "latest": "4.0.0", "supportStatus": "active", "headRef": "releases/4.x" }
10    ]
11  }
12]

data/releases.json

 1[
 2  {
 3    "provider": "atr",
 4    "componentSlug": "spark",
 5    "artifactKey": "runtime",
 6    "version": "4.0.0",
 7    "tag": "v4.0.0",
 8    "releaseLine": "4.x",
 9    "supportStatus": "active"
10  }
11]

data/candidates.json

 1[
 2  {
 3    "provider": "atr",
 4    "componentSlug": "spark",
 5    "artifactKey": "runtime",
 6    "version": "4.1.0",
 7    "displayVersion": "4.1.0-rc2",
 8    "candidateSequence": 2,
 9    "releaseLine": "4.x",
10    "voteStatus": "open"
11  }
12]

data/refs.json

 1[
 2  {
 3    "provider": "atr",
 4    "componentSlug": "spark",
 5    "artifactKey": "runtime",
 6    "kind": "lineHead",
 7    "ref": "releases/4.x",
 8    "releaseLine": "4.x"
 9  },
10  {
11    "provider": "atr",
12    "componentSlug": "spark",
13    "artifactKey": "runtime",
14    "kind": "development",
15    "ref": "main"
16  }
17]

Why the example uses JSON for aggregate files

The current examples often use YAML for readability, but JSON is the safer baseline for aggregate staged metadata because renderer support for arbitrary YAML files is inconsistent. YAML remains a good default for front matter.

Renderer outcomes

From the staged outputs above, a renderer can build:

  • a candidate banner for 4.1.0-rc2
  • a release selector showing 4.0.0 and 4.x
  • a vote-status badge for the open candidate
  • links to development docs and release-line docs
  • download or release summary pages from the aggregate metadata