default void buildFieldJavadoc(FieldSpec.Builder builder) {
    MarkupLine description = getInstance().getEffectiveDescription();
    if (description != null) {
      builder.addJavadoc("$L\n", description.toHtml());
    }
  }

  /**
   * {@inheritDoc}
   *
   * <p>
   * This implementation generates getter Javadoc using the instance's formal name
   * (if available) or property name, adds the effective description, and includes
   * an appropriate {@code @return} tag based on whether the property is required
   * or a collection.
   */
  @Override
  default void buildGetterJavadoc(@NonNull MethodSpec.Builder builder) {
    MarkupLine description = getInstance().getEffectiveDescription();
    String formalName = getInstance().getEffectiveFormalName();
    String propertyName = getInstance().getEffectiveName();

    // Use formal name if available, otherwise property name
    if (formalName != null) {
      builder.addJavadoc("Get the \"{@literal $L}\".\n", formalName);
    } else {
      builder.addJavadoc("Get the {@code $L} property.\n", propertyName);
    }

    // Add description as a second paragraph if available
    if (description != null) {
      builder.addJavadoc("\n");
      builder.addJavadoc("<p>\n");
      builder.addJavadoc("$L\n", description.toHtml());
    }

    builder.addJavadoc("\n");
    // Collections are always @NonNull (lazy initialized), required properties are
    // @NonNull
    if (isRequired() || isCollectionType()) {
      builder.addJavadoc("@return the $L value\n", propertyName);
    } else {
      builder.addJavadoc("@return the $L value, or {@code null} if not set\n", propertyName);
    }
  }

  /**
   * {@inheritDoc}
   *
   * <p>
   * This implementation generates setter Javadoc using the instance's formal name
   * (if available) or property name, adds the effective description, and includes
   * a {@code @param} tag for the value parameter.
   */
  @Override
  default void buildSetterJavadoc(@NonNull MethodSpec.Builder builder, @NonNull String paramName) {
    MarkupLine description = getInstance().getEffectiveDescription();
    String formalName = getInstance().getEffectiveFormalName();
    String propertyName = getInstance().getEffectiveName();

    // Use formal name if available, otherwise property name
    if (formalName != null) {
      builder.addJavadoc("Set the \"{@literal $L}\".\n", formalName);
    } else {
      builder.addJavadoc("Set the {@code $L} property.\n", propertyName);
    }

    // Add description as a second paragraph if available
    if (description != null) {
      builder.addJavadoc("\n");
      builder.addJavadoc("<p>\n");
      builder.addJavadoc("$L\n", description.toHtml());
    }

    builder.addJavadoc("\n");
    builder.addJavadoc("@param $L\n", paramName);
    // Collections and required properties require non-null values;
    // optional properties can be set to null to clear
    if (isRequired() || isCollectionType()) {
      builder.addJavadoc("          the $L value to set\n", propertyName);
    } else {
      builder.addJavadoc("          the $L value to set, or {@code null} to clear\n", propertyName);
    }
  }
}

ISource source = module.getSource();

    this.javaTypeAdapter = ModelSupport.dataType(
        binding.getAsType(),
        source);
    this.defaultValue = ModelSupport.defaultValue(binding.getDefault(), this.javaTypeAdapter);
    this.flagContainer = ObjectUtils.notNull(Lazy.of(() -> {
      JsonKey jsonKey = binding.getJsonKey();
      return FlagContainerSupport.newFlagContainer(
          binding.getFlags(),
          bindingInstance,
          this,
          jsonKey == null ? null : jsonKey.getFlagRef());
    }));
    this.valueConstraints = ObjectUtils.notNull(Lazy.of(() -> {
      IValueConstrained retval = new ValueConstraintSet(source);
      FieldConstraints constraints = binding.getConstraint();
      if (constraints != null) {
        ConstraintBindingSupport.parse(retval, constraints, source);
      }
      return retval;
    }));

IGroupAs groupAs = ModelUtil.resolveDefaultGroupAs(
        annotation.groupAs(),
        parent.getContainingModule());
    if (annotation.maxOccurs() == -1 || annotation.maxOccurs() > 1) {
      if (IGroupAs.SINGLETON_GROUP_AS.equals(groupAs)) {
        throw new IllegalStateException(String.format("Field '%s' on class '%s' is missing the '%s' annotation.",
            javaField.getName(),
            javaField.getDeclaringClass().getName(),
            GroupAs.class.getName()));
      }
    } else if (!IGroupAs.SINGLETON_GROUP_AS.equals(groupAs)) {
      // max is 1 and a groupAs is set
      throw new IllegalStateException(
          String.format(
              "Field '%s' on class '%s' has the '%s' annotation, but maxOccurs=1. A groupAs must not be specfied.",
              javaField.getName(),
              javaField.getDeclaringClass().getName(),
              GroupAs.class.getName()));
    }
    return new InstanceModelFieldComplex(javaField, annotation, groupAs, definition, parent);

@NonNull IValueTargetedConstraintsBase constraints,
      @NonNull ISource source) {
    parseLet(constraintSet, constraints, source);

    // parse rules
    for (IConstraintBase ruleObj : constraints.getRules()) {
      if (ruleObj instanceof TargetedAllowedValuesConstraint) {
        IAllowedValuesConstraint constraint = newAllowedValues((TargetedAllowedValuesConstraint) ruleObj, source);
        constraintSet.addConstraint(constraint);
      } else if (ruleObj instanceof TargetedExpectConstraint) {
        IExpectConstraint constraint = newExpect((TargetedExpectConstraint) ruleObj, source);
        constraintSet.addConstraint(constraint);
      } else if (ruleObj instanceof TargetedIndexHasKeyConstraint) {
        IIndexHasKeyConstraint constraint = newIndexHasKey((TargetedIndexHasKeyConstraint) ruleObj, source);
        constraintSet.addConstraint(constraint);
      } else if (ruleObj instanceof TargetedMatchesConstraint) {
        IMatchesConstraint constraint = newMatches((TargetedMatchesConstraint) ruleObj, source);
        constraintSet.addConstraint(constraint);
      } else if (ruleObj instanceof TargetedReportConstraint) {

static Class<?> getItemType(@NonNull Field field) {
    Type fieldType = field.getGenericType();
    Class<?> rawType = ObjectUtils.notNull(
        (Class<?>) (fieldType instanceof ParameterizedType ? ((ParameterizedType) fieldType).getRawType() : fieldType));

    Class<?> itemType;
    if (Map.class.isAssignableFrom(rawType)) {
      // this is a Map so the second generic type is the value
      itemType = ObjectUtils.notNull((Class<?>) ((ParameterizedType) fieldType).getActualTypeArguments()[1]);
    } else if (List.class.isAssignableFrom(rawType)) {
      // this is a List so there is only a single generic type
      itemType = ObjectUtils.notNull((Class<?>) ((ParameterizedType) fieldType).getActualTypeArguments()[0]);
    } else {
      // non-collection
      itemType = rawType;
    }
    return itemType;

@Nullable MetaschemaBindings.MetaschemaBinding.DefineAssemblyBinding.Java java) {
    IMutableDefinitionBindingConfiguration config = oldConfig == null
        ? new DefaultDefinitionBindingConfiguration()
        : new DefaultDefinitionBindingConfiguration(oldConfig);

    if (java != null) {
      String className = java.getUseClassName();
      if (className != null) {
        config.setClassName(ObjectUtils.notNull(className));
      }

      String baseClass = java.getExtendBaseClass();
      if (baseClass != null) {
        config.setQualifiedBaseClassName(ObjectUtils.notNull(baseClass));
      }

      List<String> interfaces = java.getImplementInterfaces();
      for (String interfaceName : interfaces) {
        config.addInterfaceToImplement(Objects.requireNonNull(interfaceName,
            "interface name cannot be null in implement-interfaces configuration"));
      }
    }
    return config;
  }

IExpectConstraint.Builder builder = IExpectConstraint.builder();
    applyId(builder, constraint.id());
    applyFormalName(builder, constraint.formalName());
    applyDescription(builder, constraint.description());
    builder
        .source(source)
        .level(constraint.level());
    applyTarget(builder, metapath(constraint.target(), source));
    applyProperties(builder, constraint.properties());
    applyMessage(builder, constraint.message());
    applyRemarks(builder, constraint.remarks());

    builder.test(metapath(constraint.test(), source));

    return builder.build();
  }

  /**
   * Create a new report constraint from the provided annotation.
   * <p>
   * Report constraints generate findings when their test expression evaluates to
   * {@code true}, which is the opposite of expect constraints.
   *
   * @param constraint
   *          the annotation containing the constraint configuration
   * @param source
   *          the source of the constraint
   * @return a new report constraint
   */
  @NonNull

for (MetaschemaModuleConstraints.Import imported : imports) {
            URI importedResource = imported.getHref();
            importedResource = ObjectUtils.notNull(resource.resolve(importedResource));
            importedConstraints.addAll(loadInternal(importedResource, visitedResources));
          }
        } catch (MetaschemaException ex) {
          throw new IOException(ex);
        }
      }

      // handle namespace to prefix bindings
      CollectionUtil.listOrEmpty(obj.getNamespaceBindings()).stream()
          .forEach(binding -> builder.namespace(
              ObjectUtils.notNull(binding.getPrefix()),
              ObjectUtils.notNull(binding.getUri())));
      ISource source = ISource.externalSource(builder.build(), false);

IIndexConstraint.Builder builder = IIndexConstraint.builder(constraint.name());
    applyId(builder, constraint.id());
    applyFormalName(builder, constraint.formalName());
    applyDescription(builder, constraint.description());
    builder
        .source(source)
        .level(constraint.level());
    applyTarget(builder, metapath(constraint.target(), source));
    applyProperties(builder, constraint.properties());
    applyMessage(builder, constraint.message());
    applyRemarks(builder, constraint.remarks());

    applyKeyFields(builder, source, constraint.keyFields());

    return builder.build();
  }

  @NonNull
  static IIndexHasKeyConstraint newIndexHasKeyConstraint(

this.properties = ModelSupport.parseProperties(ObjectUtils.requireNonNull(binding.getProps()));
    this.flagContainer = ObjectUtils.notNull(Lazy.of(() -> {
      JsonKey jsonKey = getBinding().getJsonKey();
      return FlagContainerSupport.newFlagContainer(
          binding.getFlags(),
          bindingInstance,
          this,
          jsonKey == null ? null : jsonKey.getFlagRef());
    }));
    this.modelContainer = ObjectUtils.notNull(Lazy.of(() -> AssemblyModelGenerator.of(
        binding.getModel(),
        ObjectUtils.requireNonNull(bindingInstance.getDefinition()
            .getAssemblyInstanceByName(MetaschemaModelConstants.MODEL_QNAME.getIndexPosition())),
        this,
        nodeItemFactory)));

    ISource source = module.getSource();

return ObjectUtils.notNull(valueConstraints.get());
  }

  @Override
  public Map<IAttributable.Key, Set<String>> getProperties() {
    return properties;
  }

  @Override
  public IDataTypeAdapter<?> getJavaTypeAdapter() {
    return javaTypeAdapter;
  }

  @Override
  public Object getDefaultValue() {
    return defaultValue;
  }

  @Override
  public String getName() {
    return ObjectUtils.notNull(getBinding().getName());
  }

  @Override
  public String getFormalName() {
    return getBinding().getFormalName();
  }

  @Override
  public MarkupLine getDescription() {
    return getBinding().getDescription();
  }

  @Override
  public ModuleScope getModuleScope() {

handler.writeItemAssembly(item, this);
  }

  @Override
  default IBoundObject deepCopyItem(IBoundObject item, IBoundObject parentInstance) throws BindingException {
    return getDefinition().deepCopyItem(item, parentInstance);
  }

  @Override
  default Class<? extends IBoundObject> getBoundClass() {
    return getDefinition().getBoundClass();
  }

  @Override
  default void callBeforeDeserialize(IBoundObject targetObject, IBoundObject parentObject) throws BindingException {
    getDefinition().callBeforeDeserialize(targetObject, parentObject);
  }

  @Override
  default void callAfterDeserialize(IBoundObject targetObject, IBoundObject parentObject) throws BindingException {
    getDefinition().callAfterDeserialize(targetObject, parentObject);
  }
}

ISource source = module.getSource();

    this.javaTypeAdapter = ModelSupport.dataType(
        binding.getAsType(),
        source);
    this.defaultValue = ModelSupport.defaultValue(binding.getDefault(), this.javaTypeAdapter);
    this.valueConstraints = ObjectUtils.notNull(Lazy.of(() -> {
      IValueConstrained retval = new ValueConstraintSet(source);
      FlagConstraints constraints = binding.getConstraint();
      if (constraints != null) {
        ConstraintBindingSupport.parse(retval, constraints, source);
      }
      return retval;
    }));
    this.boundNodeItem = ObjectUtils.notNull(Lazy.of(() -> ObjectUtils.requireNonNull(ModelSupport.toNodeItem(

}

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
    }

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances,
        ValidationContext context) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances, context);
    }

    @Override
    public boolean handleUnknownProperty(
        IBoundDefinitionModelComplex definition,
        IBoundObject parentItem,
        String fieldName,
        IJsonParsingContext parsingContext) throws IOException {
      boolean retval;
      if (instance.getParentContainer().getJsonDiscriminatorProperty().equals(fieldName)) {

ObjectUtils.notNull(binding.getInstances()).forEach(obj -> {
      assert obj != null;
      IBoundInstanceModelGroupedAssembly objInstance
          = (IBoundInstanceModelGroupedAssembly) instance.getItemInstance(obj);

      if (obj instanceof AssemblyReference) {
        generator.addAssemblyInstance((AssemblyReference) obj, objInstance);
      } else if (obj instanceof InlineDefineAssembly) {
        generator.addAssemblyInstance((InlineDefineAssembly) obj, objInstance);
      } else if (obj instanceof FieldReference) {
        generator.addFieldInstance((FieldReference) obj, objInstance);
      } else if (obj instanceof InlineDefineField) {
        generator.addFieldInstance((InlineDefineField) obj, objInstance);
      } else if (obj instanceof AssemblyModel.Choice) {

@NonNull INodeItemFactory nodeItemFactory) {
    super(parent);
    this.binding = binding;
    this.properties = ModelSupport.parseProperties(ObjectUtils.requireNonNull(binding.getProps()));
    this.groupAs = ModelSupport.groupAs(binding.getGroupAs(), parent.getOwningDefinition().getContainingModule());
    this.boundNodeItem = ObjectUtils.notNull(
        Lazy.of(() -> (IAssemblyNodeItem) ObjectUtils.notNull(getContainingDefinition().getSourceNodeItem())
            .getModelItemsByName(bindingInstance.getQName())
            .get(position)));