Feature Request: Default Values for Listing Fields

[JGeanca]

Hi, I just wanted to ask if it’s possible to add something like the following. It would be very useful!

Problem Statement

Currently, PKL supports default values for scalar fields:

class Config {
  environment: String = "production"
  timeout: Int = 30
}

However, there's no way to define default values for Listing fields that get merged with user-provided items or injected when certain items are missing:

class Config {
  // How to ensure certain items always exist in the list?
  tags: Listing<Tag>
  
  // How to provide defaults that merge with user items instead of being replaced?
  permissions: Listing<Permission>
}

Use Case

When defining configuration schemas, it's common to have lists where:

1. Certain items must always exist (e.g., a default role, a system-reserved tag)
2. User-provided items should extend defaults, not replace them

Currently, if you define:

class Config {
  roles: Listing<Role> = new Listing {
    new Role { name = "default" }
  }
}

The default is completely replaced when a user provides any value. There's no way to express "always include these items, plus whatever the user adds."

Current Workarounds

All workarounds have significant drawbacks:

Workaround	Drawback
Post-process in host language (Go, Java, etc.)	Defeats declarative purpose; defaults scattered across schema and code
Require users to always specify required items	Error-prone; duplication
Use PKL amendments with helper modules	Complex; not enforceable at schema level

Desired Behavior Suggestions

Merge semantics for Listing defaults

A way to specify that default items should be merged with user-provided items:

class Config {
  roles: Listing<Role> = new Listing {
    @MergeDefault
    new Role { name = "default" }
  }
}

Conditional injection constraint

A constraint that injects an item if a predicate isn't satisfied:

class Config {
  roles: Listing<Role>(
    ensureContains((r) -> r.name == "default", new Role { name = "default" })
  )
}

defaultItems modifier

Similar to how default works for scalar fields:

class Config {
  roles: Listing<Role> {
    defaultItems {
      new Role { name = "default" }
    }
  }
}

[HT154]

Hi there! If I'm interpreting your ask correctly, Pkl already provides what you're looking for. Building from your example:

class Config {
  roles: Listing<Role> = new { // note: no `new Listing`, Pkl infers the type for `new` is `Listing<Role>`
    new { name = "default" } // note: no `new Role`, Pkl infers the type for new within the `Listing` is `Role`
  }
}

Note

I've elided explicit types for your new incantations.
It is typically best practice (and less typing) to do this.
In fact, it's common for end-user modules (those amending a schema) to never use an explicitly-typed new (and only use the implicitly-typed new inside Listings), unless polymorphism is in play.

There are a few ways a user might use this class:

// completely replace/override the default value in the class
config1: Config = new {
  roles = new Listing<Role> { ... } // or `new Listing`
}

// replace/override the value with a new one that amends the default value in the class, adding more elements
config2: Config = new {
  roles = new { ... }
}

// amend the parent value (in this case the default value in the class), adding more elements
config3: Config = new {
  roles { ... }
}
// in the scenario the result is the same as config2 but the meaning is subtly different
// and manifests when amending values, not instantiating classes
// see https://pkl-lang.org/main/current/language-reference/index.html#implicitly-typed-new

Note

The third method—parent amending—is the most common way that Pkl schemas are amended.
That it is the shortest to type and often the simplest to reason about is not a coincidence!

Finally, since you want to enforce that some default role is always present, using a type constraint is a typical approach:

const defaultRole: Role = new { name = "default" }

class Config {
  roles: Listing<Role>(toSet().contains(defaultRole)) = new {
    defaultRole
  }
}

Another approach here is splitting the property into a hidden/fixed pair. This makes some documentation/usability tradeoffs, but is sometimes preferable. It looks something like this:

class Config {
  hidden roles: Listing<Role>
  fixed effectiveRoles: Listing<Role> = (roles) {
    new { name = "default" }
  }
}