From 6e37c62057088a95ff5dbe1c4d37c0b47321ffb9 Mon Sep 17 00:00:00 2001
From: Vincent Batts <vbatts@hashbangbash.com>
Date: Wed, 11 Mar 2020 14:31:00 -0400
Subject: [PATCH] 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 | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 ext/ext-0.md  | 15 +++++++++++++++
 spec.md       | 20 ++++++++++++++++++++
 3 files changed, 84 insertions(+)
 create mode 100644 ext/README.md
 create mode 100644 ext/ext-0.md

diff --git a/ext/README.md b/ext/README.md
new file mode 100644
index 00000000..5a7f58c3
--- /dev/null
+++ b/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)
diff --git a/ext/ext-0.md b/ext/ext-0.md
new file mode 100644
index 00000000..b1c941f5
--- /dev/null
+++ b/ext/ext-0.md
@@ -0,0 +1,15 @@
+# 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
+
diff --git a/spec.md b/spec.md
index 6ce6b735..b4002823 100644
--- a/spec.md
+++ b/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.