@minecraft/creator-tools/lib/dataform/DataFormValidator.d.ts

Minecraft Creator Tools command line and libraries.

import IField, { FieldDataType } from "./IField";
import IFormDefinition from "./IFormDefinition";
/**
 * Cache for subForm lookups during a single validation call chain.
 * This prevents repeated async lookups for the same subFormId during recursive validation.
 * Exported so it can be shared across items with the same formPath for performance.
 */
export interface IValidationContext {
    depth: number;
    subFormCache: Map<string, IFormDefinition | null>;
}
export declare enum DataFormIssueType {
    unexpectedStringUsedWhenObjectExpected = 101,
    unexpectedBooleanUsedWhenObjectExpected = 102,
    unexpectedNumberUsedWhenObjectExpected = 103,
    dataTypeMismatch = 110,
    valueBelowMinimum = 111,
    valueAboveMaximum = 112,
    stringTooShort = 113,
    stringTooLong = 114,
    valueNotInChoices = 115,
    patternMismatch = 116,
    arrayLengthMismatch = 117,
    pointSizeMismatch = 118,
    keyNotAllowed = 119,
    unexpectedProperty = 120,
    missingRequiredField = 121
}
export interface IDataFormValidationIssue {
    message: string;
    type: DataFormIssueType;
}
export default class DataFormValidator {
    static validate(data: object | string | number | boolean, form: IFormDefinition, issues?: IDataFormValidationIssue[], path?: string, context?: IValidationContext): Promise<IDataFormValidationIssue[]>;
    /**
     * Validates that an object doesn't have properties not defined in the form.
     * This check only runs when form.strictAdditionalProperties is true, as most Minecraft
     * content formats allow additional properties not explicitly defined in the schema.
     */
    static validateUnexpectedProperties(data: object, form: IFormDefinition, issues: IDataFormValidationIssue[], path: string): Promise<void>;
    static validateField(data: object | string | number | boolean | undefined | null, field: IField, issues: IDataFormValidationIssue[], path: string, context: IValidationContext): Promise<void>;
    static getDataMismatchError(data: object | string | number | boolean | string[] | number[], type: FieldDataType): string;
    /**
     * Validates that a numeric value is within the allowed range.
     */
    static validateNumericRange(data: number, field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Validates that a string value is within the allowed length.
     */
    static validateStringLength(data: string, field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Validates that a value matches one of the allowed choices.
     */
    static validateChoices(data: unknown, field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Validates that a value matches patterns defined in field.validity conditions.
     */
    static validatePatterns(data: unknown, field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Validates that an array has the correct length if fixedLength is specified.
     */
    static validateArrayLength(data: unknown[], field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Validates that point arrays (point2, point3, etc.) have the correct number of elements.
     */
    static validatePointSize(data: unknown, field: IField, issues: IDataFormValidationIssue[], path: string): void;
    /**
     * Gets a subForm for a field, using the validation context cache to avoid repeated lookups.
     * This significantly improves performance when validating deeply nested structures.
     */
    static getCachedSubForm(field: IField, context: IValidationContext): Promise<IFormDefinition | null>;
    /**
     * Validates that keys in a keyed collection are allowed if allowedKeys is specified.
     */
    static validateKeyedCollection(data: object, field: IField, issues: IDataFormValidationIssue[], path: string, context: IValidationContext): Promise<void>;
    /**
     * Checks if a field ID contains regex metacharacters, indicating it's a pattern
     * that should be matched against data keys rather than used as a literal property name.
     * Common patterns in Minecraft forms: "geometry.[a-zA-Z0-9_.'-:]+" for legacy geometry.
     */
    static isPatternFieldId(fieldId: string): boolean;
    /**
     * Validates a pattern-based field ID against the data object.
     * For pattern fields, iterates through all data keys and validates those matching the pattern.
     * If the field is required, at least one matching key must exist.
     * @param cleanedFieldId - The field ID after cleaning (removing embedded enum syntax)
     */
    static validatePatternField(data: object, field: IField, issues: IDataFormValidationIssue[], path: string, context: IValidationContext, cleanedFieldId?: string): Promise<void>;
    static getValidationIssue(type: DataFormIssueType): IDataFormValidationIssue;
}