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.ANNOTATION_TYPE;
009import static java.lang.annotation.RetentionPolicy.RUNTIME;
010
011import java.lang.annotation.Documented;
012import java.lang.annotation.Retention;
013import java.lang.annotation.Target;
014
015import dev.metaschema.core.model.constraint.IAllowedValuesConstraint;
016import dev.metaschema.core.model.constraint.IConstraint;
017import dev.metaschema.core.model.constraint.IConstraint.Level;
018import edu.umd.cs.findbugs.annotations.NonNull;
019
020/**
021 * This annotation defines a set of values permitted to be used in the context
022 * of the containing annotation.
023 */
024@Documented
025@Retention(RUNTIME)
026@Target(ANNOTATION_TYPE)
027public @interface AllowedValues {
028  /**
029   * An optional identifier for the constraint, which must be unique to only this
030   * constraint.
031   *
032   * @return the identifier if provided or an empty string otherwise
033   */
034  @NonNull
035  String id() default "";
036
037  /**
038   * An optional formal name for the constraint.
039   *
040   * @return the formal name if provided or an empty string otherwise
041   */
042  @NonNull
043  String formalName() default "";
044
045  /**
046   * An optional description of the constraint.
047   *
048   * @return the description if provided or an empty string otherwise
049   */
050  @NonNull
051  String description() default "";
052
053  /**
054   * The significance of a violation of this constraint.
055   *
056   * @return the level
057   */
058  @NonNull
059  Level level() default IConstraint.Level.ERROR;
060
061  /**
062   * An optional metapath that points to the target flag or field value that the
063   * constraint applies to. If omitted the target will be ".", which means the
064   * target is the value of the {@link BoundFlag}, {@link BoundField} or
065   * {@link BoundFieldValue} annotation the constraint appears on. In the prior
066   * case, this annotation may only appear on a {@link BoundField} if the field
067   * has no flags, which results in a {@link BoundField} annotation on a field
068   * instance with a scalar, data type value.
069   *
070   * @return the target metapath
071   */
072  @NonNull
073  String target() default ".";
074
075  /**
076   * An optional set of properties associated with these allowed values.
077   *
078   * @return the properties or an empty array with no properties
079   */
080  Property[] properties() default {};
081
082  /**
083   * Get any allowed values for this constraint.
084   *
085   * @return an array of allowed value enumerations
086   */
087  @NonNull
088  AllowedValue[] values();
089
090  /**
091   * Indicates if the constraint allows other values not included in the
092   * enumerated list.
093   *
094   * @return {@code true} if other values are allowed or {@code false} otherwise
095   */
096  boolean allowOthers() default IAllowedValuesConstraint.ALLOW_OTHER_DEFAULT;
097
098  /**
099   * Indicates if the constraint can be extended by other constraints.
100   *
101   * @return the extension mode
102   */
103  @NonNull
104  IAllowedValuesConstraint.Extensible extensible() default IAllowedValuesConstraint.Extensible.EXTERNAL;
105
106  /**
107   * Any remarks about the constraint, encoded as an escaped Markdown string.
108   *
109   * @return an encoded markdown string or an empty string if no remarks are
110   *         provided
111   */
112  @NonNull
113  String remarks() default "";
114}