Integrate provider, compatibility, and translation data

Keep ownership boundaries explicit

The clean split is:

• authored site and catalog metadata own public policy and route intent
• provider snapshots enrich lifecycle and release-state information
• compatibility metadata expresses cross-component or cross-artifact support
• translation linkage relates localized pages without redefining route policy

These are three independent dimensions. Add and validate each one separately so a provider problem cannot be mistaken for a compatibility or localization problem.

1. Add provider lifecycle data

First author the component, artifact, versioning rules, publication selection, and lifecycle entries in site/catalog.yaml. Then supply matching normalized records in site/provider-snapshot.json:

 1{
 2  "schemaVersion": 1,
 3  "providers": [
 4    {
 5      "key": "github",
 6      "type": "githubReleases",
 7      "fetchedAt": "2026-04-03T00:00:00Z"
 8    }
 9  ],
10  "records": [
11    {
12      "provider": "github",
13      "kind": "released",
14      "componentSlug": "spark",
15      "artifactKey": "runtime",
16      "version": "4.0.0",
17      "tag": "v4.0.0"
18    }
19  ]
20}

After building, inspect data/providers.json, data/artifacts.json, and data/releases.json. The released page’s pipeline.page.version and pipeline.page.provider fields provide page-local context.

Provider records must match authored identities and selected contexts. They may add normalized lifecycle provenance, but they cannot introduce a new public component, route, or release selection by themselves.

2. Model compatibility as an authored assertion

Place the assertion on the component or artifact whose compatibility is being described:

1compatibility:
2  - subjectRef: component:spark
3    targetRef: component:spark-operator
4    relation: testedWith
5    scope: kubernetes
6    confidence: verified
7    notes: Spark runtime docs assume the matching operator line.

The typed subject and target must resolve within the catalog. The staged data/compatibility.json entry then retains the relationship for renderers:

1{
2  "subjectId": "component:spark",
3  "targetId": "component:spark-operator",
4  "relation": "testedWith",
5  "scope": "kubernetes",
6  "confidence": "verified",
7  "notes": "Spark runtime docs assume the matching operator line."
8}

Do not infer compatibility from similar version numbers. State the relationship and its scope directly, and update it when the supporting evidence changes.

3. Link translated pages

Declare the locale policy in defaults or on one component:

1localization:
2  supportedLocales: [en, de]
3  defaultLocale: en
4  fallbackLocale: en
5  routeMode: prefixAll

Place corresponding pages below supported locale directories and give them the same authored translation key:

1---
2title: Install Spark
3translationKey: install
4---

For example, en/install.md and de/install.md form one translation set when both declare translationKey: install. The pipeline emits page-local sibling links and a cross-page entry in data/translations.json; the renderer chooses how to display those links.

The same key may occur only once per locale in a component/artifact context. With prefixAll, a translated page must live below a supported locale prefix, and sibling routes must have a consistent shape.

Validate one dimension at a time

1. Build and inspect the authored publication model without optional compatibility or translation data.
2. Add provider records and inspect lifecycle aggregates.
3. Add compatibility assertions and inspect data/compatibility.json.
4. Add localization policy and one complete translation set, then inspect data/translations.json and the staged page front matter.
5. Expand only after site-pipeline check passes at each step.

Failure map

Read this next

For unreleased development contract details:

• provider snapshot schema
• provider to staged metadata mapping
• security and trust model
• pipeline model schema reference