add support for /cap?offered

Signed-off-by: Doug Davis <[email protected]>

core/spec.md

@@ -111,9 +111,9 @@ For easy reference, the JSON serialization of a Registry adheres to this form:
   "capabilities": {                     # Supported capabilities/options
     "enforcecompatibility": BOOLEAN, ?
     "flags": [                          # Query parameters
-      "doc",? "epoch",? "filter",? "inline",?
-      "nodefaultversionid",? "nodefaultversionsticky",? "noepoch",?
-      "noreadonly",?  "schema",? "setdefaultversionid",? "specversion",?
+      "doc",? "epoch",? "filter",? "inline",?  "nodefaultversionid",?
+      "nodefaultversionsticky",? "noepoch",?  "noreadonly",?  "offered",?
+      "schema",? "setdefaultversionid",? "specversion",?
       "STRING" *
     ],
     "mutable": [                        # What is mutable in the Registry
@@ -1875,11 +1875,17 @@ Where:
   extensions use some domain-specific name to avoid possible conflicts with
   other extensions.
 
+All capability values, including extensions, MUST be defined as one of the
+following:
+- Numeric (one of: integer, unsigned integer, float)
+- Boolean
+- String
+- Array of one of the above
+
 Absence of a capability in the capability map is an indication of that feature
 not being supported, or if it is specification mandated feature, then its
 configuration is the default value as specified by this specification.
-Each capability MAY define its own value syntax and all supported extensions
-SHOULD be included in the list.
+All supported extensions SHOULD be included in the list.
 
 Absence, presence, or configuration values of a feature in the map MAY vary
 based on the authorization level of the client making the request.
@@ -1978,6 +1984,8 @@ extension values.
 For clarity, servers SHOULD include all capabilities in the serialization,
 even if they are set to their default values or have empty lists.
 
+#### Updating the Capabilities of a Server
+
 If supported, updates to the server's capabilities MAY be done via an HTTP
 `PUT`, or `PATCH`, to the `/capabilities` API, or by updating the `capabilities`
 attribute on the root of the Registry. As with other APIs, a `PUT` MUST be
@@ -2035,7 +2043,73 @@ response.
 Regardless of the mechanism used to update the capabilities, the Registry's
 `epoch` value MUST be incremented.
 
----
+In order for a client to discover the list of available values for each
+capability, an HTTP `GET` MAY be sent to the `/capabilities` API with the
+`?offered` query parameter and the response MUST adhere to the following:
+
+```yaml
+GET /capabilities?offered
+
+{
+  "STRING": [ ALLOWED-VALUES ] *
+}
+```
+
+Where:
+- `"STRING"` is the capability name.
+- `ALLOW_VALUES` is an array of the valid values for that capability. The
+  data type of each value MUST adhere to the data type associated with the
+  capability, with the exception of the `#` (range)  variants described below.
+
+For example:
+
+```yaml
+GET /capabilities?offered
+
+{
+  "enforcecompatibility": [ true, false ],
+  "flags": [ "doc", "epoch", "filter", "inline", "nodefaultversionid",
+    "nodefaultversionsticky", "noepoch", "noreadonly", "offered", "schema",
+    "setdefaultversionid", "specversion" ],
+  "mutable": [ "capabilities", "entities", "model" ],
+  "pagination": [ true, false ],
+  "schemas": [ "xRegistry-json/0.5" ],
+  "shortself": [ true, false ],
+  "specversions": [ "0.5" ]
+}
+```
+
+The array of values allows for some special cases:
+- `"*"` mean that all possible values of that data type are allowed.
+- Numeric capabilities MAY express ranges via `"#-#"` (min-max),
+  `"#-"` (value or greater) or `"-#"` (less than or equal to value) where `#`
+  is a valid numeric value.
+- String capabilities MAY include `*` as a wildcard character in a value
+  to indicate zero or more unspecified characters MAY appear at that location
+  in the value string.
+
+A request to update a capability with a value that is compliant with the
+output of the `/capabilities?offered` MAY still be rejected if the server
+determines it can not support the request. For example, due to authorization
+concerns or the value, while syntactically valid, isn't allow in certain
+situations.
+
+For clarity, even in cases where there is no variability allowed with certain
+capabilities they SHOULD still be listed in both the `/capabilities` API
+and the `/capabilities?offered` API to maximize discoverability. For example,
+if `pagination` is not supported, then a server should still include:
+
+```yaml
+  "pagination": false
+```
+
+in the `/capabilities` output, and
+
+```yaml
+  "pagination": [ false ]
+```
+
+in the `/capabilities?offered` output (assuming both APIs are supported).
 
 ### Registry Model
 
@@ -6123,7 +6197,7 @@ Steps to encode a Unicode character:
   bits of the byte.
 
 Percent-encoding SHOULD be performed using upper-case for values A-F,
-but decoding MUST accept lower-case values.
+but decoding MUST accept lowercase values.
 
 When performing percent-decoding, values that have been unnecessarily
 percent-encoded MUST be accepted, but encoded byte sequences which are