Validate REST specs against schema (#55117)

A JSON schema was recently introduced for the REST API specification. #54252
This PR introduces a 3rd party validation tool to ensure that the
REST specification conforms to the schema.

The task is applied to the 3 projects that contain REST API specifications.
The plugin wires this task into the precommit commit task, and should be
considered as part of the public API for the build tools for any plugin
developer to contribute their plugin's specification.

An ignore parameter has been introduced for the task to allow specific
file to be ignored from the validation. The ignored files in this PR
will soon get issues logged and a link so they can be fixed.

Closes #54314

buildSrc/build.gradle

@@ -121,6 +121,7 @@ dependencies {
   compile 'de.thetaphi:forbiddenapis:2.7'
   compile 'com.avast.gradle:gradle-docker-compose-plugin:0.8.12'
   compile 'org.apache.maven:maven-model:3.6.2'
+  compile 'com.networknt:json-schema-validator:1.0.36'
   compileOnly "com.puppycrawl.tools:checkstyle:${props.getProperty('checkstyle')}"
   testCompile "com.puppycrawl.tools:checkstyle:${props.getProperty('checkstyle')}"
   testCompile "junit:junit:${props.getProperty('junit')}"

buildSrc/src/main/java/org/elasticsearch/gradle/precommit/ValidateJsonAgainstSchemaTask.java

@@ -0,0 +1,152 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.gradle.precommit;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.networknt.schema.JsonSchema;
+import com.networknt.schema.JsonSchemaException;
+import com.networknt.schema.JsonSchemaFactory;
+import com.networknt.schema.SchemaValidatorsConfig;
+import com.networknt.schema.SpecVersion;
+import com.networknt.schema.ValidationMessage;
+import org.gradle.api.DefaultTask;
+import org.gradle.api.UncheckedIOException;
+import org.gradle.api.file.FileCollection;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.InputFile;
+import org.gradle.api.tasks.InputFiles;
+import org.gradle.api.tasks.Optional;
+import org.gradle.api.tasks.OutputFile;
+import org.gradle.api.tasks.TaskAction;
+import org.gradle.work.ChangeType;
+import org.gradle.work.Incremental;
+import org.gradle.work.InputChanges;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.nio.file.Files;
+import java.nio.file.StandardOpenOption;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.StreamSupport;
+
+/**
+ * Incremental task to validate a set of JSON files against against a schema.
+ */
+public class ValidateJsonAgainstSchemaTask extends DefaultTask {
+
+    private final ObjectMapper mapper = new ObjectMapper();
+    private Set<String> ignore = new HashSet<>();
+    private File jsonSchema;
+    private FileCollection inputFiles;
+
+    @Incremental
+    @InputFiles
+    public FileCollection getInputFiles() {
+        return inputFiles;
+    }
+
+    public void setInputFiles(FileCollection inputFiles) {
+        this.inputFiles = inputFiles;
+    }
+
+    @InputFile
+    public File getJsonSchema() {
+        return jsonSchema;
+    }
+
+    public void setJsonSchema(File jsonSchema) {
+        this.jsonSchema = jsonSchema;
+    }
+
+    @Input
+    @Optional
+    public Set<String> getIgnore() {
+        return ignore;
+    }
+
+    public void ignore(String... ignore) {
+        this.ignore.addAll(Arrays.asList(ignore));
+    }
+
+    @OutputFile
+    public File getReport() {
+        return new File(getProject().getBuildDir(), "reports/validateJson.txt");
+    }
+
+    @TaskAction
+    public void validate(InputChanges inputChanges) throws IOException {
+        File jsonSchemaOnDisk = getJsonSchema();
+        getLogger().debug("JSON schema : [{}]", jsonSchemaOnDisk.getAbsolutePath());
+        SchemaValidatorsConfig config = new SchemaValidatorsConfig();
+        JsonSchemaFactory factory = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V7);
+        JsonSchema jsonSchema = factory.getSchema(mapper.readTree(jsonSchemaOnDisk), config);
+        Map<File, Set<String>> errors = new LinkedHashMap<>();
+        // incrementally evaluate input files
+        StreamSupport.stream(inputChanges.getFileChanges(getInputFiles()).spliterator(), false)
+            .filter(f -> f.getChangeType() != ChangeType.REMOVED)
+            .forEach(fileChange -> {
+                File file = fileChange.getFile();
+                if (ignore.contains(file.getName())) {
+                    getLogger().debug("Ignoring file [{}] due to configuration", file.getName());
+                } else if (file.isDirectory() == false) {
+                    // validate all files and hold on to errors for a complete report if there are failures
+                    getLogger().debug("Validating JSON [{}]", file.getName());
+                    try {
+                        Set<ValidationMessage> validationMessages = jsonSchema.validate(mapper.readTree(file));
+                        maybeLogAndCollectError(validationMessages, errors, file);
+                    } catch (IOException e) {
+                        throw new UncheckedIOException(e);
+                    }
+                }
+            });
+        if (errors.isEmpty()) {
+            Files.writeString(getReport().toPath(), "Success! No validation errors found.", StandardOpenOption.CREATE);
+        } else {
+            try (PrintWriter printWriter = new PrintWriter(getReport())) {
+                printWriter.printf("Schema: %s%n", jsonSchemaOnDisk);
+                printWriter.println("----------Validation Errors-----------");
+                errors.values().stream().flatMap(Collection::stream).forEach(printWriter::println);
+            }
+            StringBuilder sb = new StringBuilder();
+            sb.append("Error validating JSON. See the report at: ");
+            sb.append(getReport().toURI().toASCIIString());
+            sb.append(System.lineSeparator());
+            sb.append(
+                String.format("JSON validation failed: %d files contained %d violations", errors.keySet().size(), errors.values().size())
+            );
+            throw new JsonSchemaException(sb.toString());
+        }
+    }
+
+    private void maybeLogAndCollectError(Set<ValidationMessage> messages, Map<File, Set<String>> errors, File file) {
+        for (ValidationMessage message : messages) {
+            getLogger().error("[validate JSON][ERROR][{}][{}]", file.getName(), message.toString());
+            errors.computeIfAbsent(file, k -> new LinkedHashSet<>())
+                .add(String.format("%s: %s", file.getAbsolutePath(), message.toString()));
+        }
+    }
+}

buildSrc/src/main/java/org/elasticsearch/gradle/precommit/ValidateRestSpecPlugin.java

@@ -0,0 +1,44 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.gradle.precommit;
+
+import org.elasticsearch.gradle.util.Util;
+import org.gradle.api.Plugin;
+import org.gradle.api.Project;
+import org.gradle.api.provider.Provider;
+
+import java.io.File;
+
+public class ValidateRestSpecPlugin implements Plugin<Project> {
+    private static final String DOUBLE_STAR = "**"; // checkstyle thinks these are javadocs :(
+
+    @Override
+    public void apply(Project project) {
+        Provider<ValidateJsonAgainstSchemaTask> validateRestSpecTask = project.getTasks()
+            .register("validateRestSpec", ValidateJsonAgainstSchemaTask.class, task -> {
+                task.setInputFiles(Util.getJavaTestAndMainSourceResources(project, filter -> {
+                    filter.include(DOUBLE_STAR + "/rest-api-spec/api/" + DOUBLE_STAR + "/*.json");
+                    filter.exclude(DOUBLE_STAR + "/_common.json");
+                }));
+                task.setJsonSchema(new File(project.getRootDir(), "rest-api-spec/src/main/resources/schema.json"));
+            });
+        project.getTasks().named("precommit").configure(t -> t.dependsOn(validateRestSpecTask));
+    }
+}

buildSrc/src/main/java/org/elasticsearch/gradle/util/Util.java

@@ -20,8 +20,15 @@
 package org.elasticsearch.gradle.util;
 
 import org.elasticsearch.gradle.info.GlobalBuildInfoPlugin;
+import org.gradle.api.Action;
 import org.gradle.api.GradleException;
+import org.gradle.api.Project;
+import org.gradle.api.file.FileTree;
+import org.gradle.api.plugins.JavaPluginConvention;
+import org.gradle.api.tasks.SourceSet;
+import org.gradle.api.tasks.util.PatternFilterable;
 
+import javax.annotation.Nullable;
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStreamReader;
@@ -29,6 +36,7 @@ import java.io.UncheckedIOException;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.Locale;
+import java.util.Optional;
 
 public class Util {
 
@@ -75,4 +83,65 @@ public class Util {
             throw new GradleException("Error determining build tools JAR location", e);
         }
     }
+
+    /**
+     * @param project The project to look for resources.
+     * @param filter  Optional filter function to filter the returned resources
+     * @return Returns the {@link FileTree} for main resources from Java projects. Returns null if no files exist.
+     */
+    @Nullable
+    public static FileTree getJavaMainSourceResources(Project project, Action<? super PatternFilterable> filter) {
+        final Optional<FileTree> mainFileTree = getJavaMainSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
+        return mainFileTree.map(files -> files.matching(filter)).orElse(null);
+    }
+
+    /**
+     * @param project The project to look for resources.
+     * @param filter  Optional filter function to filter the returned resources
+     * @return Returns the {@link FileTree} for test resources from Java projects. Returns null if no files exist.
+     */
+    @Nullable
+    public static FileTree getJavaTestSourceResources(Project project, Action<? super PatternFilterable> filter) {
+        final Optional<FileTree> testFileTree = getJavaTestSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
+        return testFileTree.map(files -> files.matching(filter)).orElse(null);
+    }
+
+    /**
+     * @param project The project to look for resources.
+     * @param filter  Optional filter function to filter the returned resources
+     * @return Returns the combined {@link FileTree} for test and main resources from Java projects. Returns null if no files exist.
+     */
+    @Nullable
+    public static FileTree getJavaTestAndMainSourceResources(Project project, Action<? super PatternFilterable> filter) {
+        final Optional<FileTree> testFileTree = getJavaTestSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
+        final Optional<FileTree> mainFileTree = getJavaMainSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
+        if (testFileTree.isPresent() && mainFileTree.isPresent()) {
+            return testFileTree.get().plus(mainFileTree.get()).matching(filter);
+        } else if (mainFileTree.isPresent()) {
+            return mainFileTree.get().matching(filter);
+        } else if (testFileTree.isPresent()) {
+            return testFileTree.get().matching(filter);
+        }
+        return null;
+    }
+
+    /**
+     * @param project The project to look for test Java resources.
+     * @return An Optional that contains the Java test SourceSet if it exists.
+     */
+    public static Optional<SourceSet> getJavaTestSourceSet(Project project) {
+        return project.getConvention().findPlugin(JavaPluginConvention.class) == null
+            ? Optional.empty()
+            : Optional.ofNullable(GradleUtils.getJavaSourceSets(project).findByName(SourceSet.TEST_SOURCE_SET_NAME));
+    }
+
+    /**
+     * @param project The project to look for main Java resources.
+     * @return An Optional that contains the Java main SourceSet if it exists.
+     */
+    public static Optional<SourceSet> getJavaMainSourceSet(Project project) {
+        return project.getConvention().findPlugin(JavaPluginConvention.class) == null
+            ? Optional.empty()
+            : Optional.ofNullable(GradleUtils.getJavaSourceSets(project).findByName(SourceSet.MAIN_SOURCE_SET_NAME));
+    }
 }

buildSrc/src/main/resources/META-INF/gradle-plugins/elasticsearch.validate-rest-spec.properties

@@ -0,0 +1 @@
+implementation-class=org.elasticsearch.gradle.precommit.ValidateRestSpecPlugin

modules/lang-painless/build.gradle

@@ -16,7 +16,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 import org.elasticsearch.gradle.testclusters.DefaultTestClustersTask;
+apply plugin: 'elasticsearch.validate-rest-spec'
 
 esplugin {
   description 'An easy, safe and fast scripting language for Elasticsearch'
@@ -191,3 +193,7 @@ task regen {
     }
   }
 }
+
+validateRestSpec {
+  ignore 'scripts_painless_context.json'
+}

rest-api-spec/build.gradle

@@ -1,6 +1,7 @@
 apply plugin: 'elasticsearch.build'
 apply plugin: 'nebula.maven-base-publish'
 apply plugin: 'elasticsearch.rest-resources'
+apply plugin: 'elasticsearch.validate-rest-spec'
 
 test.enabled = false
 jarHell.enabled = false
@@ -9,3 +10,7 @@ artifacts {
   restSpecs(new File(projectDir, "src/main/resources/rest-api-spec/api"))
   restTests(new File(projectDir, "src/main/resources/rest-api-spec/test"))
 }
+
+validateRestSpec {
+   ignore "cat.thread_pool.json"
+}

rest-api-spec/src/main/resources/schema.json

@@ -142,7 +142,7 @@
                 "description"
             ],
             "title": "Documentation",
-            "description": "API documentation including a link to the public reference and a short descritpion"
+            "description": "API documentation including a link to the public reference and a short description"
         },
         "Parts": {
             "type": "object",

x-pack/plugin/build.gradle

@@ -3,6 +3,7 @@ import org.elasticsearch.gradle.info.BuildParams
 apply plugin: 'elasticsearch.testclusters'
 apply plugin: 'elasticsearch.standalone-rest-test'
 apply plugin: 'elasticsearch.rest-test'
+apply plugin: 'elasticsearch.validate-rest-spec'
 
 archivesBaseName = 'x-pack'
 
@@ -109,3 +110,15 @@ testClusters.integTest {
   extraConfigFile nodeCert.name, nodeCert
   extraConfigFile 'roles.yml', file('src/test/resources/roles.yml')
 }
+
+validateRestSpec {
+  ignore 'searchable_snapshots.mount.json'
+  ignore 'searchable_snapshots.clear_cache.json'
+  ignore 'searchable_snapshots.stats.json'
+  ignore 'searchable_snapshots.repository_stats.json'
+  ignore 'autoscaling.delete_autoscaling_policy.json'
+  ignore 'autoscaling.get_autoscaling_policy.json'
+  ignore 'autoscaling.put_autoscaling_policy.json'
+  ignore 'ml.validate.json'
+  ignore 'ml.validate_detector.json'
+}