From ff0c9da34286c4f8259c575b76b616ccdac5d86f Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 12:19:01 +0100
Subject: [PATCH 01/11] policy/upstream: add descriptions to the json schema

---
 gateway/src/apicast/policy/upstream/schema.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/gateway/src/apicast/policy/upstream/schema.json b/gateway/src/apicast/policy/upstream/schema.json
index 719842402..78b4d1277 100644
--- a/gateway/src/apicast/policy/upstream/schema.json
+++ b/gateway/src/apicast/policy/upstream/schema.json
@@ -1,17 +1,21 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Upstream policy configuration",
+  "description": "This policy allows to modify the host of a request based on its path.",
   "type": "object",
   "properties": {
     "rules": {
+      "description": "list of rules to be applied",
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
           "regex": {
+            "description": "regular expression to be matched",
             "type": "string"
           },
           "url": {
+            "description": "new URL in case of match",
             "type": "string"
           }
         },

From 104b55d0beec55149830c4850e4d285db658fb46 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 12:37:08 +0100
Subject: [PATCH 02/11] policy/echo: add descriptions to the json schema

---
 gateway/src/apicast/policy/echo/schema.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gateway/src/apicast/policy/echo/schema.json b/gateway/src/apicast/policy/echo/schema.json
index c8354195c..05e40c8bc 100644
--- a/gateway/src/apicast/policy/echo/schema.json
+++ b/gateway/src/apicast/policy/echo/schema.json
@@ -1,12 +1,17 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Echo policy configuration",
+  "description":
+    ["This policy prints the request back to the client and optionally sets ",
+     "a status code."],
   "type": "object",
   "properties": {
     "status": {
+      "description": "HTTP status code to be returned",
       "type": "integer"
     },
     "exit": {
+      "description": "Exit mode. 'request' interrupts the processing of the request, 'phase' only skips the rewrite phase.",
       "type": "string",
       "enum": ["request", "phase"]
     }

From 34f35c0353ee745d23a4a249cb6bedb18065bfd8 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 12:42:40 +0100
Subject: [PATCH 03/11] policy/url_rewriting: add descriptions to the json
 schema

---
 gateway/src/apicast/policy/url_rewriting/schema.json | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/gateway/src/apicast/policy/url_rewriting/schema.json b/gateway/src/apicast/policy/url_rewriting/schema.json
index 07b9637f7..ce7ed435b 100644
--- a/gateway/src/apicast/policy/url_rewriting/schema.json
+++ b/gateway/src/apicast/policy/url_rewriting/schema.json
@@ -1,27 +1,39 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "URL rewriting policy configuration",
+  "description":
+    ["This policy allows to modify the path of a request. ",
+     "The operations supported are sub and gsub based on ngx.re.sub and ",
+     "ngx.re.gsub provided by OpenResty. Please check ",
+     "https://github.com/openresty/lua-nginx-module for more details on how ",
+     "to define regular expressions and learn the options supported."],
   "type": "object",
   "properties": {
     "commands": {
+      "description": "List of rewriting commands to be applied",
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
           "op": {
+            "description": "Operation to be applied (sub or gsub)",
             "type": "string",
             "enum": ["sub", "gsub"]
           },
           "regex": {
+            "description": "Regular expression to be matched",
             "type": "string"
           },
           "replace": {
+            "description": "String that will replace what is matched by the regex",
             "type": "string"
           },
           "options": {
+            "description": "Options that define how the regex matching is performed",
             "type": "string"
           },
           "break": {
+            "description": "when set to true, if the command rewrote the URL, it will be the last one applied",
             "type": "boolean"
           }
         },

From 3bbd27bbe03f43b7d09408eeacecad6fd98dd5fe Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 12:50:35 +0100
Subject: [PATCH 04/11] policy/headers: add descriptions to json schema

---
 gateway/src/apicast/policy/headers/schema.json | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/gateway/src/apicast/policy/headers/schema.json b/gateway/src/apicast/policy/headers/schema.json
index 65b101abe..872600a22 100644
--- a/gateway/src/apicast/policy/headers/schema.json
+++ b/gateway/src/apicast/policy/headers/schema.json
@@ -1,21 +1,30 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Headers policy configuration",
+  "description":
+    ["This policy allows to include custom headers that will be sent to the ",
+     "upstream as well as modify or delete the ones included in the original ",
+     "request. Similarly, this policy also allows to add, modify, and delete ",
+     "the headers included in the response."],
   "type": "object",
   "definitions": {
     "commands": {
+      "description": "List of operations to apply to the headers",
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
           "op": {
+            "description": "Operation to be applied",
             "type": "string",
             "enum": ["add", "set", "push"]
           },
           "header": {
+            "description": "Header to be modified",
             "type": "string"
           },
           "value": {
+            "description": "Value that will be added, set or pushed in the header",
             "type": "string"
           }
         },

From 39ab16789c8e031791def8fef1cf1ca5e07264d6 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 12:58:31 +0100
Subject: [PATCH 05/11] policy/cors: add descriptions to the json schema

---
 gateway/src/apicast/policy/cors/schema.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gateway/src/apicast/policy/cors/schema.json b/gateway/src/apicast/policy/cors/schema.json
index af482ff55..987fb32bf 100644
--- a/gateway/src/apicast/policy/cors/schema.json
+++ b/gateway/src/apicast/policy/cors/schema.json
@@ -1,15 +1,18 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "CORS policy configuration",
+  "description": "This policy enables CORS (Cross Origin Resource Sharing) request handling.",
   "type": "object",
   "properties": {
     "allow_headers": {
+      "description": "Allowed headers",
       "type": "array",
       "items": {
         "type": "string"
       }
     },
     "allow_methods": {
+      "description": "Allowed methods",
       "type": "array",
       "items": {
         "type": "string",
@@ -27,9 +30,11 @@
       }
     },
     "allow_origin": {
+      "description": "Origins for which the response can be shared with",
       "type": "string"
     },
     "allow_credentials": {
+      "description": "Whether the request can be made using credentials",
       "type": "boolean"
     }
   }

From 6a295cb7c797223befcb9be42c11b1a8e2d9d113 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 13:00:46 +0100
Subject: [PATCH 06/11] policy/caching: add descriptions to the json schema

---
 gateway/src/apicast/policy/caching/schema.json | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/gateway/src/apicast/policy/caching/schema.json b/gateway/src/apicast/policy/caching/schema.json
index 43c3db717..5298e7a02 100644
--- a/gateway/src/apicast/policy/caching/schema.json
+++ b/gateway/src/apicast/policy/caching/schema.json
@@ -1,9 +1,26 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Caching policy configuration",
+  "description":
+    ["Configures a cache for the authentication calls against the 3scale ",
+     "backend. This policy support three kinds of caching: \n",
+     " - Strict: it only caches authorized calls. Denied and failed calls ",
+     "invalidate the cache entry.\n",
+     " - Resilient: caches authorized and denied calls. Failed calls do not ",
+     "invalidate the cache. This allows us to authorize and deny calls ",
+     "according to the result of the last request made even when backend is ",
+     "down.\n",
+     "- Allow: caches authorized and denied calls. When backend is ",
+     "unavailable, it will cache an authorization. In practice, this means ",
+     "that when backend is down _any_ request will be authorized unless last ",
+     "call to backend for that request returned 'deny' (status code = 4xx). ",
+     "Make sure to understand the implications of that before using this ",
+     "mode. It makes sense only in very specific use cases.\n",
+     "- None: disables caching."],
   "type": "object",
   "properties": {
     "caching_type": {
+      "description": "Caching mode",
       "type": "string",
       "enum": ["resilient", "strict", "allow", "none"]
     }

From 23112428e1b9df1864e14e5762365935aae3a0be Mon Sep 17 00:00:00 2001
From: Michal Cichra <michal@cichra.cz>
Date: Thu, 25 Jan 2018 10:31:48 +0100
Subject: [PATCH 07/11] policy manifest and its schema

---
 Makefile                                      |  6 +-
 .../src/apicast/policy/manifest-schema.json   | 58 +++++++++++++++++++
 2 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 gateway/src/apicast/policy/manifest-schema.json

diff --git a/Makefile b/Makefile
index d50ad81f8..b5907577d 100644
--- a/Makefile
+++ b/Makefile
@@ -155,9 +155,9 @@ doc: doc/lua/index.html ## Generate documentation
 
 lint-schema: apicast-source
 	@ docker run --volumes-from ${COMPOSE_PROJECT_NAME}-source --workdir /opt/app-root/src \
-	    3scale/ajv validate \
-		-s /usr/local/lib/node_modules/ajv-cli/node_modules/ajv/lib/refs/json-schema-draft-07.json \
-		$(addprefix -d ,$(shell find gateway/src/apicast/policy -name 'schema.json'))
+		3scale/ajv validate \
+		-s gateway/src/apicast/policy/manifest-schema.json \
+		$(addprefix -d ,$(shell find gateway/src/apicast/policy -name 'apicast-policy.json'))
 
 node_modules/.bin/markdown-link-check:
 	yarn install
diff --git a/gateway/src/apicast/policy/manifest-schema.json b/gateway/src/apicast/policy/manifest-schema.json
new file mode 100644
index 000000000..0984e70b7
--- /dev/null
+++ b/gateway/src/apicast/policy/manifest-schema.json
@@ -0,0 +1,58 @@
+{
+  "$id": "http://apicast.io/policy-v1/schema#manifest",
+  "type": "object",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "schema": {
+      "$id": "#/definitions/schema",
+      "$ref": "http://json-schema.org/draft-07/schema#",
+      "default": {}
+    },
+    "version": {
+      "$id": "#/definitions/version",
+      "type": "string",
+      "title": "The Policy Version",
+      "description": "A semantic version of a policy.",
+      "examples": [
+        "1.3.4",
+        "0.1"
+      ],
+      "pattern": "^(\\d+\\.)?(\\d+\\.)?(\\*|\\d+)$"
+    }
+  },
+  "properties": {
+    "name": {
+      "$id": "/properties/name",
+      "type": "string",
+      "title": "The Policy Name",
+      "description": "Name of the policy.",
+      "examples": [
+        "Basic Authentication"
+      ],
+      "minLength": 1
+    },
+    "description": {
+      "$id": "/properties/description",
+      "oneOf": [
+        { "type": "string",
+          "minLength": 1 },
+        { "type": "array", "items": { "type": "string" },
+          "minItems": 1
+        }
+      ],
+      "title": "The Policy Description",
+      "description": "Longer description of what the policy does.",
+      "examples": [
+        "Extract authentication credentials from the HTTP Authorization header and pass them to 3scale backend.",
+        [ "Redirect request to different upstream: ", " - based on path", "- set different Host header"]
+      ]
+    },
+    "version": {
+      "$ref": "#/definitions/version"
+    },
+    "configuration": {
+      "$ref": "#/definitions/schema"
+    }
+  },
+  "required": ["name", "version", "configuration"]
+}

From 6cf0b23f90fb7f76192c1de15757f7517e965508 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 18:01:13 +0100
Subject: [PATCH 08/11] policy: rename json schemas

Just a convention.
---
 .../apicast/policy/caching/{schema.json => apicast-policy.json}   | 0
 .../src/apicast/policy/cors/{schema.json => apicast-policy.json}  | 0
 .../src/apicast/policy/echo/{schema.json => apicast-policy.json}  | 0
 .../apicast/policy/headers/{schema.json => apicast-policy.json}   | 0
 .../apicast/policy/upstream/{schema.json => apicast-policy.json}  | 0
 .../policy/url_rewriting/{schema.json => apicast-policy.json}     | 0
 6 files changed, 0 insertions(+), 0 deletions(-)
 rename gateway/src/apicast/policy/caching/{schema.json => apicast-policy.json} (100%)
 rename gateway/src/apicast/policy/cors/{schema.json => apicast-policy.json} (100%)
 rename gateway/src/apicast/policy/echo/{schema.json => apicast-policy.json} (100%)
 rename gateway/src/apicast/policy/headers/{schema.json => apicast-policy.json} (100%)
 rename gateway/src/apicast/policy/upstream/{schema.json => apicast-policy.json} (100%)
 rename gateway/src/apicast/policy/url_rewriting/{schema.json => apicast-policy.json} (100%)

diff --git a/gateway/src/apicast/policy/caching/schema.json b/gateway/src/apicast/policy/caching/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/caching/schema.json
rename to gateway/src/apicast/policy/caching/apicast-policy.json
diff --git a/gateway/src/apicast/policy/cors/schema.json b/gateway/src/apicast/policy/cors/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/cors/schema.json
rename to gateway/src/apicast/policy/cors/apicast-policy.json
diff --git a/gateway/src/apicast/policy/echo/schema.json b/gateway/src/apicast/policy/echo/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/echo/schema.json
rename to gateway/src/apicast/policy/echo/apicast-policy.json
diff --git a/gateway/src/apicast/policy/headers/schema.json b/gateway/src/apicast/policy/headers/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/headers/schema.json
rename to gateway/src/apicast/policy/headers/apicast-policy.json
diff --git a/gateway/src/apicast/policy/upstream/schema.json b/gateway/src/apicast/policy/upstream/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/upstream/schema.json
rename to gateway/src/apicast/policy/upstream/apicast-policy.json
diff --git a/gateway/src/apicast/policy/url_rewriting/schema.json b/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
similarity index 100%
rename from gateway/src/apicast/policy/url_rewriting/schema.json
rename to gateway/src/apicast/policy/url_rewriting/apicast-policy.json

From 3daf081abea22363803f9d73a07d81a06908775b Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 18:18:25 +0100
Subject: [PATCH 09/11] policy: make schemas conform with the new manifest

---
 .../policy/caching/apicast-policy.json        | 19 ++---
 .../apicast/policy/cors/apicast-policy.json   | 71 ++++++++++---------
 .../apicast/policy/echo/apicast-policy.json   | 27 +++----
 .../policy/headers/apicast-policy.json        | 59 +++++++--------
 .../policy/upstream/apicast-policy.json       | 41 ++++++-----
 .../policy/url_rewriting/apicast-policy.json  | 67 ++++++++---------
 6 files changed, 151 insertions(+), 133 deletions(-)

diff --git a/gateway/src/apicast/policy/caching/apicast-policy.json b/gateway/src/apicast/policy/caching/apicast-policy.json
index 5298e7a02..d437b915d 100644
--- a/gateway/src/apicast/policy/caching/apicast-policy.json
+++ b/gateway/src/apicast/policy/caching/apicast-policy.json
@@ -1,6 +1,6 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Caching policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "Caching policy",
   "description":
     ["Configures a cache for the authentication calls against the 3scale ",
      "backend. This policy support three kinds of caching: \n",
@@ -17,12 +17,15 @@
      "Make sure to understand the implications of that before using this ",
      "mode. It makes sense only in very specific use cases.\n",
      "- None: disables caching."],
-  "type": "object",
-  "properties": {
-    "caching_type": {
-      "description": "Caching mode",
-      "type": "string",
-      "enum": ["resilient", "strict", "allow", "none"]
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "caching_type": {
+        "description": "Caching mode",
+        "type": "string",
+        "enum": ["resilient", "strict", "allow", "none"]
+      }
     }
   }
 }
diff --git a/gateway/src/apicast/policy/cors/apicast-policy.json b/gateway/src/apicast/policy/cors/apicast-policy.json
index 987fb32bf..2f4c9ae12 100644
--- a/gateway/src/apicast/policy/cors/apicast-policy.json
+++ b/gateway/src/apicast/policy/cors/apicast-policy.json
@@ -1,41 +1,44 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "CORS policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "CORS policy",
   "description": "This policy enables CORS (Cross Origin Resource Sharing) request handling.",
-  "type": "object",
-  "properties": {
-    "allow_headers": {
-      "description": "Allowed headers",
-      "type": "array",
-      "items": {
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "allow_headers": {
+        "description": "Allowed headers",
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "allow_methods": {
+        "description": "Allowed methods",
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "GET",
+            "HEAD",
+            "POST",
+            "PUT",
+            "DELETE",
+            "PATCH",
+            "OPTIONS",
+            "TRACE",
+            "CONNECT"
+          ]
+        }
+      },
+      "allow_origin": {
+        "description": "Origins for which the response can be shared with",
         "type": "string"
+      },
+      "allow_credentials": {
+        "description": "Whether the request can be made using credentials",
+        "type": "boolean"
       }
-    },
-    "allow_methods": {
-      "description": "Allowed methods",
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [
-          "GET",
-          "HEAD",
-          "POST",
-          "PUT",
-          "DELETE",
-          "PATCH",
-          "OPTIONS",
-          "TRACE",
-          "CONNECT"
-        ]
-      }
-    },
-    "allow_origin": {
-      "description": "Origins for which the response can be shared with",
-      "type": "string"
-    },
-    "allow_credentials": {
-      "description": "Whether the request can be made using credentials",
-      "type": "boolean"
     }
   }
 }
diff --git a/gateway/src/apicast/policy/echo/apicast-policy.json b/gateway/src/apicast/policy/echo/apicast-policy.json
index 05e40c8bc..cd77dd6b0 100644
--- a/gateway/src/apicast/policy/echo/apicast-policy.json
+++ b/gateway/src/apicast/policy/echo/apicast-policy.json
@@ -1,19 +1,22 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Echo policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "Echo policy",
   "description":
     ["This policy prints the request back to the client and optionally sets ",
      "a status code."],
-  "type": "object",
-  "properties": {
-    "status": {
-      "description": "HTTP status code to be returned",
-      "type": "integer"
-    },
-    "exit": {
-      "description": "Exit mode. 'request' interrupts the processing of the request, 'phase' only skips the rewrite phase.",
-      "type": "string",
-      "enum": ["request", "phase"]
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "status": {
+        "description": "HTTP status code to be returned",
+        "type": "integer"
+      },
+      "exit": {
+        "description": "Exit mode. 'request' interrupts the processing of the request, 'phase' only skips the rewrite phase.",
+        "type": "string",
+        "enum": ["request", "phase"]
+      }
     }
   }
 }
diff --git a/gateway/src/apicast/policy/headers/apicast-policy.json b/gateway/src/apicast/policy/headers/apicast-policy.json
index 872600a22..97ed938ef 100644
--- a/gateway/src/apicast/policy/headers/apicast-policy.json
+++ b/gateway/src/apicast/policy/headers/apicast-policy.json
@@ -1,39 +1,42 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Headers policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "Headers policy",
   "description":
     ["This policy allows to include custom headers that will be sent to the ",
      "upstream as well as modify or delete the ones included in the original ",
      "request. Similarly, this policy also allows to add, modify, and delete ",
      "the headers included in the response."],
-  "type": "object",
-  "definitions": {
-    "commands": {
-      "description": "List of operations to apply to the headers",
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "op": {
-            "description": "Operation to be applied",
-            "type": "string",
-            "enum": ["add", "set", "push"]
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "definitions": {
+      "commands": {
+        "description": "List of operations to apply to the headers",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "op": {
+              "description": "Operation to be applied",
+              "type": "string",
+              "enum": ["add", "set", "push"]
+            },
+            "header": {
+              "description": "Header to be modified",
+              "type": "string"
+            },
+            "value": {
+              "description": "Value that will be added, set or pushed in the header",
+              "type": "string"
+            }
           },
-          "header": {
-            "description": "Header to be modified",
-            "type": "string"
-          },
-          "value": {
-            "description": "Value that will be added, set or pushed in the header",
-            "type": "string"
-          }
-        },
-        "required": ["op", "header", "value"]
+          "required": ["op", "header", "value"]
+        }
       }
+    },
+    "properties": {
+      "request": { "$ref": "#/definitions/commands" },
+      "response": { "$ref": "#/definitions/commands" }
     }
-  },
-  "properties": {
-    "request": { "$ref": "#/definitions/commands" },
-    "response": { "$ref": "#/definitions/commands" }
   }
 }
diff --git a/gateway/src/apicast/policy/upstream/apicast-policy.json b/gateway/src/apicast/policy/upstream/apicast-policy.json
index 78b4d1277..7b99d4b11 100644
--- a/gateway/src/apicast/policy/upstream/apicast-policy.json
+++ b/gateway/src/apicast/policy/upstream/apicast-policy.json
@@ -1,25 +1,28 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Upstream policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "Upstream policy",
   "description": "This policy allows to modify the host of a request based on its path.",
-  "type": "object",
-  "properties": {
-    "rules": {
-      "description": "list of rules to be applied",
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "regex": {
-            "description": "regular expression to be matched",
-            "type": "string"
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "rules": {
+        "description": "list of rules to be applied",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "regex": {
+              "description": "regular expression to be matched",
+              "type": "string"
+            },
+            "url": {
+              "description": "new URL in case of match",
+              "type": "string"
+            }
           },
-          "url": {
-            "description": "new URL in case of match",
-            "type": "string"
-          }
-        },
-        "required": ["regex", "url"]
+          "required": ["regex", "url"]
+        }
       }
     }
   }
diff --git a/gateway/src/apicast/policy/url_rewriting/apicast-policy.json b/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
index ce7ed435b..ef54b21c3 100644
--- a/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
+++ b/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
@@ -1,43 +1,46 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "URL rewriting policy configuration",
+  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
+  "name": "URL rewriting policy",
   "description":
     ["This policy allows to modify the path of a request. ",
      "The operations supported are sub and gsub based on ngx.re.sub and ",
      "ngx.re.gsub provided by OpenResty. Please check ",
      "https://github.com/openresty/lua-nginx-module for more details on how ",
      "to define regular expressions and learn the options supported."],
-  "type": "object",
-  "properties": {
-    "commands": {
-      "description": "List of rewriting commands to be applied",
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "op": {
-            "description": "Operation to be applied (sub or gsub)",
-            "type": "string",
-            "enum": ["sub", "gsub"]
+  "version": "0.1",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "commands": {
+        "description": "List of rewriting commands to be applied",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "op": {
+              "description": "Operation to be applied (sub or gsub)",
+              "type": "string",
+              "enum": ["sub", "gsub"]
+            },
+            "regex": {
+              "description": "Regular expression to be matched",
+              "type": "string"
+            },
+            "replace": {
+              "description": "String that will replace what is matched by the regex",
+              "type": "string"
+            },
+            "options": {
+              "description": "Options that define how the regex matching is performed",
+              "type": "string"
+            },
+            "break": {
+              "description": "when set to true, if the command rewrote the URL, it will be the last one applied",
+              "type": "boolean"
+            }
           },
-          "regex": {
-            "description": "Regular expression to be matched",
-            "type": "string"
-          },
-          "replace": {
-            "description": "String that will replace what is matched by the regex",
-            "type": "string"
-          },
-          "options": {
-            "description": "Options that define how the regex matching is performed",
-            "type": "string"
-          },
-          "break": {
-            "description": "when set to true, if the command rewrote the URL, it will be the last one applied",
-            "type": "boolean"
-          }
-        },
-        "required": ["op", "regex", "replace"]
+          "required": ["op", "regex", "replace"]
+        }
       }
     }
   }

From c206f3d89ece28db6197aca0853b5a845fd0e877 Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Thu, 25 Jan 2018 18:42:07 +0100
Subject: [PATCH 10/11] CHANGELOG: add entry for policy json manifest

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd10920d8..4fd2772a5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Caching policy [PR #546](https://github.com/3scale/apicast/pull/546), [PR #558](https://github.com/3scale/apicast/pull/558)
 - New phase: `content` for generating content or getting the upstream response [PR #535](https://github.com/3scale/apicast/pull/535)
 - Upstream policy [PR #562](https://github.com/3scale/apicast/pull/562)
+- Policy JSON manifest [PR #565](https://github.com/3scale/apicast/pull/565)
 
 ## Fixed
 

From c3f48d6fc6fb41d490aa2520a9f784240f077b6b Mon Sep 17 00:00:00 2001
From: David Ortiz <z.david.ortiz@gmail.com>
Date: Fri, 26 Jan 2018 12:12:11 +0100
Subject: [PATCH 11/11] policy: replace enums with oneOfs in the schemas

The reason is that this way, we can add a description for each of the
options.
---
 .../policy/caching/apicast-policy.json        | 19 ++++++++++++++++++-
 .../apicast/policy/echo/apicast-policy.json   | 13 +++++++++++--
 .../policy/headers/apicast-policy.json        | 15 ++++++++++++++-
 .../policy/url_rewriting/apicast-policy.json  | 11 ++++++++++-
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/gateway/src/apicast/policy/caching/apicast-policy.json b/gateway/src/apicast/policy/caching/apicast-policy.json
index d437b915d..04d904937 100644
--- a/gateway/src/apicast/policy/caching/apicast-policy.json
+++ b/gateway/src/apicast/policy/caching/apicast-policy.json
@@ -24,7 +24,24 @@
       "caching_type": {
         "description": "Caching mode",
         "type": "string",
-        "enum": ["resilient", "strict", "allow", "none"]
+        "oneOf": [
+          {
+            "const": "resilient",
+            "description": "Authorize according to last request when backend is down."
+          },
+          {
+            "const": "strict",
+            "description": "It only caches authorized calls."
+          },
+          {
+            "const": "allow",
+            "description": "When backend is down, allow everything unless seen before and denied."
+          },
+          {
+            "const": "none",
+            "description": "Disables caching."
+          }
+        ]
       }
     }
   }
diff --git a/gateway/src/apicast/policy/echo/apicast-policy.json b/gateway/src/apicast/policy/echo/apicast-policy.json
index cd77dd6b0..25937f8dd 100644
--- a/gateway/src/apicast/policy/echo/apicast-policy.json
+++ b/gateway/src/apicast/policy/echo/apicast-policy.json
@@ -13,9 +13,18 @@
         "type": "integer"
       },
       "exit": {
-        "description": "Exit mode. 'request' interrupts the processing of the request, 'phase' only skips the rewrite phase.",
+        "description": "Exit mode",
         "type": "string",
-        "enum": ["request", "phase"]
+        "oneOf": [
+          {
+            "const": "request",
+            "description": "Interrupts the processing of the request."
+          },
+          {
+            "const": "set",
+            "description": "Only skips the rewrite phase."
+          }
+        ]
       }
     }
   }
diff --git a/gateway/src/apicast/policy/headers/apicast-policy.json b/gateway/src/apicast/policy/headers/apicast-policy.json
index 97ed938ef..a718009ac 100644
--- a/gateway/src/apicast/policy/headers/apicast-policy.json
+++ b/gateway/src/apicast/policy/headers/apicast-policy.json
@@ -19,7 +19,20 @@
             "op": {
               "description": "Operation to be applied",
               "type": "string",
-              "enum": ["add", "set", "push"]
+              "oneOf": [
+                {
+                  "const": "add",
+                  "description": "Adds a value to an existing header."
+                },
+                {
+                  "const": "set",
+                  "description": "Creates the header when not set, replaces its value when set."
+                },
+                {
+                  "const": "push",
+                  "description": "Creates the header when not set, adds the value when set."
+                }
+              ]
             },
             "header": {
               "description": "Header to be modified",
diff --git a/gateway/src/apicast/policy/url_rewriting/apicast-policy.json b/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
index ef54b21c3..1beb0cce0 100644
--- a/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
+++ b/gateway/src/apicast/policy/url_rewriting/apicast-policy.json
@@ -20,7 +20,16 @@
             "op": {
               "description": "Operation to be applied (sub or gsub)",
               "type": "string",
-              "enum": ["sub", "gsub"]
+              "oneOf": [
+                {
+                  "const": "sub",
+                  "description": "Substitutes the first match of the regex applied."
+                },
+                {
+                  "const": "gsub",
+                  "description": "Substitutes all the matches of the regex applied."
+                }
+              ]
             },
             "regex": {
               "description": "Regular expression to be matched",