What Clojure Spec is and what you can do with it

I started playing with spec because of the idea of automated test generation, but the reality of it is that I use it as a super-charged validation library.

I think this emphasis actually does the library a disservice in that I see new users ask questions along the lines of "Should I use s/valid? to manually check inputs to my API"? The answer to that, in my usage, is "Yes! Of course!", but many people seem to think that they are using Spec wrong if they use it for something other than instrumentation and generation.

so that "john mcallister" yields { :name "john" :lastname "mcallister" } but "john " would yield { :name "john" :lastname nil } (or :todo even)

When writing complicated macros, Spec conforming is so useful!

Also note for others with regard to eagerness, this is only for maps. "When conformance is checked on a map, it does two things - checking that the required attributes are included, and checking that every registered key has a conforming value. We’ll see later where optional attributes can be useful. Also note that ALL attributes are checked via keys, not just those listed in the :req and :opt keys. Thus a bare (s/keys) is valid and will check all attributes of a map without checking which keys are required or optional."

Can you explain the point of :opt with s/keys if it will always check any registered spec in if present?

Conformers are meant to parse the data when there are multiple possibility of what something can validate against, the conformer will disambiguate and return a result that tells you which path was chosen.

Coercion is not supported as part of Spec, you're expected to do that seperatly either before or after validating/conforming.

You should be careful asking for this.

Both Protobufs and Cap'n Proto eventually decided that "optional" creates more grief that it saves.

It is also a bit of a religious flamewar.

Caution is advised.

That's because you don't Spec your functions and macros.

A lot of people have only used Spec to validate data that enters and leaves the boundary of their application. Which is a great use of Spec, and I use Spec mostly for that as well.

But there is a whole other world where Spec was designed to validate your functions and macros as well.

That's where conformers make sense.

For macros, you can use conformers to help you with writing a macro, by using Spec to define a DSL and conform to parse it out for you. It both validates the macro DSL and makes it easier for you to parse it.

For functions, conform can be useful to assert the output is what you expect for some given input. Often times, the output might depend on what kind of input you got. Conform basically tells you the kind of input it was, so in your validation you can validate differently based on each kind conform tells you it received.

This has to do with the philosophy. If you want to write bug free programs, and I mean, if you care A LOT about software correctness.

The idea in that case will be that all your functions will have a set of unit tests and generative tests over them that asserts that for most possible inputs they return the correct output.

Once you know that, you know that if provided valid input, your functions are going to return valid output. Because you know your function works without any bugs.

Thus, you no longer need to validate the output, only the input. Because as I just said, you now know that any valid input will result in your code returning valid output as well. So re-validating the output would be redundant.

And this goes one further. After you've thoroughly tested each functions, now you want to test the integration of your functions together. So you'd instrument your app, and now you'd write a bunch of integration tests (some maybe even using generative testing), to make sure that all possible input from the user (or external systems if intended for machine use) will result in correct program behavior and an arrangement of functions that all call each other with valid input.

Once you've tested that, you now also know that the interaction/integration of all your functions work.

At this point you are confident that given any valid user input, your program will behave as expected in output and side-effect.

You can thus now disable instrumentation.

But before you go to prod, you need one more thing, you have to protect yourself against invalid user input, because you haven't tested that and don't know how your program would behave for it. Thus with Spec, you add explicit validation over your user input which reject at the boundary the input from the user of invalid.

You now know there things:

1. All your individual functions given valid input behave as expected in output and side-effect.

2. Your integration of those functions into a program works for all given valid user input.

3. Your program rejects all invalid user input, and will only process valid user input.

Thus you can go to prod with high confidence that everything will work without any defect.

---

Now back to orchestra. Orchestra assumes that you weren't as vigilant as I just described, and that you might have not tested each and every function, or that you only wrote a small amount of tests for them which only tested a small range of inputs. Thus it assumed because of that, probably when you go towards running functional/integ tests, you want to continue to assert the output of each function is still valid, as you anticipate those will probably create inputs to functions that your tests over that function did not test.

It's not exactly a secret that Spec is not intended to be a type-like system. But it turns out, it's perfectly possible to use Spec as a building block to do so!

As for complexity, I think instrumentation (Spec's approach) is complex. People routinely struggle with it, in fact you must use an external lib (Orchestra) to fully enable it. It also slows down execution, sometimes disproportionally.

Whereas Schema simply has a global toggle that also can be overriden in a fine-grained manner. It's explicitly made to be fast and have a type-like use.

As for type definitions, honestly both are elegant and powerful; you can quite easily use arbitrary predicates as "types" with both, and compose those predicates. Ultimately Spec is better designed because it fosters namespaced-qualifed keywords which compose better.

For addressing the instrumentation problem, I created https://github.com/nedap/speced.def which uses Clojure's :pre system. I have used :pre for over a decade so I know it has an extreme simplicity. Spec can take :pre's usefulness to the next level.