/*
    * SPDX-FileCopyrightText: none
    * SPDX-License-Identifier: CC0-1.0
    */
   
   package dev.metaschema.databind;
   
   import org.eclipse.jdt.annotation.Owning;
   import org.json.JSONObject;
  import org.json.JSONTokener;
  import org.xml.sax.SAXException;
  
  import java.io.BufferedInputStream;
  import java.io.FileNotFoundException;
  import java.io.IOException;
  import java.io.InputStream;
  import java.math.BigInteger;
  import java.net.URI;
  import java.net.URL;
  import java.nio.file.Path;
  import java.time.ZonedDateTime;
  import java.util.Collection;
  import java.util.LinkedList;
  import java.util.List;
  import java.util.function.Function;
  
  import javax.xml.namespace.QName;
  
  import dev.metaschema.core.configuration.IConfiguration;
  import dev.metaschema.core.datatype.DataTypeService;
  import dev.metaschema.core.datatype.IDataTypeAdapter;
  import dev.metaschema.core.metapath.DynamicContext;
  import dev.metaschema.core.metapath.item.node.IDefinitionNodeItem;
  import dev.metaschema.core.metapath.item.node.IDocumentNodeItem;
  import dev.metaschema.core.metapath.item.node.IRootAssemblyNodeItem;
  import dev.metaschema.core.model.IBoundObject;
  import dev.metaschema.core.model.IConstraintLoader;
  import dev.metaschema.core.model.IModule;
  import dev.metaschema.core.model.IModuleLoader;
  import dev.metaschema.core.model.MetaschemaException;
  import dev.metaschema.core.model.constraint.ConstraintValidationException;
  import dev.metaschema.core.model.constraint.DefaultConstraintValidator;
  import dev.metaschema.core.model.constraint.ExternalConstraintsModulePostProcessor;
  import dev.metaschema.core.model.constraint.FindingCollectingConstraintValidationHandler;
  import dev.metaschema.core.model.constraint.IConstraintSet;
  import dev.metaschema.core.model.constraint.IConstraintValidationHandler;
  import dev.metaschema.core.model.constraint.IConstraintValidator;
  import dev.metaschema.core.model.constraint.NoOpValidationEventListener;
  import dev.metaschema.core.model.constraint.ValidationConfig;
  import dev.metaschema.core.model.constraint.ValidationEventListener;
  import dev.metaschema.core.model.constraint.ValidationFeature;
  import dev.metaschema.core.model.validation.AggregateValidationResult;
  import dev.metaschema.core.model.validation.IValidationResult;
  import dev.metaschema.core.model.validation.JsonSchemaContentValidator;
  import dev.metaschema.core.model.validation.XmlSchemaContentValidator;
  import dev.metaschema.core.util.CollectionUtil;
  import dev.metaschema.core.util.ObjectUtils;
  import dev.metaschema.databind.codegen.DefaultModuleBindingGenerator;
  import dev.metaschema.databind.io.BindingException;
  import dev.metaschema.databind.io.DefaultBoundLoader;
  import dev.metaschema.databind.io.DeserializationFeature;
  import dev.metaschema.databind.io.Format;
  import dev.metaschema.databind.io.IBoundLoader;
  import dev.metaschema.databind.io.IDeserializer;
  import dev.metaschema.databind.io.ISerializer;
  import dev.metaschema.databind.io.yaml.YamlOperations;
  import dev.metaschema.databind.model.IBoundDefinitionModel;
  import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
  import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
  import dev.metaschema.databind.model.IBoundModule;
  import dev.metaschema.databind.model.annotations.MetaschemaAssembly;
  import dev.metaschema.databind.model.annotations.MetaschemaField;
  import dev.metaschema.databind.model.metaschema.BindingConstraintLoader;
  import dev.metaschema.databind.model.metaschema.IBindingMetaschemaModule;
  import dev.metaschema.databind.model.metaschema.IBindingModuleLoader;
  import dev.metaschema.databind.model.metaschema.ModuleLoadingPostProcessor;
  import edu.umd.cs.findbugs.annotations.NonNull;
  import edu.umd.cs.findbugs.annotations.Nullable;
  
  /**
   * Provides information supporting a binding between a set of Module models and
   * corresponding Java classes.
   */
  public interface IBindingContext {
    /**
     * Get a new builder that can produce a new, configured binding context.
     *
     * @return the builder
     * @since 2.0.0
     */
    static BindingContextBuilder builder() {
      return new BindingContextBuilder();
    }
  
    /**
     * Get a new {@link IBindingContext} instance, which can be used to load
     * information that binds a model to a set of Java classes.
     *
     * @return a new binding context
    * @since 2.0.0
    */
   @NonNull
   static IBindingContext newInstance() {
     return new DefaultBindingContext();
   }
 
   /**
    * Get a new {@link IBindingContext} instance, which can be used to load
    * information that binds a model to a set of Java classes.
    *
    * @param strategy
    *          the loader strategy to use when loading Metaschema modules
    * @return a new binding context
    * @since 2.0.0
    */
   @NonNull
   static IBindingContext newInstance(@NonNull IBindingContext.IModuleLoaderStrategy strategy) {
     return new DefaultBindingContext(strategy);
   }
 
   /**
    * Get the Metaschema module loader strategy used by this binding context to
    * load modules.
    *
    * @return the strategy instance
    * @since 2.0.0
    */
   @NonNull
   IModuleLoaderStrategy getModuleLoaderStrategy();
 
   /**
    * Get a loader that supports loading a Metaschema module from a specified
    * resource.
    * <p>
    * Modules loaded with this loader are automatically registered with this
    * binding context.
    * <p>
    * Use of this method requires that the binding context is initialized using a
    * {@link IModuleLoaderStrategy} that supports dynamic bound module loading.
    * This can be accomplished using the {@link SimpleModuleLoaderStrategy}
    * initialized using the {@link DefaultModuleBindingGenerator}. * @return the
    * loader
    *
    * @return the loader
    * @since 2.0.0
    */
   @NonNull
   IBindingModuleLoader newModuleLoader();
 
   /**
    * Loads a Metaschema module from the specified path.
    * <p>
    * This method automatically registers the module with this binding context.
    * <p>
    * Use of this method requires that the binding context is initialized using a
    * {@link IModuleLoaderStrategy} that supports dynamic bound module loading.
    * This can be accomplished using the {@link SimpleModuleLoaderStrategy}
    * initialized using the {@link DefaultModuleBindingGenerator}.
    *
    * @param path
    *          the path to load the module from
    * @return the loaded Metaschema module
    * @throws MetaschemaException
    *           if an error occurred while processing the resource
    * @throws IOException
    *           if an error occurred parsing the resource
    * @throws UnsupportedOperationException
    *           if this binding context is not configured to support dynamic bound
    *           module loading
    * @since 2.0.0
    */
   @NonNull
   default IBindingMetaschemaModule loadMetaschema(@NonNull Path path) throws MetaschemaException, IOException {
     return newModuleLoader().load(path);
   }
 
   /**
    * Loads a Metaschema module from the specified URL.
    * <p>
    * This method automatically registers the module with this binding context.
    * <p>
    * Use of this method requires that the binding context is initialized using a
    * {@link IModuleLoaderStrategy} that supports dynamic bound module loading.
    * This can be accomplished using the {@link SimpleModuleLoaderStrategy}
    * initialized using the {@link DefaultModuleBindingGenerator}.
    *
    * @param url
    *          the URL to load the module from
    * @return the loaded Metaschema module
    * @throws MetaschemaException
    *           if an error occurred while processing the resource
    * @throws IOException
    *           if an error occurred parsing the resource
    * @throws UnsupportedOperationException
    *           if this binding context is not configured to support dynamic bound
    *           module loading
    * @since 2.0.0
    */
   @NonNull
   default IBindingMetaschemaModule loadMetaschema(@NonNull URL url) throws MetaschemaException, IOException {
     return newModuleLoader().load(url);
   }
 
   /**
    * Get a loader that supports loading Metaschema module constraints from a
    * specified resource.
    * <p>
    * Metaschema module constraints loaded this need to be used with a new
    * {@link IBindingContext} instance to be applied to loaded modules. The new
    * binding context must initialized using the
    * {@link PostProcessingModuleLoaderStrategy} that is initialized with a
    * {@link ExternalConstraintsModulePostProcessor} instance.
    *
    * @return the loader
    * @since 2.0.0
    */
   @NonNull
   static IConstraintLoader getConstraintLoader() {
     return new BindingConstraintLoader(DefaultBindingContext.instance());
   }
 
   /**
    * Get a loader that supports loading Metaschema module constraints from a
    * specified resource.
    * <p>
    * Metaschema module constraints loaded this need to be used with a new
    * {@link IBindingContext} instance to be applied to loaded modules. The new
    * binding context must initialized using the
    * {@link PostProcessingModuleLoaderStrategy} that is initialized with a
    * {@link ExternalConstraintsModulePostProcessor} instance.
    *
    * @return the loader
    * @since 2.0.0
    */
   @NonNull
   default IConstraintLoader newConstraintLoader() {
     return new BindingConstraintLoader(this);
   }
 
   /**
    * Load a bound Metaschema module implemented by the provided class.
    * <p>
    * Also registers any associated bound classes.
    * <p>
    * Implementations are expected to return the same IModule instance for multiple
    * calls to this method with the same class argument.
    *
    * @param clazz
    *          the class implementing a bound Metaschema module
    * @return the loaded module
    * @throws MetaschemaException
    *           if an error occurred while registering the module
    */
   @NonNull
   IBoundModule registerModule(@NonNull Class<? extends IBoundModule> clazz) throws MetaschemaException;
 
   /**
    * Registers the provided Metaschema module with this binding context.
    * <p>
    * If the provided instance is not an instance of {@link IBoundModule}, then
    * annotated Java classes for this module will be generated, compiled, and
    * loaded based on the provided Module.
    *
    * @param module
    *          the Module module to generate classes for
    * @return the registered module, which may be a different instance than what
    *         was provided if dynamic compilation was performed
    * @throws MetaschemaException
    *           if an error occurred while registering the module
    * @throws UnsupportedOperationException
    *           if this binding context is not configured to support dynamic bound
    *           module loading and the module instance is not a subclass of
    *           {@link IBoundModule}
    * @since 2.0.0
    */
   @NonNull
   default IBoundModule registerModule(@NonNull IModule module) throws MetaschemaException {
     return getModuleLoaderStrategy().registerModule(module, this);
   }
 
   /**
    * Register a class binding for a given bound class.
    *
    * @param definition
    *          the bound class information to register
    * @return the old bound class information or {@code null} if no binding existed
    *         for the associated class
    */
   @Nullable
   IBoundDefinitionModelComplex registerClassBinding(@NonNull IBoundDefinitionModelComplex definition);
 
   /**
    * Get the {@link IBoundDefinitionModel} instance associated with the provided
    * Java class.
    * <p>
    * Typically the class will have a {@link MetaschemaAssembly} or
    * {@link MetaschemaField} annotation.
    *
    * @param clazz
    *          the class binding to load
    * @return the associated class binding instance or {@code null} if the class is
    *         not bound
    */
   @Nullable
   IBoundDefinitionModelComplex getBoundDefinitionForClass(@NonNull Class<? extends IBoundObject> clazz);
 
   /**
    * Determine the bound class for the provided XML {@link QName}.
    *
    * @param rootQName
    *          the root XML element's QName
    * @return the bound class or {@code null} if not recognized
    */
   @Nullable
   Class<? extends IBoundObject> getBoundClassForRootXmlQName(@NonNull QName rootQName);
 
   /**
    * Determine the bound class for the provided JSON/YAML property/item name using
    * any registered matchers.
    *
    * @param rootName
    *          the JSON/YAML property/item name
    * @return the bound class or {@code null} if not recognized
    */
   @Nullable
   Class<? extends IBoundObject> getBoundClassForRootJsonName(@NonNull String rootName);
 
   /**
    * Get's the {@link IDataTypeAdapter} associated with the specified Java class,
    * which is used to read and write XML, JSON, and YAML data to and from
    * instances of that class. Thus, this adapter supports a direct binding between
    * the Java class and structured data in one of the supported formats. Adapters
    * are used to support bindings for simple data objects (e.g., {@link String},
    * {@link BigInteger}, {@link ZonedDateTime}, etc).
    *
    * @param <TYPE>
    *          the class type of the adapter
    * @param clazz
    *          the Java {@link Class} for the bound type
    * @return the adapter instance or {@code null} if the provided class is not
    *         bound
    */
   @Nullable
   default <TYPE extends IDataTypeAdapter<?>> TYPE getDataTypeAdapterInstance(@NonNull Class<TYPE> clazz) {
     return DataTypeService.instance().getDataTypeByAdapterClass(clazz);
   }
 
   /**
    * Gets a data {@link ISerializer} which can be used to write Java instance data
    * for the provided class in the requested format.
    * <p>
    * The provided class must be a bound Java class with a
    * {@link MetaschemaAssembly} or {@link MetaschemaField} annotation for which a
    * {@link IBoundDefinitionModel} exists.
    *
    * @param <CLASS>
    *          the Java type this serializer can write data from
    * @param format
    *          the format to serialize into
    * @param clazz
    *          the Java data object to serialize
    * @return the serializer instance
    * @throws NullPointerException
    *           if any of the provided arguments, except the configuration, are
    *           {@code null}
    * @throws IllegalArgumentException
    *           if the provided class is not bound to a Module assembly or field
    * @throws UnsupportedOperationException
    *           if the requested format is not supported by the implementation
    * @see #getBoundDefinitionForClass(Class)
    */
   @NonNull
   <CLASS extends IBoundObject> ISerializer<CLASS> newSerializer(
       @NonNull Format format,
       @NonNull Class<CLASS> clazz);
 
   /**
    * Gets a data {@link IDeserializer} which can be used to read Java instance
    * data for the provided class from the requested format.
    * <p>
    * The provided class must be a bound Java class with a
    * {@link MetaschemaAssembly} or {@link MetaschemaField} annotation for which a
    * {@link IBoundDefinitionModel} exists.
    *
    * @param <CLASS>
    *          the Java type this deserializer can read data into
    * @param format
    *          the format to serialize into
    * @param clazz
    *          the Java data type to serialize
    * @return the deserializer instance
    * @throws NullPointerException
    *           if any of the provided arguments, except the configuration, are
    *           {@code null}
    * @throws IllegalArgumentException
    *           if the provided class is not bound to a Module assembly or field
    * @throws UnsupportedOperationException
    *           if the requested format is not supported by the implementation
    * @see #getBoundDefinitionForClass(Class)
    */
   @NonNull
   <CLASS extends IBoundObject> IDeserializer<CLASS> newDeserializer(
       @NonNull Format format,
       @NonNull Class<CLASS> clazz);
 
   /**
    * Get a new {@link IBoundLoader} instance to load bound content instances.
    *
    * @return the instance
    */
   @NonNull
   default IBoundLoader newBoundLoader() {
     return new DefaultBoundLoader(this);
   }
 
   /**
    * Get a new {@link IBoundLoader} instance configured for permissive loading.
    * <p>
    * This loader has
    * {@link DeserializationFeature#DESERIALIZE_VALIDATE_REQUIRED_FIELDS} disabled,
    * making it suitable for use with Metapath functions like {@code fn:doc()}
    * where documents may be incomplete or under construction.
    * <p>
    * Use this method when setting up a {@link DynamicContext} for Metapath
    * evaluation to ensure that referenced documents can be loaded without strict
    * required field validation.
    *
    * @return a permissive loader instance
    */
   @NonNull
   default IBoundLoader newPermissiveBoundLoader() {
     IBoundLoader loader = newBoundLoader();
     loader.disableFeature(DeserializationFeature.DESERIALIZE_VALIDATE_REQUIRED_FIELDS);
     return loader;
   }
 
   /**
    * Create a deep copy of the provided bound object.
    *
    * @param <CLASS>
    *          the bound object type
    * @param other
    *          the object to copy
    * @param parentInstance
    *          the object's parent or {@code null}
    * @return a deep copy of the provided object
    * @throws BindingException
    *           if an error occurred copying content between java instances
    * @throws NullPointerException
    *           if the provided object is {@code null}
    * @throws IllegalArgumentException
    *           if the provided class is not bound to a Module assembly or field
    */
   @NonNull
   <CLASS extends IBoundObject> CLASS deepCopy(@NonNull CLASS other, IBoundObject parentInstance)
       throws BindingException;
 
   /**
    * Get a new single use constraint validator.
    * <p>
    * The caller owns the returned validator and is responsible for closing it to
    * release any resources (such as thread pools) when validation is complete.
    * <p>
    * Example usage:
    *
    * <pre>{@code
    * try (IConstraintValidator validator = context.newValidator(handler, config)) {
    *   validator.validate(item, documentUri);
    *   validator.finalizeValidation();
    * }
    * }</pre>
    * <p>
    * The {@code @SuppressWarnings("resource")} annotation on this method is
    * intentional: ownership transfers to the caller who must close the validator.
    *
    * @param handler
    *          the validation handler to use to process the validation results
    * @param config
    *          the validation configuration
    * @return the validator
    */
   @SuppressWarnings("resource")
   @NonNull
   @Owning
   default IConstraintValidator newValidator(
       @NonNull IConstraintValidationHandler handler,
       @Nullable IConfiguration<ValidationFeature<?>> config) {
     // Use permissive loader for referenced documents
     IBoundLoader loader = newPermissiveBoundLoader();
     // Also disable constraint validation for referenced documents
     loader.disableFeature(DeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTS);
 
     DynamicContext context = new DynamicContext();
     context.setDocumentLoader(loader);
 
     // Determine parallel validation configuration
     int threadCount = config != null
         ? config.get(ValidationFeature.PARALLEL_THREADS)
         : ValidationFeature.PARALLEL_THREADS.getDefault();
     ValidationConfig validationConfig = threadCount > 1
         ? ValidationConfig.withThreads(threadCount)
         : ValidationConfig.SEQUENTIAL;
 
     // Apply event listener if configured
     ValidationEventListener listener = config != null
         ? config.get(ValidationFeature.EVENT_LISTENER)
         : null;
     if (listener != null && listener != NoOpValidationEventListener.INSTANCE) {
       validationConfig = validationConfig.withListener(listener);
     }
 
     DefaultConstraintValidator retval = new DefaultConstraintValidator(handler, validationConfig);
     if (config != null) {
       retval.applyConfiguration(config);
     }
     return retval;
   }
 
   /**
    * Perform constraint validation on the provided bound object represented as an
    * {@link IDocumentNodeItem}.
    *
    * @param nodeItem
    *          the node item to validate
    * @param loader
    *          a module loader used to load and resolve referenced resources
    * @param config
    *          the validation configuration
    * @return the validation result
    * @throws ConstraintValidationException
    *           if a constraint violation prevents validation from completing
    * @throws IllegalArgumentException
    *           if the node item is not valid for validation
    */
   default IValidationResult validate(
       @NonNull IDocumentNodeItem nodeItem,
       @NonNull IBoundLoader loader,
       @Nullable IConfiguration<ValidationFeature<?>> config) throws ConstraintValidationException {
     IRootAssemblyNodeItem root = nodeItem.getRootAssemblyNodeItem();
     return validate(root, loader, config);
   }
 
   /**
    * Perform constraint validation on the provided bound object represented as an
    * {@link IDefinitionNodeItem}.
    *
    * @param nodeItem
    *          the node item to validate
    * @param loader
    *          a module loader used to load and resolve referenced resources
    * @param config
    *          the validation configuration
    * @return the validation result
    * @throws ConstraintValidationException
    *           if a constraint violation prevents validation from completing
    * @throws IllegalArgumentException
    *           if the node item is not valid for validation
    */
   default IValidationResult validate(
       @NonNull IDefinitionNodeItem<?, ?> nodeItem,
       @NonNull IBoundLoader loader,
       @Nullable IConfiguration<ValidationFeature<?>> config) throws ConstraintValidationException {
 
     FindingCollectingConstraintValidationHandler handler = new FindingCollectingConstraintValidationHandler();
 
     try (IConstraintValidator validator = newValidator(handler, config)) {
 
       DynamicContext dynamicContext = new DynamicContext(nodeItem.getStaticContext());
       dynamicContext.setDocumentLoader(loader);
 
       validator.validate(nodeItem, dynamicContext);
       validator.finalizeValidation(dynamicContext);
       return handler;
     }
   }
 
   /**
    * Load and perform schema and constraint validation on the target. The
    * constraint validation will only be performed if the schema validation passes.
    *
    * @param target
    *          the target to validate
    * @param asFormat
    *          the schema format to use to validate the target
    * @param schemaProvider
    *          provides callbacks to get the appropriate schemas
    * @param config
    *          the validation configuration
    * @return the validation result
    * @throws IOException
    *           if an error occurred while reading the target
    * @throws ConstraintValidationException
    *           if a constraint violation prevents validation from completing
    */
   default IValidationResult validate(
       @NonNull URI target,
       @NonNull Format asFormat,
       @NonNull ISchemaValidationProvider schemaProvider,
       @Nullable IConfiguration<ValidationFeature<?>> config) throws IOException, ConstraintValidationException {
 
     IValidationResult retval = schemaProvider.validateWithSchema(target, asFormat, this);
 
     if (retval.isPassing()) {
       IValidationResult constraintValidationResult = validateWithConstraints(target, config);
       retval = AggregateValidationResult.aggregate(retval, constraintValidationResult);
     }
     return retval;
   }
 
   /**
    * Load and validate the provided {@code target} using the associated Module
    * module constraints.
    *
    * @param target
    *          the file to load and validate
    * @param config
    *          the validation configuration
    * @return the validation results
    * @throws IOException
    *           if an error occurred while parsing the target
    * @throws ConstraintValidationException
    *           if a constraint violation prevents validation from completing
    */
   default IValidationResult validateWithConstraints(
       @NonNull URI target,
       @Nullable IConfiguration<ValidationFeature<?>> config)
       throws IOException, ConstraintValidationException {
     // Use permissive loader for the target document and any referenced documents
     IBoundLoader loader = newPermissiveBoundLoader();
     // Also disable constraint validation during loading
     loader.disableFeature(DeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTS);
     IDocumentNodeItem nodeItem = loader.loadAsNodeItem(target);
 
     return validate(nodeItem, loader, config);
   }
 
   /**
    * A behavioral class used by the binding context to load Metaschema modules.
    * <p>
    * A module will flow through the following process.
    * <ol>
    * <li><b>Loading:</b> The module is read from its source.
    * <li><b>Post Processing:</b> The module is prepared for use.
    * <li><b>Registration:</b> The module is registered for use.
    * </ol>
    * <p>
    * A module will be loaded when either the module or one of its global
    * definitions is accessed the first time.
    */
   interface IModuleLoaderStrategy extends ModuleLoadingPostProcessor {
     /**
      * Load the bound Metaschema module represented by the provided class.
      * <p>
      * This is the primary entry point for loading an already bound module. This
      * method must ensure that the loaded module is post-processed and registered.
      * <p>
      * Implementations are allowed to return a cached instance if the module has
      * already been loaded by this method.
      *
      * @param clazz
      *          the Module class
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the module
      * @throws IllegalStateException
      *           if an error occurred while processing the associated module
      *           information
      * @since 2.0.0
      */
     @NonNull
     IBoundModule loadModule(
         @NonNull Class<? extends IBoundModule> clazz,
         @NonNull IBindingContext bindingContext);
 
     /**
      * Perform post-processing on the module.
      *
      * @param module
      *          the Metaschema module to post-process
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @since 2.0.0
      */
     @Override
     default void postProcessModule(
         @NonNull IModule module,
         @NonNull IBindingContext bindingContext) {
       // do nothing by default
     }
 
     /**
      * Registers the provided Metaschema module.
      * <p>
      * If this module has not been post-processed, this method is expected to drive
      * post-processing first.
      * <p>
      * If the provided instance is not an instance of {@link IBoundModule}, then
      * annotated Java classes for this module will be generated, compiled, and
      * loaded based on the provided Module.
      *
      * @param module
      *          the Module module to generate classes for
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the registered module, which may be a different instance than what
      *         was provided if dynamic compilation was performed
      * @throws MetaschemaException
      *           if an error occurred while dynamically binding the provided module
      * @throws UnsupportedOperationException
      *           if this binding context is not configured to support dynamic bound
      *           module loading and the module instance is not a subclass of
      *           {@link IBoundModule}
      * @since 2.0.0
      */
     @NonNull
     IBoundModule registerModule(
         @NonNull IModule module,
         @NonNull IBindingContext bindingContext) throws MetaschemaException;
     //
     // /**
     // * Register a matcher used to identify a bound class by the definition's root
     // * name.
     // *
     // * @param definition
     // * the definition to match for
     // * @return the matcher
     // */
     // @NonNull
     // IBindingMatcher registerBindingMatcher(@NonNull IBoundDefinitionModelAssembly
     // definition);
 
     /**
      * Get the matchers used to identify the bound class associated with the
      * definition's root name.
      *
      * @return the matchers
      */
     @NonNull
     Collection<IBindingMatcher> getBindingMatchers();
 
     /**
      * Get the {@link IBoundDefinitionModel} instance associated with the provided
      * Java class.
      * <p>
      * Typically the class will have a {@link MetaschemaAssembly} or
      * {@link MetaschemaField} annotation.
      *
      * @param clazz
      *          the class binding to load
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the associated class binding instance
      * @throws IllegalArgumentException
      *           if the class is not a bound definition with a
      *           {@link MetaschemaAssembly} or {@link MetaschemaField} annotation
      */
     @NonNull
     IBoundDefinitionModelComplex getBoundDefinitionForClass(
         @NonNull Class<? extends IBoundObject> clazz,
         @NonNull IBindingContext bindingContext);
   }
 
   /**
    * Enables building a {@link IBindingContext} using common configuration options
    * based on the builder pattern.
    *
    * @since 2.0.0
    */
   final class BindingContextBuilder {
     private Path compilePath;
     private final List<IModuleLoader.IModulePostProcessor> postProcessors = new LinkedList<>();
     private final List<IConstraintSet> constraintSets = new LinkedList<>();
     @NonNull
     private final Function<IBindingContext.IModuleLoaderStrategy, IBindingContext> initializer;
 
     private BindingContextBuilder() {
       this(DefaultBindingContext::new);
     }
 
     /**
      * Construct a new builder.
      *
      * @param initializer
      *          the callback to use to get a new binding context instance
      */
     public BindingContextBuilder(
         @NonNull Function<IBindingContext.IModuleLoaderStrategy, IBindingContext> initializer) {
       this.initializer = initializer;
     }
 
     /**
      * Enable dynamic code generation and compilation for Metaschema module-based
      * classes.
      *
      * @param path
      *          the path to use to generate and compile Metaschema module-based
      *          classes
      * @return this builder
      */
     @NonNull
     public BindingContextBuilder compilePath(@NonNull Path path) {
       compilePath = path;
       return this;
     }
 
     /**
      * Configure a Metaschema module post processor.
      *
      * @param processor
      *          the post processor to configure
      * @return this builder
      */
     @NonNull
     public BindingContextBuilder postProcessor(@NonNull IModuleLoader.IModulePostProcessor processor) {
       postProcessors.add(processor);
       return this;
     }
 
     /**
      * Configure a set of constraints targeting Metaschema modules.
      *
      * @param set
      *          the constraint set to configure
      * @return this builder
      */
     @NonNull
     public BindingContextBuilder constraintSet(@NonNull IConstraintSet set) {
       constraintSets.add(set);
       return this;
     }
 
     /**
      * Configure a collection of constraint sets targeting Metaschema modules.
      *
      * @param set
      *          the constraint sets to configure
      * @return this builder
      */
     @NonNull
     public BindingContextBuilder constraintSet(@NonNull Collection<IConstraintSet> set) {
       constraintSets.addAll(set);
       return this;
     }
 
     /**
      * Build a {@link IBindingContext} using the configuration options provided to
      * the builder.
      *
      * @return a new, configured binding context
      */
     @NonNull
     public IBindingContext build() {
       // get loader strategy based on if code generation is configured
       IBindingContext.IModuleLoaderStrategy strategy = compilePath == null
           ? new SimpleModuleLoaderStrategy()
           : new SimpleModuleLoaderStrategy(new DefaultModuleBindingGenerator(compilePath));
 
       // determine if any post processors are configured or need to be
       List<IModuleLoader.IModulePostProcessor> processors = new LinkedList<>(postProcessors);
       if (!constraintSets.isEmpty()) {
         processors.add(new ExternalConstraintsModulePostProcessor(constraintSets));
       }
 
       if (!processors.isEmpty()) {
         // post processors are configured, configure the loader strategy to handle them
         strategy = new PostProcessingModuleLoaderStrategy(
             CollectionUtil.unmodifiableList(processors),
             strategy);
       }
 
       return ObjectUtils.notNull(initializer.apply(strategy));
     }
   }
 
   /**
    * Provides schema validation capabilities.
    */
   interface ISchemaValidationProvider {
 
     /**
      * Validate the target resource.
      *
      * @param target
      *          the resource to validate
      * @param asFormat
      *          the format to validate the content as
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the validation result
      * @throws FileNotFoundException
      *           if the resource was not found
      * @throws IOException
      *           if an error occurred while reading the resource
      */
     @NonNull
     default IValidationResult validateWithSchema(
         @NonNull URI target,
         @NonNull Format asFormat,
         @NonNull IBindingContext bindingContext)
         throws FileNotFoundException, IOException {
       URL targetResource = ObjectUtils.notNull(target.toURL());
 
       IValidationResult retval;
       switch (asFormat) {
       case JSON: {
         JSONObject json;
         try (@SuppressWarnings("resource")
         InputStream is
             = new BufferedInputStream(ObjectUtils.notNull(targetResource.openStream()))) {
           json = new JSONObject(new JSONTokener(is));
         }
         retval = getJsonSchema(json, bindingContext).validate(json, target);
         break;
       }
       case XML:
         try {
           retval = getXmlSchemas(targetResource, bindingContext).validate(target);
         } catch (SAXException ex) {
           throw new IOException(ex);
         }
         break;
       case YAML: {
         JSONObject json = YamlOperations.yamlToJson(YamlOperations.parseYaml(target));
         assert json != null;
         retval = getJsonSchema(json, bindingContext).validate(json, ObjectUtils.notNull(target));
         break;
       }
       default:
         throw new UnsupportedOperationException("Unsupported format: " + asFormat.name());
       }
       return retval;
     }
 
     /**
      * Get a JSON schema to use for content validation.
      *
      * @param json
      *          the JSON content to validate
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the JSON schema validator
      * @throws IOException
      *           if an error occurred while loading the schema
      * @since 2.0.0
      */
     @NonNull
     JsonSchemaContentValidator getJsonSchema(@NonNull JSONObject json, @NonNull IBindingContext bindingContext)
         throws IOException;
 
     /**
      * Get a XML schema to use for content validation.
      *
      * @param targetResource
      *          the URL for the XML content to validate
      * @param bindingContext
      *          the Metaschema binding context used to load bound resources
      * @return the XML schema validator
      * @throws IOException
      *           if an error occurred while loading the schema
      * @throws SAXException
      *           if an error occurred while parsing the schema
      * @since 2.0.0
      */
     @NonNull
     XmlSchemaContentValidator getXmlSchemas(@NonNull URL targetResource, @NonNull IBindingContext bindingContext)
         throws IOException, SAXException;
   }
 
   /**
    * Implementations of this interface provide a means by which a bound class can
    * be found that corresponds to an XML element, JSON property, or YAML item
    * name.
    */
   interface IBindingMatcher {
     /**
      * Construct a new binding matcher for the provided assembly definition.
      *
      * @param assembly
      *          the assembly definition that matcher is for
      * @return the matcher
      */
     @NonNull
     static IBindingMatcher of(IBoundDefinitionModelAssembly assembly) {
       if (!assembly.isRoot()) {
         throw new IllegalArgumentException(
             String.format("The provided class '%s' is not a root assembly.", assembly.getBoundClass().getName()));
       }
       return new RootAssemblyBindingMatcher(assembly);
     }
 
     /**
      * Determine the bound class for the provided XML {@link QName}.
      *
      * @param rootQName
      *          the root XML element's QName
      * @return the bound class for the XML qualified name or {@code null} if not
      *         recognized
      */
     Class<? extends IBoundObject> getBoundClassForXmlQName(QName rootQName);
 
     /**
      * Determine the bound class for the provided JSON/YAML property/item name.
      *
      * @param rootName
      *          the JSON/YAML property/item name
      * @return the bound class for the JSON property name or {@code null} if not
      *         recognized
      */
     Class<? extends IBoundObject> getBoundClassForJsonName(String rootName);
   }
 }