I'm trying to define a spec for a portion of the GraphQL schema syntax. Here's what a field type looks like as returned from an API (note that :ofType can be infinitely nested):
{:kind "NON_NULL",
:name nil,
:ofType {:kind "LIST",
:name nil,
:ofType {:kind "NON_NULL",
:name nil,
:ofType {:kind "OBJECT", :name "Comment"}}}}
Currently I have a spec like so to represent this structure:
(spec/def ::kind #{"NON_NULL" "LIST" "SCALAR" "OBJECT"})
(spec/def ::name (spec/nilable string?))
(spec/def ::ofType (spec/or :terminal nil?
:type ::type))
(spec/def ::type
(spec/keys :req-un [::name ::kind ::ofType]))
This is an ok solution, but there are some invariants that I haven't figured out how to capture:
:name
must be nil at all levels except the deepest (terminal) level.:kind
can only equal SCALAR
or OBJECT
at the terminal level.:kind
must equal either SCALAR
or OBJECT
at the terminal level.:kind
cannot equal NON_NULL
in two consecutive levels.Is it possible to capture these rules inside of a spec? Or, if not, is it possible to write a custom generator which abides by these rules?
UPDATE - Generator solution
I was able to build a generator for this purpose. See Rulle's answer below for how to spec this directly.
(spec/def ::kind #{"NON_NULL" "LIST" "SCALAR" "OBJECT"})
(spec/def ::name (spec/nilable string?))
(spec/def ::ofType (spec/or :terminal nil?
:type ::type))
(spec/def ::type
(spec/keys :req-un [::name ::kind ::ofType]))
(spec/def ::terminal-kind #{"SCALAR" "OBJECT"})
(spec/def ::terminal-name string?)
(def terminal-gen
"Returns a generator for a terminal field type.
Terminal field types are either of :kind 'OBJECT' or 'SCALAR', have an :ofType of nil, and a non-nil :name."
(gen/bind
(spec/gen (spec/tuple ::terminal-name ::terminal-kind))
(fn [[name kind]]
(gen/hash-map
:name (spec/gen #{name})
:kind (spec/gen #{kind})
:ofType (gen/return nil)))))
(defn build-type-gen
"Returns a generator which constructs a field type data structure.
An example of a field type:
{ :name nil,
:kind 'NON_NULL',
:ofType {:name nil, <-- a 'modifier layer', these can be infinitely nested
:kind 'LIST',
:ofType {:name nil,
:kind 'LIST',
:ofType {:name 'M17Pyn0zClVD', :kind 'OBJECT', :ofType nil}}}}} <-- Terminal field type
This function works by creating a terminal type generator, then 'wrapping' it with layer generators (NON NULL and LIST)
until it's a given depth. The following constraints are ensured through the process:
1. :name must be nil at all levels except the deepest (terminal) level.
2. :kind can only equal SCALAR or OBJECT at the terminal level.
3. :kind must equal either SCALAR or OBJECT at the terminal level.
4. :kind cannot equal NON_NULL in two consecutive levels."
([max-depth] (if (= max-depth 1) terminal-gen
(build-type-gen max-depth 0 terminal-gen)))
([max-depth curr-depth inner-gen]
(if (< curr-depth max-depth)
(recur max-depth
(inc curr-depth)
(gen/bind inner-gen
(fn [inner-gen]
(if (= "NON_NULL" (:kind inner-gen))
(gen/hash-map
:name (gen/return nil)
:kind (spec/gen #{"LIST"}) ; two NON_NULLs cannot be child-parent
:ofType (spec/gen #{inner-gen}))
(gen/hash-map
:name (gen/return nil)
:kind (spec/gen #{"NON_NULL" "LIST"})
:ofType (spec/gen #{inner-gen}))))))
inner-gen)))
(def type-gen (gen/bind (spec/gen (spec/int-in 1 5)) build-type-gen))
Example:
(gen/generate type-gen)
=>
{:name nil,
:kind "LIST",
:ofType {:name nil,
:kind "LIST",
:ofType {:name nil,
:kind "NON_NULL",
:ofType {:name nil, :kind "LIST", :ofType {:name "KmgbOsy", :kind "SCALAR", :ofType nil}}}}}
You could probably separate it into inner and outer varieties of the ofType
, like this:
(spec/def :inner/name nil?)
(spec/def :inner/kind #{"NON_NULL" "LIST" "SCALAR" "OBJECT"})
(spec/def :inner/ofType (spec/or :inner ::inner
:outer ::outer))
(spec/def ::inner (spec/keys :req-un [:inner/name :inner/kind :inner/ofType]))
(spec/def :outer/name (spec/nilable string?))
(spec/def :outer/kind #{"SCALAR" "OBJECT"})
(spec/def :outer/ofType nil?)
(spec/def ::outer (spec/keys :req-un [:outer/name :outer/kind] :opt-un [:outer/ofType]))
(spec/def ::ofType (spec/or :terminal nil?
:inner ::inner
:outer ::outer))
The last condition, that two NON_NULL
must not follow each other, could be dealt with separately. Note that this function will receive the conformed value when used later on in the spec:
(defn kinds-ok? [of-type]
(->> (second of-type)
(iterate (comp second :ofType))
(map :kind)
(take-while some?)
(partition 2 1)
(some #{["NON_NULL" "NON_NULL"]})
not))
Then we create a top-level spec with this extra condition:
(spec/def ::top (spec/and ::ofType kinds-ok?))
The fact that kinds-ok?
will receive the conformed value and not the raw value is a somewhat surprising, or even annoying, aspect of spec. But this is how it is designed. I am not sure how to make it receive the raw value: if someone knows, feel free to suggest.