Java Parser Check

Actionable YAML diagnostics for Java applications and plugins.

java-parser-check parses YAML files, validates their structure, and returns clear diagnostics with source locations, error codes, explanations, and repair suggestions. It is designed for configuration-heavy projects where a single YAML mistake can prevent an application or Minecraft plugin from starting.

Features

• Parse YAML from files, readers, or strings
• Report syntax errors with line and column information
• Detect duplicate keys instead of silently accepting the last value
• Reject unsupported multi-document YAML files
• Validate required keys and YAML value types with a small, fluent schema API
• Report warnings for empty documents and unknown schema keys
• Return parsed values as standard Java collections and scalar values
• Use SnakeYAML's safe constructor
• Apply alias and input-size limits to reduce resource-exhaustion risks
• Format diagnostics for logs, build tools, and editor integrations

Requirements

• Java 8 or newer at runtime
• Gradle 9.7.1 or newer for building (Gradle 9.7.1 itself runs on JDK 17+)

Installation

JitPack builds the published GitHub tags and is the easiest way to use the library right now. Add the JitPack repository and the dependency to your project.

Gradle Kotlin DSL

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.BitAspire:java-parser-check:0.1.1")
}

Gradle Groovy DSL

repositories {
    maven { url = 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.BitAspire:java-parser-check:0.1.1'
}

Replace 0.1.1 with the release tag you want to use. JitPack uses the GitHub owner in the group ID, so the dependency starts with com.github.BitAspire.

Quick start

Use JPC for the simple case:

import com.bitaspire.javaparsercheck.JPC;
import com.bitaspire.javaparsercheck.diagnostics.DiagnosticReport;

import java.nio.file.Paths;
import java.util.Map;

DiagnosticReport report = JPC.diagnose(Paths.get("plugin.yml"));

if (report.hasErrors()) {
    System.err.println(report.format());
    return;
}

Map<?, ?> configuration = (Map<?, ?>) report.value().orElseThrow(
        () -> new IllegalStateException("Expected a parsed YAML value")
);

DiagnosticReport.isValid() returns false when at least one error is present. Warnings do not invalidate the document.

For applications that prefer fail-fast startup:

JPC.diagnose(Paths.get("plugin.yml")).throwIfInvalid();

Validate a configuration schema

Parsing confirms that a file is valid YAML. A schema confirms that it contains the configuration your application expects.

import com.bitaspire.javaparsercheck.JPC;
import com.bitaspire.javaparsercheck.diagnostics.DiagnosticReport;
import com.bitaspire.javaparsercheck.yaml.YamlOptions;
import com.bitaspire.javaparsercheck.yaml.YamlSchema;
import com.bitaspire.javaparsercheck.yaml.YamlType;

import java.nio.file.Paths;

YamlSchema pluginSchema = YamlSchema.builder()
        .required("name", YamlType.STRING)
        .required("main", YamlType.STRING)
        .required("version", YamlType.STRING)
        .optional("api-version", YamlType.STRING)
        .optional("depend", YamlType.LIST)
        .allowUnknownKeys(false)
        .build();

DiagnosticReport report = JPC.diagnose(
        Paths.get("plugin.yml"),
        YamlOptions.builder()
                .schema(pluginSchema)
                .build()
);

if (!report.isValid()) {
    report.diagnostics().forEach(diagnostic ->
            System.err.println(diagnostic.format())
    );
}

Schemas support:

• required and optional keys
• nested maps
• strict or permissive unknown-key handling
• STRING
• BOOLEAN
• INTEGER
• NUMBER
• LIST
• MAP
• NULL
• ANY

Input sources

JPC.diagnose(Paths.get("config.yml"));
JPC.diagnose(file, options);
JPC.diagnose(reader, "config.yml");
JPC.diagnoseContent(yaml, "config.yml");

The source name supplied for readers and strings is included in formatted diagnostics.

Diagnostics

Every diagnostic contains:

• severity: ERROR, WARNING, or INFO
• stable diagnostic code
• human-readable message
• optional explanation
• optional repair suggestion
• source range with one-based line and column numbers

Example:

plugin.yml:4:3 [ERROR JPC-YAML-002] Duplicate key 'commands'. YAML mappings should contain each key only once; different loaders may keep different values. Suggestion: Remove the duplicate key or merge its values into the first occurrence.

Diagnostic codes

Code	Description
JPC-YAML-001	Invalid YAML syntax or a parser/loader limit was reached
JPC-YAML-002	Duplicate mapping key
JPC-YAML-004	More than one YAML document in one file
JPC-YAML-005	Empty YAML document
JPC-SCHEMA-001	Schema expected a map
JPC-SCHEMA-002	Required key is missing
JPC-SCHEMA-003	Value has the wrong YAML type
JPC-SCHEMA-004	Key is not declared in a strict schema
JPC-IO-001	YAML file could not be read
JPC-IO-002	YAML reader could not be read

Security and parsing behavior

• YAML is loaded with SnakeYAML's SafeConstructor; application classes are not instantiated automatically.
• Duplicate keys are reported explicitly. The parsed value is still available so callers can inspect the document, but the report is invalid.
• The default limits are 50 aliases and 3,000,000 code points. Configure them with YamlOptions when needed.
• Empty documents produce a warning by default.
• Unknown keys produce warnings when allowUnknownKeys(false) is enabled.

Releases and JitPack

Publishing a GitHub Release triggers the release workflow. The workflow:

1. checks out the released tag
2. runs the Java 8-compatible build and tests
3. attaches the main, sources, and Javadocs JARs to the GitHub Release
4. creates SHA-256 checksums
5. requests a JitPack build for the same tag

JitPack also builds tags on demand when a dependency is requested for the first time. Build status is available at:

https://jitpack.io/#BitAspire/java-parser-check/0.1.1

This project is published from the BitAspire/java-parser-check GitHub repository.

Use a released version from JitPack

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.BitAspire:java-parser-check:0.1.1")
}

JitPack uses the GitHub owner as the group, so the dependency is com.github.BitAspire rather than the library's regular Maven group com.bitaspire.

Build from source

gradle test

The library targets Java 8 and uses Gradle 9.7.1 for builds. Gradle 9.7.1 itself runs on JDK 17+. To generate the standard Gradle wrapper for local development:

gradle wrapper --gradle-version 9.7.1
./gradlew test

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, testing guidance, feature proposals, and pull request guidelines.

License

This project is licensed under the Apache License 2.0.