Metadata

The Wikipedia entry on metadata^[17] begins by saying that metadata is “data about data.” That is true but not usably specific. In Clojure, metadata is data that is orthogonal to the logical value of an object. For example, a person’s first and last names are plain old data. The fact that a person object can be serialized to XML has nothing to do with the person and is therefore metadata. Likewise, the fact that a person object is dirty and needs to be flushed to the database is metadata.

The Clojure language itself uses metadata in several places. For example, vars have a metadata map containing documentation, type information, and source information. Here is the metadata for the str var:

Some common metadata keys and their uses are shown in the following table.

Much of the metadata on a var is added automatically by the Clojure compiler. To add your own key/value pairs to a var, use the metadata reader macro:

For example, you could create a simple shout function that upcases a string and then document that shout both expects and returns a string, using the :tag key:

You can inspect shout’s metadata to see that Clojure added the :tag:

You provided the :tag, and Clojure provided the other keys. The :file value NO_SOURCE_PATH indicates that the code was entered at the REPL.

Because :tag metadata is so common, you can also use the short-form ^Classname, which expands to ^{:tag Classname}. Using the shorter form, you can rewrite shout as follows:

If you find the metadata disruptive when you’re reading the definition of a function, you can place the metadata last. Use a variant of defn that wraps one or more body forms in parentheses, followed by a metadata map: