001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.model.annotations;
007
008import static java.lang.annotation.ElementType.FIELD;
009import static java.lang.annotation.ElementType.METHOD;
010import static java.lang.annotation.RetentionPolicy.RUNTIME;
011
012import java.lang.annotation.Documented;
013import java.lang.annotation.Retention;
014import java.lang.annotation.Target;
015
016import dev.metaschema.core.datatype.IDataTypeAdapter;
017import dev.metaschema.core.model.IBoundObject;
018import edu.umd.cs.findbugs.annotations.NonNull;
019
020/**
021 * Identifies that the annotation target is a bound property that references a
022 * Module field.
023 * <p>
024 * For XML serialization, the {@link #useName()} identifies the name of the
025 * element to use for this element.
026 * <p>
027 * For JSON and YAML serializations, the {@link #useName()} identifies the
028 * property/item name to use.
029 * <p>
030 * The field must be either:
031 * <ol>
032 * <li>A Module data type or a collection whose item value is Module data type,
033 * with a non-null {@link #typeAdapter()}.
034 * <li>A type or a collection whose item value is a type based on a class with a
035 * {@link MetaschemaField} annotation, with a property annotated with
036 * {@link BoundFieldValue}.
037 * </ol>
038 */
039@Documented
040@Retention(RUNTIME)
041@Target({ FIELD, METHOD })
042public @interface BoundGroupedField {
043  /**
044   * Get the documentary formal name of the field.
045   * <p>
046   * If the value is "##none", then the description will be considered
047   * {@code null}.
048   *
049   * @return a markdown string or {@code "##none"} if no formal name is provided
050   */
051  @NonNull
052  String formalName() default ModelUtil.NO_STRING_VALUE;
053
054  /**
055   * Get the documentary description of the field.
056   * <p>
057   * If the value is "##none", then the description will be considered
058   * {@code null}.
059   *
060   * @return a markdown string or {@code "##none"} if no description is provided
061   */
062  @NonNull
063  String description() default ModelUtil.NO_STRING_VALUE;
064
065  /**
066   * The model name to use for JSON/YAML singleton values and associated XML
067   * elements.
068   * <p>
069   * If the value is "##none", then the use name will be provided by the
070   * definition or by the field name if the item value class is missing the
071   * {@link MetaschemaField} annotation.
072   *
073   * @return the name
074   */
075  @NonNull
076  String useName() default ModelUtil.NO_STRING_VALUE;
077
078  /**
079   * The binary use name of the field.
080   * <p>
081   * The value {@link Integer#MIN_VALUE} indicates that there is no use name.
082   *
083   * @return the index value
084   */
085  int useIndex() default Integer.MIN_VALUE;
086
087  /**
088   * The Metaschema data type adapter for the field's value.
089   *
090   * @return the data type adapter
091   */
092  @NonNull
093  Class<? extends IDataTypeAdapter<?>> typeAdapter() default NullJavaTypeAdapter.class;
094
095  /**
096   * An optional set of associated properties.
097   *
098   * @return the properties or an empty array with no properties
099   */
100  Property[] properties() default {};
101
102  /**
103   * Get any remarks for this field.
104   *
105   * @return a markdown string or {@code "##none"} if no remarks are provided
106   */
107  @NonNull
108  String remarks() default ModelUtil.NO_STRING_VALUE;
109
110  /**
111   * Get the value constraints defined for this Metaschema field inline
112   * definition.
113   *
114   * @return the value constraints
115   */
116  ValueConstraints valueConstraints() default @ValueConstraints;
117
118  /**
119   * Get any remarks for this field.
120   *
121   * @return the discriminator string or {@code "##none"} if no discriminator is
122   *         provided
123   */
124  @NonNull
125  String discriminatorValue() default ModelUtil.NO_STRING_VALUE;
126
127  /**
128   * The bound class associated with this assembly.
129   * <p>
130   * This is optional when used on a field or method, and required when used with
131   * an annotation type value, i.e. {@link BoundChoiceGroup}.
132   *
133   * @return the bound class
134   */
135  @NonNull
136  Class<? extends IBoundObject> binding();
137}