[Initiative] Kubernetes-style Catalog Frontmatter

[juliuskrah]

Summary

Add Kubernetes-style frontmatter (apiVersion, kind, metadata, spec) to product, category, and collection files for better configuration management and consistency.

Scope

In scope:

• apiVersion, kind, metadata, spec, status fields for products, categories, collections
• Schema validation on push
• Migration guide from current frontmatter format

Out of scope:

• Custom resource definitions beyond core catalog types

Acceptance Criteria

• All three catalog types accept the new frontmatter schema
• Schema validation rejects invalid documents at push time
• Existing catalog files can be migrated with a provided script
• Docs updated with new format examples

Implementation Notes

The common schema for all resource types:

• apiVersion (string)
• kind (string)
• metadata (ObjectMeta)

---
apiVersion: catalog.gitstore.dev/v1beta1
kind: Product
metadata:
  name: macbook-pro-2026
  labels:
    gitstore.dev/brand: Apple
    processor: M3 Max
    ram: 36GB
    storage: 1TB SSD
  creationTimestamp: "2026-05-01T14:45:27Z"
spec: {}
status: {} # machine generated
---

# MacBook Pro 16" with M3 Max

The most powerful MacBook Pro ever. Supercharged by the M3 Max chip.

## Features

- M3 Max chip with up to 40-core GPU
- 36GB unified memory
- 1TB SSD storage
- 16-inch Liquid Retina XDR display

ObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

• name (string)
• generateName (string)
• namespace (string)
• labels (map[string]string)
• annotations (map[string]string)

System

• ownerReferences ([]OwnerReference)
  • ownerReferences.apiVersion (string)
  • ownerReferences.kind (string)
  • ownerReferences.name (string)
  • ownerReferences.uid (string)

Read Only

• creationTimestamp (Time)
• uid (string)
• resourceVersion (string)
  An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources.
• generation (int64)
• revision (string) The revision e.g. main@sha1:a1b2c3d

LabelSelector

A label selector is a label query over a set of resources.

• matchExpressions ([]LabelSelectorRequirement)
  • matchExpressions.key (string)
  • matchExpressions.operator (string)
    valid operators are In, NotIn, Exists and DoesNotExist
  • matchExpressions.values ([]string)
    if the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.
• matchLabels (map[string]string)

ObjectReference

ObjectReference contains enough information to let you inspect or modify the referred object.

• apiVersion (string)
• fieldPath (string)
  if referring to a piece of an object instead of the entire object, this string should contain a valid JSON/Go field access statement, such as spec.mediaFrom[1]. For example, if the object reference is to a media within a product, this would take on a value like: spec.mediaFrom{name} (where "name" refers to the name of the media within the product.
• kind (string)
• name (string)
• namespace (string)
• resourceVersion (string)
• uid (string)

Typical Status Properties

• conditions ([]Condition)
  • conditions.type (string)
  • conditions.status (string) One of True, False or Unknown
  • conditions.observedGeneration (int64)
  • conditions.lastTransitionTime (Time)
  • conditions.reason (string)
  • conditions.message (string)
• lastAppliedRevision (string) e.g.

  status:
    lastAppliedRevision: main@sha1:a1b2c3d

• resolved (Resolved..Definition)
• observedGeneration (int64)
• phase (string) ? Deprecated in Eliminate Phase and simplify Conditions kubernetes/kubernetes#7856

Note

The core schemas are created based off of the latest JSON Schema (2020-12). They are then imported into the individual schemas of the subtasks

Tracking

• Milestone: TBD
• Labels: area/catalog, priority/p1