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 an expected condition to be met in the context of the
021 * containing annotation.
022 */
023@Documented
024@Retention(RUNTIME)
025@Target(ANNOTATION_TYPE)
026public @interface Expect {
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   * A metapath that is expected to evaluate to {@code true} in this context.
083   *
084   * @return a metapath expression
085   */
086  @NonNull
087  String test();
088
089  /**
090   * The message to emit when the constraint is violated.
091   *
092   * @return the message or an empty string otherwise
093   */
094  @NonNull
095  String message() default "";
096
097  /**
098   * Any remarks about the constraint, encoded as an escaped Markdown string.
099   *
100   * @return an encoded markdown string or an empty string if no remarks are
101   *         provided
102   */
103  @NonNull
104  String remarks() default "";
105}