When to use simple/qualified keywords?

Question

Is there any "official" guidance on this?

Clojure.spec uses both:

(s/def ::foo (s/keys :req [::bar]))

The current usecase I'm wondering about is an internal API I'm working on. It is pretty clear that top-level keys in the api response benefit from being qualified. How about keywords in value positions?

{:my.api.person/name "Imre"
 :my.api/result-type :success ;; :my.api.result/success perhaps?
 :my.api/warnings [:quota-exceeded :my.api.quota/exceeded]}

Edit: Slack discussion where I brought this up first

Answer 1

Spec's guidance on this can be best found at https://clojure.org/about/spec#_global_namespaced_names_are_more_important - spec strongly encourages the use of qualified attribute spec names as map keys when the data is likely to be shared with others, or composed with data from other libraries or sources.

However, this is not the only concern - we are also concerned about readability, write-ability, etc. In some cases, an attribute (or a value) may only exist in a context, such that qualification is not necessary and can be inferred from the container. In the example above, I'm not sure there is a ton of value in qualifying the value - it will presumably only be set/compared in the context of its attribute, which is qualified.