Missing marker for 'title' key

[braghettos]

Hi everyone - I would like to generate a CRD that includes the 'title' key, but I'm unable to find a marker that allows me to generate it - I cannot find it here: https://book.kubebuilder.io/reference/markers/crd - am I missing something?

Thanks for any help!

[sbueringer]

Sounds good. Feel free to open a PR

[JoelSpeed]

Title is a new one to me, can you expand on the use case at all?

What is the effect of the title on the openapi schema? Is this somehow presented to users via kubectl explain or some other mechanism?

[sbueringer]

I don't know what the use case behind it is, but it's a field in jsonschemaprops in CRDs. So I thought it makes sense to be able to set this field via controller-gen as well.

Independent of that, also curious about the use case

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[braghettos]

I don't know what the use case behind it is, but it's a field in jsonschemaprops in CRDs. So I thought it makes sense to be able to set this field via controller-gen as well.

Independent of that, also curious about the use case

Sorry for the late response @sbueringer - the use case is that we're using CRDs to automatically render forms in the Internal Developer Portal of our open-source platform https://github.com/krateoplatformops/krateo so having 'title' available would be a great advantage for us.

[sbueringer]

/remove lifecycle/stale
/lifecycle frozen

[sbueringer]

/help

[k8s-ci-robot]

@sbueringer:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[braghettos]

Hi @sbueringer @JoelSpeed, is there any space for the contributors to add this request to the backlog? Since Kubernetes CRDs are accepting this field, it would be great if markers could support it.

[JoelSpeed]

At the moment, I don't entirely understand the use case, and if we are going to add this, I'd expect a wider use case that covers Kubernetes in general, and I'd like to know what effect setting this field within the schema has.

I can see that the field exists, https://github.com/kubernetes/apiextensions-apiserver/blob/3f4850cd459d7d7324f9c76f0932096fbe3d10a8/pkg/apis/apiextensions/v1/types_jsonschema.go#L75, but I'm not sure what it's used for. Could someone do some research and explain the effect and use case if I were to set the title within the schema of a CRD?

[braghettos]

Use Case

The title field in OpenAPI schemas is primarily used for documentation and UI presentation purposes. It provides a human-readable name for the schema, which can improve usability in tools that visualize or interact with OpenAPI definitions. Some possible benefits of supporting title in CRDs include:

• Better UX in API Browsers and Documentation Tools: OpenAPI-based tools (e.g., Swagger UI, Redoc) often use the title field for presenting schema names more clearly.
• Improved Discoverability in Code Generators: Some client generators may use the title field to provide meaningful names instead of relying on generic names inferred from kind.
• Consistency with OpenAPI: OpenAPI 3.0 schemas define title as a standard field, so supporting it aligns with broader API documentation practices.

Effect of Setting title in CRD Schema

The Kubernetes API machinery does not currently use the title field for validation or enforcement. However, if included in the OpenAPI schema of a CRD, it could affect:

• Client-Side Tooling: Any tools that parse CRD OpenAPI specs might display or utilize the title field, improving clarity.
• API Documentation Generators: If Kubernetes exposes the CRD OpenAPI schema via discovery endpoints, API documentation tools could leverage title to present schemas more effectively.
• No Runtime Behavioral Changes: Since title is not enforced by the Kubernetes API server, adding it would be purely for documentation and tooling purposes.

Would this be an acceptable justification for supporting title? Happy to dive deeper if needed!

[JoelSpeed]

Can you possibly provide a concrete example of what a field name and title might look like?

I'm thinking about Kube conventions. For documentation on fields, we start the comment (which becomes description in the openapi schema) with the serialised version of the field name.

The idea here is that this means that the description, when read, uses the version of the field name that the user is most likely to be familiar with. When you kubectl explain ... .spec.foo the output will start with foo does something

I wonder how a title would fit in here?

[braghettos]

HI @JoelSpeed - thanks for the follow-up! I'll provide a concrete example and clarify how title could fit alongside existing conventions.

Example: Field Name vs. Title in OpenAPI Schema

Consider a CRD defining a BackupPolicy resource with the following field:

spec:
  retentionPeriod:  # Field name
    type: integer
    description: "retentionPeriod defines the number of days backups should be retained."
    title: "Backup Retention Period"

How does this align with Kubernetes conventions?

• The field name remains retentionPeriod, which is what users interact with in manifests and kubectl explain.
• The description still starts with retentionPeriod to match API documentation standards.
• The title serves as an optional, higher-level label that could enhance readability in tools parsing OpenAPI specs.

How Would title fit into Kubernetes?

• kubectl explain wouldn’t change since it relies on description, not title.
• OpenAPI-based tools (like Swagger UI, Redoc) could display title in headings, making schemas easier to scan.
• title does not change validation behavior—it’s purely a documentation enhancement.

Would this kind of usage make sense within the Kubernetes ecosystem? Open to refining the proposal if needed!

[JoelSpeed]

I can see the argument here, I'd be interested to get the opinion of the sig-api-machinery folks though, in case they know of any existing use case for the field that we haven't considered

[braghettos]

I can see the argument here, I'd be interested to get the opinion of the sig-api-machinery folks though, in case they know of any existing use case for the field that we haven't considered

That's a great idea @JoelSpeed, should we tag them here?

[fedebongio]

/cc @jpbetz @deads2k @sttts in case you have an opinion on this use case?

[sttts]

No concerns to add a marker. It is not used today by Kube, but added just for completion as OpenAPI has it.

Note that afaik it is not exposed in the OpenAPI spec by kube-apiserver. So this is only useful for tooling that depends on CRDs directly. If there is value, I don't there is a reason not to expose it in OpenAPI too.

[JoelSpeed]

@braghettos I believe you tested and adding a title key to the CRD schema does mean it's exposed via openapi right? I thought you mentioned that to me in DM?

[camilamacedo86]

Just to share, the documentation at this link is generated based on the controller-tools code. So, once it is added to this project, released, and the new version is bumped in Kubebuilder, the documentation will be updated accordingly.

[braghettos]

@braghettos I believe you tested and adding a title key to the CRD schema does mean it's exposed via openapi right? I thought you mentioned that to me in DM?

Exactly, I have manually added the title key in the CRD schema (row 62 in the attached file) and I was able to find it via

kubectl get --raw /openapi/v2 | jq '.definitions["io.krateo.composition.v1-1-13.FireworksApp"]'

crd.json