Central repository for clojure specs

clojure_spec

#1

I’m wondering if it would make sense to have a way to share and discover existing specs.

Looking at things like https://github.com/roman01la/cljss/blob/master/src/cljss/media.clj (specs for media queries)
or
https://github.com/SparkFund/useful-specs, it would be a unfortunate to have to rewrite those specs over and over because we have no way to find them.
I don’t necessarily think we should have them on clojars but at least a way to search and be redirected to the right gist or repo would save some time.

Bonus point: we can even require/eval those specs in some way and provide an endpoint to generate/sample/exercise in the format of choice.
This would help quickly see how the data looks like or even provide “api mocking” when you spec an api like github or something.

Would it be useful ?


#2

That sounds like a neat idea. A very basic version could be just a simple website with a curated set of jars (on Clojars) that can be loaded to get certain specs.

Once the community embraces this kind of thing you could look into extending it with other useful functionality.


#3

This is a great idea! I’m all for a website which makes it nice & searchable.

For a less basic version, we could display the spec code & usage examples in addition to the dependency you’d need to pull in, in case someone just wants to get a rough “sketch” of a spec (I imagine there are lots of application where it’s not possible to give a “general” spec, email addresses might be constrained in special ways or similar issues).


#4

ok, so you think it should necessarily be made available on clojars ?

Do you think there is less value if it’s just a link to a file like here https://github.com/roman01la/cljss/blob/master/src/cljss/media.clj ?


#5

I think a “spec project” should only contains the spec and the functions to support them. If somr spec are strongly related to a project, the two should be kept separated.

Hosting spec on clojars or on a separate platform is a good question. The pro of using clojar is there is only one platform for both sources and specs. On the other hand, it may be less practical to index them on a central website (e.g. to search them, a la Hoogle).

If a reverse index could be built from record/function to spec, it would be a great opportunity to index “similar function”. Since they can be specified at a more precise level than types, it could leverage new version of system.


#6

If you decide not to go with an established dependency system (those specs are a dependency) you’ll need to think about the following things:

  • versioning
  • deployment / updates
  • tooling to download / update
  • perhaps more

For a prototype something like plain files might be ok but I believe in the end you’ll find yourself using Clojars/Maven :slight_smile:


#7

Systems like Grimoire could help with this indexing — maybe @arrdem has thoughts on integrating Specs into the grimoire.thing model?


#8

Make sense !

I won’t decide anything cause I’ll only do it if that’s interesting to other people and I’m not alone doing it.


#9

I don’t want to push you into doing anything but in my experience most collective efforts originate from one person just going ahead and making stuff. I do believe this could have value so consider starting small — maybe just a repo with a nice REAMDE that contains spec-only projects which you can publish to Clojars.
You could copy those specs from existing projects (under the conditions of their LICENSE).


#10

I appreciate the advice, I’ll do that, thanks !


#11

I really like the idea of having a website where I can search specs. To make specs sharable they probably should be distributed as separate packages e.g. cljss could have a companion package cjss.specs


#12

This is an interesting discussion, though I would like to know more about how specs are intended to be distributed and used at all, especially in libraries.

There seems to be an emerging convention where specs for namespace mylib.myns live in mylib.myns.specs (mylib.myns.specs.alpha?). Tooling will want to discover these specs, for example for presenting enhanced function signatures from s/fdef specs. So how are a library’s specs discovered in general? Or is there always a manual (require 'specs) step involved?

Apologies if this is outside the scope of this thread.


#13

Having specs in a separate namespace (as clojure.java.jdbc does, or even in a separate project as clojure.core.specs.alpha does) makes sense when:

  1. You want the code to support pre-1.9 versions of Clojure
  2. You want to publish specs independently of code, e.g., you write specs for a 3rd party library or domain model

Otherwise, if you are writing fdef specs and only care about/support Clojure 1.9, you probably want them right there above the functions to which they belong.


#14

Here is the repository :

Just started with the few I had in minds.
After a while, I think I will filter / separate the one that are on their own project and can be required as a dependency.

Any idea how/where to find more specs ?


#15

Maybe go through the most used/popular Clojure libraries and see if they have specs in the repo. Also ask on r/Clojure


#16

Maybe @colinfleming could shed some light here. Have you considered something like this for Cursive?


#17

I went through this list today to see if there was some spec on those repo https://jakemccrary.com/blog/2017/04/17/what-are-the-most-used-clojure-libraries/

I’m struggling using github search to find repo with more than 100 stars that have code with “clojure.spec”.
It returns repository with clojure.spec in their description and with more than 100 stars.
it also returns code with clojure.spec but for any repo popularity. I can’t find a way to mix both


#18

This can be very useful also for tracking external specifications that are used in in Clojure or ClojureScript. One example is the vast panoply of html keywords. I started (very partially) doing this in https://github.com/deg/sodium/blob/master/src/sodium/keys.clj, but it should really be broken out from that project and live in a more central place.


#19

About the distribution you may want to pick some ideas from other environments. Typescript for example has an hughe repository with type files for all kind of popular libraries. That way the community can contrite it. Then each library definition is published to npm under the @types name space, so all you have to do to see if there is an existing spec is go to npm and search for @types/lodash for example, and if you want to use it then just make npm install. Even if you don’t want to use them in your project this allows all sort of automatic behaviors. Visual Studio code for example downloads type definitions automatically for the libraries you use and provide intellisense based on them, even if you don’t use typescript at all.

Just my two cents


#20

Anothre URI spec here.