[Enhancement] Add schema validation and placeholders to index mappings

[pyek-bot]

Description

Added schema validation and placeholders to index mappings

Related Issues

Resolves #2951

Check List

• New functionality includes testing.
• Commits are signed per the DCO using --signoff.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[ylwu-amzn]

Is it thread-safe to define it as singleton ?

[pyek-bot]

yes, the instance is not being modified anywhere, only methods are used. It is used similarly in RestActionUtils

[dhrubo-os]

Do we need to have this check here considering we are going to check mapping.isBlank() in the replacePlaceholders method. Seems like redundant.

[pyek-bot]

i added this check here since this method can be used on its own, incase used in other places, i believe it is safer to have this additional check

[dhrubo-os]

Here we are creating string in every replace. May be we could use a StringBuilder to have in-place replacement?

May be something like this:

public static String replacePlaceholders(String mapping) throws IOException {
    if (mapping == null || mapping.isBlank()) {
        throw new IllegalArgumentException("Mapping cannot be null or empty");
    }

    // Preload resources into memory to avoid redundant I/O
    Map<String, String> loadedPlaceholders = new HashMap<>();
    for (Map.Entry<String, String> placeholder : MAPPING_PLACEHOLDERS.entrySet()) {
        URL url = IndexUtils.class.getClassLoader().getResource(placeholder.getValue());
        if (url == null) {
            throw new IOException("Resource not found: " + placeholder.getValue());
        }
        // Load and cache the content
        loadedPlaceholders.put(placeholder.getKey(), Resources.toString(url, Charsets.UTF_8));
    }

    // Use StringBuilder for efficient in-place replacements
    StringBuilder result = new StringBuilder(mapping);
    for (Map.Entry<String, String> entry : loadedPlaceholders.entrySet()) {
        String placeholder = entry.getKey();
        String replacement = entry.getValue();

        // Replace all occurrences of the placeholder
        int index;
        while ((index = result.indexOf(placeholder)) != -1) {
            result.replace(index, index + placeholder.length(), replacement);
        }
    }

    return result.toString();
}

[pyek-bot]

agreed, thanks for the suggestion, saves on the I/O and is more efficient!

[dhrubo-os]

Should we add try catch block to catch any exceptions like:

catch (JsonProcessingException e) {
        throw new IllegalArgumentException("Invalid JSON format: " + e.getMessage(), e);
    } catch (Exception e) {
        throw new OpenSearchParseException("Schema validation failed: " + e.getMessage(), e);
    }

[dhrubo-os]

What do you think about this:

if (!errors.isEmpty()) {
            String errorMessage = errors.stream()
                                        .map(ValidationMessage::getMessage)
                                        .collect(Collectors.joining(", "));
            throw new OpenSearchParseException(
                "Validation failed: " + errorMessage + 
                " for instance: " + instanceString + 
                " with schema: " + schemaString
            );
        }

[dhrubo-os]

Usually, I see that JSON files in the repository are named using snake_case. Let's follow the same convention.

[pyek-bot]

@dhrubo-os addressed review comments, please review!

[dhrubo-os]

[Nit] if you want to be fancy :D

/**
     * Checks if the provided mapping is a valid JSON and validates it against a schema.
     *
     * <p>The schema is located at <code>mappings/schema.json</code> and enforces the following validations:</p>
     *
     * <ul>
     *   <li>Mandatory fields:
     *     <ul>
     *       <li><code>_meta</code></li>
     *       <li><code>_meta.schema_version</code></li>
     *       <li><code>properties</code></li>
     *     </ul>
     *   </li>
     *   <li>No additional fields are allowed at the root level.</li>
     *   <li>No additional fields are allowed in the <code>_meta</code> object.</li>
     *   <li><code>properties</code> must be an object type.</li>
     *   <li><code>_meta</code> must be an object type.</li>
     *   <li><code>_meta.schema_version</code> must be an integer.</li>
     * </ul>
     *
     * <p><strong>Note:</strong> Validation can be made stricter if a specific schema is defined for each index.</p>
     */

[dhrubo-os]

It will look like this.

[pyek-bot]

that looks neat, ive added it