diff --git a/rest-api-spec/src/main/resources/schema.json b/rest-api-spec/src/main/resources/schema.json
index 16418116b51de..6ae10164ee7b8 100644
--- a/rest-api-spec/src/main/resources/schema.json
+++ b/rest-api-spec/src/main/resources/schema.json
@@ -43,6 +43,37 @@
                     "$ref": "#/definitions/Body"
                 }
             },
+            "if": {
+              "properties": {
+                "stability": {
+                  "const": "stable"
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "documentation": {
+                  "$ref": "#/definitions/Documentation",
+                  "properties": {
+                    "url" : {
+                      "type": ["string"]
+                    }
+                  }
+                }
+              }
+            },
+            "else": {
+              "properties": {
+                "documentation": {
+                  "$ref": "#/definitions/Documentation",
+                  "properties": {
+                    "url" : {
+                      "type": ["string", "null"]
+                    }
+                  }
+                }
+              }
+            },
             "required": [
                 "documentation",
                 "stability",
@@ -130,7 +161,6 @@
             "additionalProperties": false,
             "properties": {
                 "url": {
-                    "type": "string",
                     "format": "uri"
                 },
                 "description": {
diff --git a/x-pack/plugin/build.gradle b/x-pack/plugin/build.gradle
index a5a5bf73c5930..d9938d485ed15 100644
--- a/x-pack/plugin/build.gradle
+++ b/x-pack/plugin/build.gradle
@@ -159,7 +159,4 @@ testClusters.integTest {
   }
 }
 
-validateRestSpec {
-  ignore 'ml.validate.json'
-  ignore 'ml.validate_detector.json'
-}
+
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
index ffbede6b1e387..46f6e8337efdc 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
@@ -1,7 +1,7 @@
 {
   "ml.validate":{
     "documentation":{
-      "url":null,
+      "url":"https://www.elastic.co/guide/en/machine-learning/current/ml-jobs.html",
       "description":"Validates an anomaly detection job."
     },
     "stability":"stable",
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
index f4cee6d5c270d..336b81aaaaf87 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
@@ -1,7 +1,7 @@
 {
   "ml.validate_detector":{
     "documentation":{
-      "url":null,
+      "url":"https://www.elastic.co/guide/en/machine-learning/current/ml-jobs.html",
       "description":"Validates an anomaly detection detector."
     },
     "stability":"stable",