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.IConstraint;
016import dev.metaschema.core.model.constraint.IConstraint.Level;
017import edu.umd.cs.findbugs.annotations.NonNull;
018
019/**
020 * This annotation defines cardinality condition(s) to be met in the context of
021 * the containing annotation.
022 */
023@Documented
024@Retention(RUNTIME)
025@Target(ANNOTATION_TYPE)
026public @interface HasCardinality {
027  /**
028   * An optional identifier for the constraint, which must be unique to only this
029   * constraint.
030   *
031   * @return the identifier if provided or an empty string otherwise
032   */
033  @NonNull
034  String id() default "";
035
036  /**
037   * An optional formal name for the constraint.
038   *
039   * @return the formal name if provided or an empty string otherwise
040   */
041  @NonNull
042  String formalName() default "";
043
044  /**
045   * An optional description of the constraint.
046   *
047   * @return the description if provided or an empty string otherwise
048   */
049  @NonNull
050  String description() default "";
051
052  /**
053   * The significance of a violation of this constraint.
054   *
055   * @return the level
056   */
057  @NonNull
058  Level level() default IConstraint.Level.ERROR;
059
060  /**
061   * An optional metapath that points to the target flag or field value that the
062   * constraint applies to. If omitted the target will be ".", which means the
063   * target is the value of the {@link BoundFlag}, {@link BoundField} or
064   * {@link BoundFieldValue} annotation the constraint appears on. In the prior
065   * case, this annotation may only appear on a {@link BoundField} if the field
066   * has no flags, which results in a {@link BoundField} annotation on a field
067   * instance with a scalar, data type value.
068   *
069   * @return the target metapath
070   */
071  @NonNull
072  String target() default ".";
073
074  /**
075   * An optional set of properties associated with these allowed values.
076   *
077   * @return the properties or an empty array with no properties
078   */
079  Property[] properties() default {};
080
081  /**
082   * The minimum occurrence of the target. This value cannot be less than or equal
083   * to the corresponding value defined on the target. The value must be greater
084   * than {@code 0}.
085   *
086   * @return a non-negative integer or {@code -1} if not defined
087   */
088  int minOccurs() default -1;
089
090  /**
091   * The maximum occurrence of the target. This value must be greater than or
092   * equal to the {@link #minOccurs()} if both are provided. This value must be
093   * less than the corresponding value defined on the target.
094   *
095   * @return a non-negative integer or {@code -1} if not defined
096   */
097  int maxOccurs() default -1;
098
099  /**
100   * The message to emit when the constraint is violated.
101   *
102   * @return the message or an empty string otherwise
103   */
104  @NonNull
105  String message() default "";
106
107  /**
108   * Any remarks about the constraint, encoded as an escaped Markdown string.
109   *
110   * @return an encoded markdown string or an empty string if no remarks are
111   *         provided
112   */
113  @NonNull
114  String remarks() default "";
115}