1 files changed, 65 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..169e103
--- /dev/null
+++ b/README.org
@@ -0,0 +1,65 @@
+#+TITLE: JSON meta library
+
+* What is a meta library?
+The purpose of this library is to be a portable shim for many JSON libraries.
+
+* Why?
+If one wants to write portable Scheme which does some JSON processing, one must either:
+
+- Abandon hope of being portable, and depend on an implementation specific library.
+- Use a portable JSON library which is redundant, and may conflict with other libraries that expect parsed JSON to be represented in a certain way.
+- Write a bunch of cond-expands to act as a portability layer, and use different JSON libraries in different contexts.
+
+This library aims to be an implementation of the latter which you can just plug in as a dependency, instead of writing your own.
+
+* API
+** Constructors
+~(json-object pairs ...)~:
+Constructs a new JSON object.
+pairs are ~pair?~ objects with a ~string?~ as the ~car~, and a ~json-value?~ as the ~cdr~.
+
+An alist can be converted to a JSON object like so: ~(apply json-object alist)~
+
+~(json-list objs ...)~:
+Constructs a new JSON list.
+objs are ~json-value?~ objects.
+
+A list can be converted to a JSON list like so: ~(apply json-list some-list)~
+
+~json-null~:
+This is not a constructor, but instead it is a value which represents null in JSON.
+** Predicates
+~(json-value? obj)~:
+Returns true if ~obj~ is a value that can be serialized as JSON.
+This is true for values related to the constructors, and for numbers, strings, and booleans.
+
+~(json-object? obj)~:
+Returns true if ~obj~ is a value that can be serialized as a JSON object.
+Either the result of deserializing a string formatted as a JSON object, or from the ~json-object~ constructor.
+
+~(json-list? obj)~:
+Returns true if ~obj~ is a value that can be serialized as a JSON list.
+Either the result of deserializing a string formatted as a JSON list, or from the ~json-list~ constructor.
+
+~(json-null? obj)~:
+Returns true if ~obj~ is ~eq?~ to ~json-null~.
+** Serialization
+~(json->string obj)~:
+Convert a ~json-value?~ to a JSON formatted ~string?~.
+
+~(string->json str)~
+Converts a ~string?~ into a ~json-value?~
+** Selectors
+~(json-object-ref obj key)~:
+Returns the ~json-value?~ associated with ~key~ in ~obj~.
+~key~ should be a ~string?~, and the behavior when ~obj~ does not contain ~key~ is currently undefined.
+
+~(json-list-ref lst i)~:
+Returns the ~json-value?~ at index ~i~
+
+** Conversion
+~(json-object->alist obj)~:
+Convert ~obj~ to a ~list?~ of ~pair?~ where the ~car~ of each pair is a ~string?~ and the ~cdr~ is the associated ~json-value?~.
+
+~(json-object->list lst)~:
+Convert ~lst~ to a ~list?~ of ~json-value?~.