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.

Staged aggregate metadata types

Public aggregate JSON contracts emitted under data/.

Public aggregate JSON contracts emitted under data/.

Back to the reference overview.

Type index

ArtifactsDataEntry

Entry in data/artifacts.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
componentSlug Slug yes Owning component slug for the artifact.
key ArtifactKey yes Stable artifact key used by routes, aggregates, and typed references.
displayName NonEmptyString no Human-readable artifact label shown in navigation and metadata.
sourceKey SourceKey no Named source binding that owns the artifact’s docs and assets.
docsRoot RepoRelativePath no Repository-relative docs root for the artifact when it differs from the component default.
providerKeys list[ProviderKey] no Provider keys that contributed version metadata for this artifact.
versioning ArtifactVersioningConfig no Version-discovery rules that explain how development refs, tags, and named refs are derived for the artifact.
latestStable VersionString no Most recent stable version recommended for readers.
latestRelease LatestReleaseSummary no Compact summary of the latest known release for the artifact.
latestCandidate LatestCandidateSummary no Compact summary of the latest known release candidate for the artifact.
releaseLines list[ReleaseLineSummary] no Release-line summaries associated with the artifact.
namedRefs list[RefAggregateEntry] no Published development, line-head, or named-ref contexts associated with the artifact.
supportStatusVocabulary dict[NonEmptyString, SupportStatusDefinition] no Reusable support-status definitions that release lines and releases for this artifact can refer to by key.
supportPolicyUrl UrlString no Canonical URL for the support policy document associated with this artifact.

Selected field examples

  • componentSlug: Example: "spark"
  • key: Example: "runtime"
  • displayName: Example: "Runtime"
  • sourceKey: Example: "apache-spark"
  • docsRoot: Example: "docs/runtime"
  • providerKeys: Example: ["github-releases"]
  • latestStable: Example: "4.0.1"

CandidateAggregateEntry

Entry in data/candidates.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
provider ProviderKey no Provider key for the upstream system that supplied this candidate record.
externalId NonEmptyString no Provider-specific stable identifier for the upstream candidate record.
externalUrl UrlString no Human-browsable upstream URL for the candidate record.
componentSlug Slug yes Owning component slug for the candidate.
artifactKey ArtifactKey yes Owning artifact key for the candidate.
version VersionString yes Candidate version string represented by this aggregate entry.
displayVersion NonEmptyString no Human-readable candidate label when it should differ from the raw version string.
candidateSequence int no Numeric ordering hint for the candidate, usually the rc sequence number.
releaseLine NonEmptyString no Release-line key that the candidate belongs to, if known.
maturity NonEmptyString no Maturity label associated with the candidate.
voteStatus NonEmptyString no Vote-status label for the candidate, if known.
createdAt TimestampString no Timestamp when the candidate record was first created.
publishedAt TimestampString no Timestamp when the candidate became publicly visible.
assets list[ProviderAsset] no Downloadable assets attached to the candidate.

Selected field examples

  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"
  • version: Example: "4.1.0-rc1"
  • candidateSequence: Example: 1
  • releaseLine: Example: "4.1"
  • maturity: Example: "preview"
  • voteStatus: Example: "passed"

CompatibilityAggregateEntry

Entry in data/compatibility.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
subjectId NonEmptyString yes Typed reference or aggregate identifier for the subject of the compatibility statement.
targetId NonEmptyString yes Typed reference or aggregate identifier for the target of the compatibility statement.
relation NonEmptyString yes Relationship label that names the compatibility statement.
scope NonEmptyString no Optional scope label that narrows the compatibility statement.
confidence NonEmptyString no Optional confidence label that explains how strong the supporting evidence is.
notes NonEmptyString no Additional human-readable explanation, caveats, or migration advice for the compatibility statement.
evidence list[NonEmptyString] no Named evidence pointers or short evidence labels that support the compatibility statement.

Selected field examples

  • subjectId: Example: "artifact:spark/runtime"
  • targetId: Example: "artifact:spark/operator"
  • relation: Example: "testedWith"
  • scope: Example: "kubernetes"
  • confidence: Example: "verified"

ComponentsDataEntry

Entry in data/components.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
slug Slug yes Stable component slug used by routes, aggregates, and typed references.
displayName NonEmptyString no Human-readable component name shown in navigation, listings, and generated metadata.
latestStable VersionString no Most recent stable version recommended for the component as a whole when one shared release line is enough.
weight int no Optional ordering hint copied from the authored catalog for consumer-rendered component lists.
group Identifier no Optional group key copied from the authored catalog to support grouped rendering or filtering.
originKey OriginKey yes Origin key selected for this component’s primary published route set.
publication ResolvedPublication yes Resolved publication roots and URLs for the component.
providerKeys list[ProviderKey] no Provider keys that contributed version metadata for this component’s artifacts.
artifacts list[ArtifactFrontMatterSummary] no Compact artifact summaries used by component listings and page chrome.

Selected field examples

  • slug: Example: "spark"
  • displayName: Example: "Apache Spark"
  • latestStable: Example: "4.0.1"
  • group: Example: "data-platform"
  • originKey: Example: "archive"
  • providerKeys: Example: ["github-releases"]

ContentIndexEntry

Entry in data/content-index.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
id NonEmptyString yes Stable identifier for the indexed page entry.
componentSlug Slug yes Owning component slug for the indexed page.
artifactKey ArtifactKey no Owning artifact key when the page belongs to a specific artifact.
pageKind NonEmptyString yes Short page-kind label used for filtering and presentation.
section NonEmptyString no Higher-level section label used for navigation or filtering.
originKey OriginKey yes Origin key that this indexed page belongs to.
path PublicPath yes Published public path for the page.
url UrlString yes Canonical absolute URL for the page.
canonicalUrl UrlString no Explicit canonical URL when it should differ from url.
title NonEmptyString no Primary page title shown to readers.
linkTitle NonEmptyString no Shorter title variant used in navigation or link lists.
description NonEmptyString no Longer page description intended for metadata or search snippets.
summary NonEmptyString no Short summary used for listings, cards, or lightweight search results.
weight int no Optional ordering hint used by renderers for listings or navigation.
parentId NonEmptyString no Identifier of the parent indexed page when the page belongs to a hierarchy.
ancestorIds list[NonEmptyString] no Ancestor page identifiers ordered from nearest to farthest.
source PageSourceProvenance no Repository-neutral provenance for the authored source file that produced this indexed page.
versionKind RecordKind no Version-context kind attached when the page belongs to a versioned route set.
versionLabel NonEmptyString no Human-readable version label attached to the page, if present.
releaseLine NonEmptyString no Release-line key attached to the page, if present.
supportStatus NonEmptyString no Support-status key or label attached to the page’s version context.
publicationState PublicationState no Publication-state label attached to the page’s version context.
locale NonEmptyString no Locale key for the page when the page participates in localization.
defaultLocale bool no Whether the page represents the default locale within its translation group.
translationKey NonEmptyString no Shared key that ties translated sibling pages together.
provider ProviderKey no Provider key for the upstream record that informed the page’s version metadata.
externalId NonEmptyString no Provider-specific stable identifier for the upstream record that informed the page.
maturity NonEmptyString no Maturity label such as preview, beta, or stable.
candidateSequence int no Release-candidate sequence number when the page belongs to a candidate context.
voteStatus NonEmptyString no Vote-status label when the page belongs to a candidate context.

Selected field examples

  • id: Example: "spark-runtime-4.0.0-getting-started"
  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"
  • pageKind: Example: "docsPage"
  • section: Example: "documentation"
  • originKey: Example: "archive"
  • path: Example: "/spark/4.0.0/docs/getting-started/"
  • title: Example: "Getting Started"
  • linkTitle: Example: "Start"
  • weight: Example: 100
  • parentId: Example: "spark-runtime-4.0.0-docs-root"
  • ancestorIds: Example: ["spark-runtime-4.0.0-docs-root","spark-runtime-root"]
  • versionLabel: Example: "4.0.0"
  • releaseLine: Example: "4.0"
  • supportStatus: Example: "supported"
  • locale: Example: "en"
  • translationKey: Example: "spark-overview"
  • maturity: Example: "stable"
  • candidateSequence: Example: 1
  • voteStatus: Example: "passed"

LatestCandidateSummary

Compact latest-candidate summary embedded in artifact aggregates.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
version VersionString no Candidate version string when the provider exposes one.
displayVersion NonEmptyString no Human-readable candidate label when it should differ from the raw version string.
candidateSequence int no Numeric ordering hint for the candidate, usually the rc sequence number.
voteStatus NonEmptyString no Vote-status label for the latest candidate when it is known.

Selected field examples

  • version: Example: "4.1.0-rc1"
  • candidateSequence: Example: 1
  • voteStatus: Example: "passed"

LatestReleaseSummary

Compact latest-release summary embedded in artifact aggregates.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
version VersionString yes Exact version string of the latest known release.
displayVersion NonEmptyString no Human-readable label for the latest release when it should differ from the raw version string.
tag NonEmptyString no Tag associated with the latest release, if known.
publicationState PublicationState no Publication-state label for the latest release, such as published or withdrawn.
publishedAt TimestampString no Timestamp when the latest release became publicly available.

Selected field examples

  • version: Example: "4.0.1"
  • tag: Example: "v4.0.1"

MountAggregateEntry

Entry in data/mounts.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
mountId NonEmptyString yes Stable aggregate identifier for the mount entry.
ownerId NonEmptyString yes Aggregate identifier for the component or artifact that owns the mount.
kind NonEmptyString yes Short mount kind label that tells consumers what sort of subtree this is.
trustClass TrustClass yes Trust level assigned to the mounted content.
publicPath PublicPath yes Public path where the mounted subtree is published.
sourceRef MountSourceRef yes Typed source reference for the generated or imported subtree being mounted.
versionContext NonEmptyString no Optional version-context label that scopes the mount to one publication context.
indexBehavior IndexBehavior no How the mounted subtree should participate in generated indexes or listings.
metadata ExtensionsObject no Small JSON-like extension object for extra mount metadata consumed by downstream tooling.

Selected field examples

  • mountId: Example: "spark-runtime-generated-api"
  • ownerId: Example: "artifact:spark/runtime"
  • kind: Example: "generatedApi"
  • publicPath: Example: "/spark/api/"
  • sourceRef: Example: "generated/api"
  • versionContext: Example: "release"

ProvidersDataEntry

Entry in data/providers.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key ProviderKey yes Stable provider identifier used by aggregate entries that originate from this provider.
type NonEmptyString yes Provider implementation type, such as github or another fetcher backend label.
displayName NonEmptyString no Human-readable provider label shown in generated metadata or diagnostics.
baseUrl ProviderBaseUrl no Base URL of the provider service when records can link back to a human-browsable upstream origin.
fetchedAt TimestampString yes Timestamp when this provider descriptor was fetched or refreshed.

Selected field examples

  • key: Example: "github-releases"
  • type: Example: "github"
  • displayName: Example: "GitHub Releases"

RedirectAggregateEntry

Entry in data/redirects.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
fromUrl UrlString yes Absolute source URL that should redirect.
toUrl UrlString yes Absolute destination URL that the redirect should send readers to.
status int yes HTTP redirect status code emitted for this redirect.
reason NonEmptyString no Short explanation of why the redirect exists.
sourceKind NonEmptyString no Short label describing where the redirect originated, such as an alias or withdrawn release rule.

Selected field examples

  • status: Example: 308
  • sourceKind: Example: "withdrawnRelease"

RefAggregateEntry

Entry in data/refs.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
provider ProviderKey no Provider key for the upstream system that supplied this ref record.
externalId NonEmptyString no Provider-specific stable identifier for the upstream ref record.
externalUrl UrlString no Human-browsable upstream URL for the ref record.
componentSlug Slug yes Owning component slug for the ref context.
artifactKey ArtifactKey yes Owning artifact key for the ref context.
kind RecordKind yes Ref context kind, limited to development, named-ref, and line-head entries.
namedRefKey NonEmptyString no Catalog-authored named-ref key when this entry represents a named ref.
ref RefString yes Exact source-control ref for the published ref context.
displayVersion NonEmptyString no Human-readable label for the ref context.
releaseLine NonEmptyString no Release-line key when the ref context represents a line head.
maturity NonEmptyString no Maturity label associated with the ref context.

Selected field examples

  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"
  • namedRefKey: Example: "preview"
  • ref: Example: "refs/heads/main"
  • displayVersion: Example: "main"
  • releaseLine: Example: "4.0"
  • maturity: Example: "preview"

ReleaseAggregateEntry

Entry in data/releases.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
provider ProviderKey no Provider key for the upstream system that supplied this release record.
externalId NonEmptyString no Provider-specific stable identifier for the upstream release record.
externalUrl UrlString no Human-browsable upstream URL for the release record.
componentSlug Slug yes Owning component slug for the release.
artifactKey ArtifactKey yes Owning artifact key for the release.
version VersionString yes Exact released version represented by this aggregate entry.
displayVersion NonEmptyString no Human-readable version label when it should differ from the raw version string.
tag NonEmptyString no Exact tag associated with the release, if known.
releaseLine NonEmptyString no Release-line key that groups this release with related versions.
releaseLineAncestors list[NonEmptyString] no Ancestor release-line keys ordered from nearest to farthest.
supportStatus NonEmptyString no Support-status key or label associated with the release.
supportWindow SupportWindow no Lifecycle dates and support notes associated with the release.
publicationState PublicationState no Publication-state label for the release, such as published, withdrawn, or tombstoned.
withdrawalBehavior WithdrawalBehavior no Behavior that readers should experience when the release has been withdrawn.
redirectTarget ReferenceString | UrlString no Replacement route or external URL used when a withdrawn release redirects readers elsewhere.
maturity NonEmptyString no Maturity label such as stable, preview, or beta.
publishedAt TimestampString no Timestamp when the release became publicly available.
assets list[ProviderAsset] no Downloadable assets attached to the release.
urls dict[NonEmptyString, UrlString] no Additional named URLs related to the release, such as notes, downloads, or verification material.

Selected field examples

  • provider: Example: "github-releases"
  • externalId: Example: "github:release:runtime-4.0.0"
  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"
  • version: Example: "4.0.0"
  • tag: Example: "v4.0.0"
  • releaseLine: Example: "4.0"
  • releaseLineAncestors: Example: ["4.x","stable"]
  • supportStatus: Example: "supported"
  • redirectTarget: Example: "route:/spark/releases/4.0.1/"
  • maturity: Example: "stable"

RouteAggregateEntry

Entry in data/routes.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
originKey OriginKey yes Origin key that this public route belongs to.
baseUrl UrlString yes Base URL for the route’s origin.
path PublicPath yes Public path for the route.
url UrlString yes Absolute URL for the route after joining baseUrl and path.
componentSlug Slug yes Owning component slug for the route.
artifactKey ArtifactKey no Owning artifact key when the route belongs to a specific artifact.
section NonEmptyString no Higher-level section label for the route, if present.
canonical bool no Whether this route should be treated as the canonical route among equivalent alternatives.
routeKind NonEmptyString no Short route-kind label such as component root, docs root, alias, or release page.
targetId NonEmptyString no Stable target identifier used to correlate equivalent routes or aliases.
label NonEmptyString no Human-readable label for the route, if present.
locale NonEmptyString no Locale key when the route belongs to a localized page family.

Selected field examples

  • originKey: Example: "archive"
  • path: Example: "/spark/4.0.0/docs/"
  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"
  • section: Example: "documentation"
  • routeKind: Example: "docsRoot"
  • targetId: Example: "spark-runtime-4.0.0-docs"
  • label: Example: "4.0 docs"
  • locale: Example: "en"

TranslationSetAggregateEntry

Entry in data/translations.json.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
translationKey NonEmptyString yes Shared key that ties all translated sibling pages in this set together.
componentSlug Slug yes Owning component slug for the translation set.
artifactKey ArtifactKey no Owning artifact key when the translation set belongs to a specific artifact.
entries list[TranslationLinkSummary] yes Translated sibling pages that belong to the same translation set.

Selected field examples

  • translationKey: Example: "spark-overview"
  • componentSlug: Example: "spark"
  • artifactKey: Example: "runtime"