Example of custom format values?

[thockin]

Everything I can find says that format may have "any value", but I am here to ask if there are conventions, norms, or even "don't do that" hazards in this sapce.

I work with Kubernetes, and we would like to expose more of our custom string-formats as OpenAPI, and format seems like the right description. I am worried about 3 things: 1) Making sure it is clear that these are non-standard formats and defined by Kubernetes; 2) Making sure we don't pick a name that has meaning elsewhere (or might have meaning at some future date); 3) Making sure we don't break some parsing rule I don't know about.

So for example, suppose we have a format which is "roughly a dns subdomain", but does not match any standard format.

Should the format name be:

• dns-subdomain (implies genericness which is not true)
• k8s-dns-subdomain
• x-k8s-dns-subdomain
• k8s.io/dns-subdomain (follows style of k8s labels)
• k8s(dns-subdomain)

or something else?

[ralfhandl]

If "roughly a dns subdomain" is K8s-specific, then k8s-dns-subdomain is fine because:

• the registered format names have dash-separated names.
• the k8s- prefix makes it clear who defines that format and is unlikely to collide with someone else's format names.
• it leaves the door open to register a standard format dns-subdomain that exactly follows the RFC1034 rules.

You might want to register your custom formats in https://spec.openapis.org/registry/format/index.html.