extension proposal

First draft

Mostly a conversation piece here, but I've sat on this for too long.

Fixes #74

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

ext/README.md

@@ -0,0 +1,49 @@
+# Extensions
+
+The basis of the Extension API is described in a document which should be emulated for all extensions.
+
+## Table of Contents
+
+<!-- toc -->
+* [Table](#table)
+* [Name](#name)
+* [Filename](#filename)
+* [Detail](#detail)
+* [Prior Art](#prior-art)
+<!-- /toc -->
+
+## Table
+
+_notice_: All new `./ext/ext-$name.md` docs MUST be added to this table.
+
+| `$name`  | Definition | Summary |
+|:--:|:--:|:--:|
+| 0 | [ext-0](./ext-0.md) | Base definition of discovering extensions on registry server |
+|  |  |  |
+
+
+## Name
+
+Extension names MUST be unique.
+Names SHOULD include a version.
+
+Each extension's endpoints will be nested below its name.
+
+```HTTP
+    GET /v2/ext/0/...
+```
+
+## Filename
+
+XXX
+
+## Detail
+
+XXX acceptable error codes
+
+## Prior Art
+
+When considering the proposal structure for these extensions, the following processes were considered:
+
+* [Python PEP](https://www.python.org/dev/peps/)
+* [Kubernetes KEP](https://github.com/kubernetes/enhancements/tree/master/keps)

ext/ext-0.md

@@ -0,0 +1,14 @@
+# ext-0 -- Index of Distribution Extensions
+
+## Table of Contents
+
+<!-- toc -->
+* [Summary](#summary)
+* [Reference Explanation](#reference-explanation)
+<!-- /toc -->
+
+## Summary
+
+This base extension is to return the array of names of the extensions.
+
+## Reference Explanation

spec.md

@@ -33,6 +33,7 @@ The goal of this specification is to standardize container image distribution ba
   - [Listing Repositories](#listing-repositories)
   - [Listing Image Tags](#listing-image-tags)
   - [Deleting an Image](#deleting-an-image)
+  - [Extensions](#extensions)
 - [Detail](#detail)
   - [Errors](#errors-2)
   - [Base](#base)
@@ -840,6 +841,25 @@ If the image had already been deleted or did not exist, a `404 Not Found` respon
 
 > for more details, see: [compatibility.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#backward-compatibility)
 
+### Extensions
+
+Extensions to the distribution-spec's registry API are for the purpose of defining OPTIONAL endpoint behaviour.
+Extensions are only complementary to the distribution-spec only having additive features.
+Client can discover the extensions available, if any.
+
+These extensions are similar concept to the use of "feature flags".
+
+See the [`./ext/` directory](./ext/) for extensions available and their definitions.
+
+Extensions MUST NOT affect the behavior or endpoints of the core distribution specification.
+
+All extension endpoints are nested under `ext/`.
+
+```HTTP
+    GET /v2/ext/0/
+```
+
+
 ## Detail
 
 > **Note**: This section is still under construction.