Catalog Item Schema

Summary

This ADR defines the structure for Catalog Items in the DCM Service Catalog.

Motivation

Catalog Items wrap service specifications with validation rules and defaults, enabling administrators to create curated offerings. The design is both provider-agnostic and service type-agnostic — Catalog Items work with any service type defined in Service Type Definition

Goals

• Define the structure for Catalog Items
• Maintain independence between service types while applying consistent design patterns
• Add validation rule
• Enable administrators to create curated offerings for users
• Design catalog schemas as service type and provider-agnostic and service type-agnostic specifications that Service Providers can translate to their native platform formats

Non-Goals

• Defining the service schemas themselves (see ADR - ServiceType )

Proposal

The catalog schema acts as a translation layer between what the DCM users want (abstract service specifications) and what providers deliver (platform-specific implementations).

Implementation Details/Notes/Constraints

Catalog Item

A catalog item wraps a service specification with validation rules and defaults. Administrators create catalog offerings like “Small Dev VM” or “Production Database” that users can request without knowing the underlying details.

apiVersion: v1alpha1
kind: CatalogItem
metadata:
  name: production-postgres
spec:
  serviceType: database
  schemaVersion: v1alpha1
  fields:
    - path: "engine"
      default: "postgresql"
    - path: "version"
      editable: true
      default: "15"
      validationSchema: { enum: ["14", "15", "16"] }
    - path: "resources.cpu"
      editable: true
      default: 4
      validationSchema: { minimum: 2, maximum: 16 }
    - path: "resources.memory"
      editable: true
      default: "16GB"

See catalog-item-schema.yaml for complete schema definition.

CatalogItem components

Each field in the fields array has:

Fields not listed are neither editable nor have default values. The catalog item owner must ensure all mandatory fields are listed.

Example “Development VM” CatalogItem - only CPU and memory required

apiVersion: v1alpha1
kind: CatalogItem
metadata:
  name: dev-vm
  displayName: "Development VM"
spec:
  serviceType: vm
  schemaVersion: v1alpha1
  fields:
    - path: "vcpu.count"
      displayName: "CPU Count"
      editable: true
      default: 2
      validationSchema: { minimum: 1, maximum: 4 }
    - path: "memory.size"
      displayName: "Memory"
      editable: true
      default: "4GB"
      validationSchema: { minimum: 2, maximum: 8 }
    - path: "guestOS.type"
      displayName: "Operating System"
      editable: false
      default: "rhel-9"

Multiple CatalogItems can reference the same ServiceType with different constraints: a Production VM item could require vcpu.count between 4-16 instead of 1-4, while sharing the same underlying vm ServiceType definition.

Versioning

CatalogItems use two version fields:

• apiVersion: Versions the CatalogItem schema itself (e.g., v1alpha1). Enables evolution of the CatalogItem structure.
• schemaVersion: Versions the referenced ServiceType schema (e.g., v1alpha1). Creates a contract for ServiceType payload generation.

The schemaVersion enables:

• SP selection: Version info can be used for placement decisions (e.g., excluding SPs that don’t support a given schema version)
• Schema evolution: New schema versions can add/modify fields while older catalog items continue working
• Common naming: All SPs serving the same serviceType@schemaVersion must understand the same field names

Design Details

Validation

The validationSchema field follows JSON Schema (draft 2020-12).
This standard supports:

• Numeric constraints: minimum, maximum, multipleOf
• String patterns: pattern, minLength, maxLength
• Enumerations: enum
• Array constraints: minItems, maxItems
• Conditional logic: if/then/else

For the complete validation vocabulary, see the JSON Schema Validation specification.

Data Flow

1. Admin creates CatalogItem with defaults and validation rules
2. User requests service from CatalogItem
3. User submits request (UI may validate against validationSchema for early feedback)
4. DCM validates input against validationSchema and translates CatalogItem + user input into ServiceType payload
5. Placement Service calls policy engine for validation/mutation
6. Once approved, Placement Service selects a Service Provider and sends the ServiceType payload
7. Service Provider translates the ServiceType payload to their native format

Note: The validationSchema is used by both UI (for UX) and DCM (for enforcement). Users may bypass the UI (CLI, Ansible, cURL), so DCM must always validate.