Git Product home page Git Product logo

validation-spec's Introduction

Jakarta Validation specification

This repository contains the Jakarta Validation specification. For more information on Jakarta Validation and the work in progress, go to https://beanvalidation.org.

Building docs

The specification is written in the AsciiDoc format. In order to convert this into nicely rendered output, you need to have Apache Ant installed on your system and available on your classpath. The build file build.xml is located in this directory and all commands are relative to this directory.

  • Running ant all.doc builds both PDF and HTML output in the target/ directory. all.doc is also the default target.
  • Running ant clean will clean up output HTML and PDF files.
  • Running ant render-html will only build the HTML output (much faster).

The pom.xml in the root directory is an in-progress migration to build with maven. It can be run with mvn clean package, however Ant is still currently the official build method.

Tagging phrases for the TCK

The Jakarta Validation TCK is a suite of unit tests for validating the compliance of Jakarta Validation implementations with the specification.

The tests of the TCK are based on assertions representing sentences and phrases in this specification. Labels on specific text elements of the specification are used to mark those which should lead to an assertion in the TCK. The following values are allowed:

  • tck-testable: The tagged element must be represented by a testable assertion in the TCK
  • tck-not-testable: The tagged element must be represented by a non-testable assertion in the TCK (e.g. assertions regarding thread safety)
  • tck-ignore: The tagged element must be excluded when creating a TCK assertion for an outer element. Can be used to exlude explanatory phrases contained in an element marked as tck-testable.
  • tck-needs-update: The tagged element must be marked with a note in the TCK audit file saying that the tests for this assertion need to be updated, e.g. due to a spec update. Can be used together with tck-testable and tck-not-testable: [tck-testable tck-needs-update]#Some sentence...#.

Updating the TCK audit file

The TCK audit file is an XML file containing all assertions of the TCK. This file is generated with help of an XSL transformation (for that purpose the spec is converted into DocBook).

The generation is executed by running ant create-tck-audit-file. This is required whenever tagged elements have been added, updated, removed or changed their position within all tagged elements of a section.

The generated file target/tck-audit.xml should not be re-formatted and must be checked into the TCK project. If an update changed the section numbers of existing assertions, the corresponding tests need to be adapted as well since they reference the section numbers in the @SpecAssertion annotation.

Contributing to the specification

By submitting a "pull request" or otherwise contributing to this repository, you agree to license your contribution under the Apache Software License 2.0.

The recommended approach to contribute to the spec is via GitHub pull requests. More on contribution at http://beanvalidation.org/contribute/

Make sure to not go beyond 80 columns per line.

Style rules

  • use [...] for omissions, prefer it on a dedicated line rather than inlined. For declaration, use a ; after User user = [...];
  • remove email in @author
  • use @author on classes or interfaces (non inner)
  • use {@link} for method reference (the first in the JavaDoc of the element) except if it references external classes and if it references the class or element at bay.
  • reference methods with a trailing () but be careful that some methodname are actually annotation attributes and thus should not have ()
  • in the spec use [methodname]`Foo.bar` and in the JavaDoc {@link Foo#bar()}
  • no import statement
  • add package statement
  • use <p/> to separate paragraphs but do not use <p>blah blah</p>
  • empty line between the @param, @return, @throws group and the other @tag elements
  • @throws does not use {@link } for the exception
  • import classes used by {@link} and @throws exceptions so that the unqualified name works
  • something is true but a method returns <literal>true</literal>
  • use <ul> for lists
  • <li> are indented by 4 spaces compared to <ul>
  • multiline @param, @return etc are indented to align with the beginning of the text of the element
  • the core of the JavaDoc uses capital letters and punctuation like in plain English
  • @tag attributes do not use capital letters for the beninning of a sentence nor use dots in the end, prefer ; to separate sentences in this situation
  • use verbs at the third person instead of the imperative tense (?!): Returns foo instead of Return foo.
  • use <pre> </pre> for multiline code example. <pre> elements should be on a separate line
  • use an empty line between a class / interface declaration and the first element in the block

Here is an example

/**
 * Returns the complementary elements related to {@link FooBar#baz()}.
 * This allows to break things apart.
 * <p/>
 * Demolition mileage may vary depending on the robustness
 * of {@code FooBar} when using {@code List}:
 * <ul>
 *     <li>This is a beginning</li>
 *     <li>This is the end</li>
 * </ul>
 * <pre>
 * Some code = new Some();
 * if (size >12) {
 *     code.doStuff();
 * }
 * </pre>
 *
 * @param test this is a long description that needs
 *        to be done on several lines, yep
 * @param foo this is another param
 * @return the result
 * @throws IllegalArgumentException when things happen
 *
 * @since 1.1
 * @deprecated
 */
public void someMethod() {
    User user = [...];
    [...]
}

/**
 * Welcome to this element related to {@link FooBar}.
 * This allowed to break things apart.
 * <p/>
 * Demolition mileage may vary depending on the robustness
 * of {@code FooBar} when using {@code List}
 *
 * @author Emmanuel Bernard
 * @since 1.1
 * @deprecated
 */
public class GoodStuff {

    /**
     * [...]
     */
    [...]
}

For the API, in particular the JavaDoc, follow the conventions described at http://hibernate.org/validator/contribute/#coding-guidelines.

Showing tck assertion coverage

You can update the file docinfo/index-docinfo.html to show what is covered and what is not covered by the TCK assertion coverage.

validation-spec's People

Contributors

ahus1 avatar davided avatar dependabot[bot] avatar emmanuelbernard avatar gsmet avatar gunnarmorling avatar hendrikebbers avatar hferentschik avatar hibernate-ci avatar kasabuta4 avatar mswatosh avatar pzygielo avatar sanne avatar starksm64 avatar stevep001 avatar yrodiere avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

validation-spec's Issues

Enforce constraint validators to support injection if CDI is available

I thought this was actually enforced in the spec since a long time, but it turns out it's not:

If CDI is supported in the container, it would be a benefit for developers if they could rely that an implementation also supports dependency injection in the validator.

https://beanvalidation.org/2.0/spec/#integration-dependencyinjection enforces this only that the validator must be injectable itself, but not "inside". Additionally the scope then should be handled by CDI, if a CDI scoped annotation is present.

Example

@ApplicationScoped
public class OrderValidator implements ConstraintValidator<ValidOrder, CoffeeOrder> {

  @Inject
  CoffeeShop coffeeShop;

  // ...

Most impls IMO do this already, but it turns out not all (e.g. Payara), since it's not enforced in the spec. WDYT?

Deliver beanvalidation-spec Specification Version update for Jakarta EE 9

Is your feature request related to a problem? Please describe.
Jakarta EE 9 is the next major release, with the main focus of moving from the javax namespace to the jakarta namespace.

Describe the solution you'd like
This issue will be used to track the progress of this work effort via the Jakarta EE 9 Project board.

Additional context
Jakarta EE Specification Process
Eclipse Project Handbook
Eclipse Release Record for Jakarta EE 9

ToDo

  • Create Eclipse Release Record in your respective Jakarta Specification Project.
    Most Component Release Records will just reference the Jakarta EE 9 Platform Release Plan. But, if your Component deviates at all from the Platform Release Plan, then a description of the changes will be required in the Release Record.
  • Initiate a ballot for your Jakarta Release Record/Plan.
    Again, if your component is only doing the required minimum as defined by the Jakarta EE 9 Platform Release Plan, then no separate ballot is required. You are already approved. But, if your component deviates from the Platform Release Plan, then you will need to initiate your own ballot as defined by the Jakarta EE Specification Process.
  • Jakarta-ize your Specification document (if applicable)
    Many of the Jakarta EE components now have the source for their Specification documents. It is strongly recommended that these Specification documents are properly updated to represent Jakarta EE instead of Java EE. Some helpful instructions are documented here.
  • javax -> jakarta Spec updates
    If your component has Specification source, then all javax package references need to be updated to use jakarta package references.
  • javax -> jakarta API updates
    Your component APIs need to move from using the javax namespace to using the jakarta namespace.
  • Release Candidate (RC) of Jakarta API in Maven Central
    A Release Candidate of your component API should be pushed to Maven Central as soon as humanly possible. This will allow other dependent components to utilize your APIs as they are updating their APIs. Multiple revisions of these Release Candidate APIs are allowed (and probably expected) during the development cycle.
  • javax -> jakarta TCK updates
    Your component TCK needs to be updated to use the jakarta namespace.
  • javax -> jakarta Compatible Implementation updates
    Your compatible implementation that will be used to demonstrate completeness of the Specification needs to be updated to use the jakarta namespace.
  • Final Jakarta API available in Staging Repo
    When ready, your final version of the API needs to be staged to get ready for the PR review and approvals.
  • Draft Specification and Apidoc PRs ready for review
    Like we did for Jakarta EE 8, draft PRs need to be created and reviewed in preparation for the final ballots.
  • Release Review Ballot started
    Each Jakarta EE component will need to initiate a separate Release Review ballot after proper reviewing has completed. To be clear, there will not be a blanket Release Review for all of Jakarta EE 9 like we did for the Plan Review. Each component needs a separate Release Review.

Compatibility certification request for Hibernate Validator

Make support for record validation explicit

Probably doesn't require much, as validation pretty much "Just works" for records, too. But it would still be nice to make it explicit in the spec, have some examples, state that the constructor components should be annotated, etc.

Another question is how to trigger validation of records, as it essentially requires hooking into constructor calls, e.g. via byte code weaving. I've explored this a while ago here.

Complete the release of Bean Validation 3.0

Copied from Specification PR #222...

Per our updated process, moving these items to a separate issue against the Spec Project:

  • The specification project member who created the api staging release promotes the specification api jars to maven central. An example release job script can be found here https://wiki.eclipse.org/MavenReleaseScript.
  • The specification project team should go through the merged spec website page to verify all the links are valid.
  • The specification project team should approve the compatibility request.
  • The compatible implementation project/vendor MUST send an email to [email protected] for approval of the compatible implementation for trademark usage.
  • The specification project team should merge any final release branch as appropriate for the branch management for the project.

Finalize the release of Jakarta Validation 3.1

Project team:

  • promotes api staging release promotes the specification api jars to maven central. An example release job script can be found here https://wiki.eclipse.org/MavenReleaseScript.
  • go through the merged jakarta.ee specification website page to verify all the links are valid.
  • if XML Schemas are published on https://jakarta.ee/schemas, send a PR to update the status from Draft to Final.
  • approve the compatibility request.
  • merge any final release branch as appropriate for the branch management for the project.

Update EFSL for Specifications and Javadoc

Per the discussions on the Spec Committee and Platform Dev mailing lists, it's been discovered that many of the Javadoc and Spec references to the EFSL need updating. Please reference the following required updates and keep them in mind as your Spec Project is updating the files for Jakarta EE 9.

Note: Some Spec Projects have already started or even completed these updates. If so, just kindly return/close this Issue. Thanks!

Required EFSL updates for Javadoc

For javadoc, the EFSL.html located in src/main/javadoc/doc-files should be modified as follows:

  • the <<url to this license>> needs to be replaced with efsl.php link[1]
  • the [title and URI of the Eclipse Foundation specification document] needs to be replaced with the Specification Name and URL (Reference [2] for an example.)
  • The javadoc footer copyright year needs to be updated to 2018, 2020 as defined in the pom.xml

Required EFSL updates for Specifications

For specification, the license-efsl.adoc located in src/main/asciidoc should be modified as follows:

  • Update copyright year to 2018, 2020 from 2019. Add link to EFSL.
  • the <<url to this license>> needs to be replaced with efsl.php link[1]
  • the [title and URI of the Eclipse Foundation specification document] needs to be replaced with the Specification Name and URL (Reference [2] for an example.)

[1] https://www.eclipse.org/legal/efsl.php
[2] https://jakarta.ee/specifications/enterprise-beans/4.0/

Compatibility certification request for Hibernate Validator for BV 3.0.0

Compatibility certification request for Hibernate Validator for Validation 3.1.0

  • Organization Name ("Organization") and, if applicable, URL:

    Red Hat, https://www.jboss.org/

  • Product Name, Version and download URL (if applicable):

    Hibernate Validator, 8.0.1.Final, http://hibernate.org/validator/releases/8.0/

  • Specification Name, Version and download URL:

    Jakarta Bean Validation 3.1, https://jakarta.ee/specifications/bean-validation/3.1/

  • TCK Version, digital SHA-256 fingerprint and download URL:

    3.1.0, 32d008ee99e28325ef92761891112b7177ad2b6c31881216baa0f3729a8eda03
    https://download.eclipse.org/ee4j/bean-validation/3.1/validation-tck-dist-3.1.0.zip

  • Public URL of TCK Results Summary:

    https://github.com/jakartaredhat/beanvalidation-tck/wiki/Jakarta-Bean-Validation-3.1-TCK-Results
    Includes both Java SE 17 and 21 runs

  • Java runtime used to run the implementation:

    openjdk version "21.0.2" 2024-01-16 LTS
    OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13-LTS)
    OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13-LTS, mixed mode, sharing)

    openjdk version "17.0.10" 2024-01-16
    OpenJDK Runtime Environment Temurin-17.0.10+7 (build 17.0.10+7)
    OpenJDK 64-Bit Server VM Temurin-17.0.10+7 (build 17.0.10+7, mixed mode, sharing)

  • Summary of the information for the certification environment, operating system, cloud, ...:

    EF CI environment
    Linux basic-497lf 6.2.9-300.fc38.x86_64 SMP PREEMPT_DYNAMIC Thu Mar 30 22:32:58 UTC 2023 x86_64 GNU/Linux

  • By checking this box I acknowledge that the Organization I represent accepts the terms of the EFTL.

  • By checking this box I attest that all TCK requirements have been met, including any compatibility rules.

We need to modernize the specification doc build

The current spec document build is based on ant and the asciidoctor ant plugin. The ant plugin has not been updated in 5 years, and we are using an even older version of it. Even just updating to the 5 year old version of the ant plugin causes the generation to fail because the custom Hibernate tree/block asciidoc plugins are apparently incompatible with that version.

We should look at switching the generation to the maven plugin, but this will probably still require updates to the hibernate-asciidoctor-extensions.

Update CONTRIBUTING.md for Specification Project's repositories

Create/Update CONTRIBUTING files

Per input from the Eclipse EMO, each Specification Project needs to ensure that a CONTRIBUTING.md or CONTRIBUTING.adoc file exists in each specification-related repository maintained by Specification Projects.
In addition, the CONTRIBUTING.md or CONTRIBUTING.adoc file needs to include the following text:

## Eclipse Development Process

This Eclipse Foundation open project is governed by the Eclipse Foundation
Development Process and operates under the terms of the Eclipse IP Policy.

The Jakarta EE Specification Committee has adopted the Jakarta EE Specification
Process (JESP) in accordance with the Eclipse Foundation Specification Process
v1.2 (EFSP) to ensure that the specification process is complied with by all
Jakarta EE specification projects.

* https://eclipse.org/projects/dev_process
* https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf
* https://jakarta.ee/about/jesp/
* https://www.eclipse.org/legal/efsp_non_assert.php

Please do this at your earliest convenience.
Thank you!

-- EE4J PMC ([email protected])

Array elements can't be validated

Hi,

I'm trying to validate each element of an array, rather than the size of said array.

According to jls§9.7.4, annotations can be used on arrays like this:

Type annotations can apply to an array type or any component type thereof (§10.1). For example, assuming that A, B, and C are annotation interfaces meta-annotated with @Target(ElementType.TYPE_USE), then given the field declaration:

@C int @A [] @B [] f;

@A applies to the array type int[][], @B applies to its component type int[], and @C applies to the element type int. For more examples, see §10.2.

So essentially, these two declarations are "equivalent" according to the JLS:

private @NotEmpty List<@Size(min=1,max=3) String> myList;

private @Size(min=1,max=3) String @NotEmpty[] myArray;

It seems to me that currently it is only possible to validate the length of an array, but not validate each element inside this array. I also have the impression that the current behavior is different from what is described in the above JLS excerpt, and also different from how Lists are validated:

  • @Size(min = 1, max = 3) String[] validates the array length whereas it should in theory validate each String element
  • String @Size(min = 1, max = 3)[] should validate the array length but it does nothing at the moment.

See this sample project for JUnit test cases to reproduce the problem: https://github.com/bjansen/arrays-validation

Add "provider" attribute to @GroupSequence inspired by the Hibernate's @GroupSequenceProvider

At the moment there is no mechanism to define the group sequence validation at runtime. Hibernate Validator has its own mechanism, through @GroupSequenceProvider annotation and DefaultGroupSequenceProvider interface.

Inspired by the Hibernate's solution, my suggestion is to add the attribute "provider" to the @GroupSequence annotation which expects a reference to a class that implements the interface "GroupSequenceProvider".

More info: Hibernate Validator docs.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.