Why does Maven want to use javax.persistence instead of the alternative hibernate version

I have some code that uses:

import javax.persistence.*;

I have the following dependencies in pom.xml:

<dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-core</artifactId>
            <version>5.4.15.Final</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate.javax.persistence</groupId>
            <artifactId>hibernate-jpa-2.1-api</artifactId>
            <version>1.0.2.Final</version>
        </dependency>

I can compile ok using "mvn compile" but when I try to "mvn package" I get the following error:

[WARNING] Used undeclared dependencies found:
[WARNING]    javax.persistence:javax.persistence-api:jar:2.2:compile
[WARNING] Unused declared dependencies found:
[WARNING]    org.hibernate.javax.persistence:hibernate-jpa-2.1-api:jar:1.0.2.Final:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------

I checked the jar from hibernate-jpa-2.1-api and it does contain the javax.persistence.* classes.

So why won't Maven accept that this is the jar to use and insists it wants the javax.persistence-api instead?

If I try to switch to the javax.persistence:javax.persistence-api:jar:2.2 instead of the hibernate one I get a lot of errors from 'mvn package' that look like this:

[WARNING] Found duplicate (but equal) classes in [jakarta.xml.bind:jakarta.xml.bind-api:2.3.3, javax.xml.bind:jaxb-api:2.3.1]:
[WARNING]   javax.xml.bind.DatatypeConverterInterface
[WARNING]   javax.xml.bind.Element
[WARNING]   javax.xml.bind.JAXBContextFactory
[WARNING]   javax.xml.bind.Marshaller
[WARNING]   javax.xml.bind.NotIdentifiableEvent
[WARNING]   javax.xml.bind.ParseConversionEvent
[WARNING]   javax.xml.bind.PrintConversionEvent
[WARNING]   javax.xml.bind.Unmarshaller
[WARNING]   javax.xml.bind.UnmarshallerHandler
[WARNING]   javax.xml.bind.ValidationEvent
[WARNING]   javax.xml.bind.ValidationEventHandler
[WARNING]   javax.xml.bind.ValidationEventLocator
[WARNING]   javax.xml.bind.Validator
[WARNING]   javax.xml.bind.annotation.DomHandler
[WARNING]   javax.xml.bind.annotation.XmlAccessorOrder
[WARNING]   javax.xml.bind.annotation.XmlAccessorType
[WARNING]   javax.xml.bind.annotation.XmlAnyAttribute
[WARNING]   javax.xml.bind.annotation.XmlAnyElement
[WARNING]   javax.xml.bind.annotation.XmlAttachmentRef
[WARNING]   javax.xml.bind.annotation.XmlAttribute
[WARNING]   javax.xml.bind.annotation.XmlElement
[WARNING]   javax.xml.bind.annotation.XmlElementDecl
[WARNING]   javax.xml.bind.annotation.XmlElementRef
[WARNING]   javax.xml.bind.annotation.XmlElementRefs
[WARNING]   javax.xml.bind.annotation.XmlElementWrapper
<...lots more lines like this>

Any ideas what is going wrong?

It's really quite simple: org.hibernate:hibernate-core:5.4.15.Final depends on javax.persistence.* classes from javax.persistence:javax.persistence-api:2.2 (that's the dependency declared in its own POM) and so, by including hibernate-core, you get an additional, transitive dependency javax.persistence-api pulled in. This is why you're getting the 'Used undeclared dependencies found' warning.

For the very same reason, org.hibernate.javax.persistence:hibernate-jpa-2.1-api:1.0.2.Final is not used. Note that Maven does not have a way of knowing hibernate-jpa-2.1-api and javax.persistence-api are supposed to be interchangeable.

If, for some strange reason, you want to force hibernate-jpa-2.1-api to be used instead, you need to explicitly exclude javax.persistence-api as a transitive dependency like so:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>5.4.15.Final</version>
    <exclusions>
        <exclusion>
            <groupId>javax.persistence</groupId>
            <artifactId>javax.persistence-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

1. <version>1.0.2.Final</version> - This declaration says : allow any version, but prefer 1.0.2.FINAL.
   If you want to specify exact version declare it as <version>[1.0.2.Final]</version>

2. Generally while resolving a transitive dependency (or on conflict, which is not the case in this case) Maven will choose the nearest dependency. In this case javax.persistence:javax.persistence-api:jar:2.2:compile is closer to org.hibernate:hibernate-core:jar:5.4.15.Final:compile.

   mvn dependency:tree
    [INFO] Scanning for projects...
    [INFO] 
    [INFO] -----------------------< org.example:so-answers >-----------------------
    [INFO] Building so-answers 1.0-SNAPSHOT
    [INFO] --------------------------------[ jar ]---------------------------------
    [INFO] 
    [INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ so-answers ---
    [INFO] org.example:so-answers:jar:1.0-SNAPSHOT
    [INFO] +- org.hibernate:hibernate-core:jar:5.4.15.Final:compile
    [INFO] |  +- org.jboss.logging:jboss-logging:jar:3.3.2.Final:compile
    [INFO] |  +- javax.persistence:javax.persistence-api:jar:2.2:compile
    [INFO] |  +- org.javassist:javassist:jar:3.24.0-GA:compile
    [INFO] |  +- net.bytebuddy:byte-buddy:jar:1.10.10:compile
    [INFO] |  +- antlr:antlr:jar:2.7.7:compile
    [INFO] |  +- org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec:jar:1.1.1.Final:compile
    [INFO] |  +- org.jboss:jandex:jar:2.1.3.Final:compile
    [INFO] |  +- com.fasterxml:classmate:jar:1.5.1:compile
    [INFO] |  +- javax.activation:javax.activation-api:jar:1.2.0:compile
    [INFO] |  +- org.dom4j:dom4j:jar:2.1.3:compile
    [INFO] |  +- org.hibernate.common:hibernate-commons-annotations:jar:5.1.0.Final:compile
    [INFO] |  +- javax.xml.bind:jaxb-api:jar:2.3.1:compile
    [INFO] |  \- org.glassfish.jaxb:jaxb-runtime:jar:2.3.1:compile
    [INFO] |     +- org.glassfish.jaxb:txw2:jar:2.3.1:compile
    [INFO] |     +- com.sun.istack:istack-commons-runtime:jar:3.0.7:compile
    [INFO] |     +- org.jvnet.staxex:stax-ex:jar:1.8:compile
    [INFO] |     \- com.sun.xml.fastinfoset:FastInfoset:jar:1.2.15:compile
    [INFO] \- org.hibernate.javax.persistence:hibernate-jpa-2.1-api:jar:1.0.2.Final:compile
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 0.790 s
    [INFO] Finished at: 2020-09-26T10:02:50-04:00
    [INFO] ------------------------------------------------------------------------
   

Let's add exclusion to influence resolution.

<dependencies>
		<dependency>
			<groupId>org.hibernate</groupId>
			<artifactId>hibernate-core</artifactId>
			<version>5.4.15.Final</version>
			<exclusions>
				<exclusion>
					<groupId>javax.persistence</groupId>
					<artifactId>javax.persistence-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>org.hibernate.javax.persistence</groupId>
			<artifactId>hibernate-jpa-2.1-api</artifactId>
			<version>1.0.2.Final</version>
		</dependency>
	</dependencies>

And then check dependency tree again

  mvn dependency:tree
    [INFO] Scanning for projects...
    [INFO] 
    [INFO] -----------------------< org.example:so-answers >-----------------------
    [INFO] Building so-answers 1.0-SNAPSHOT
    [INFO] --------------------------------[ jar ]---------------------------------
    [INFO] 
    [INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ so-answers ---
    [INFO] org.example:so-answers:jar:1.0-SNAPSHOT
    [INFO] +- org.hibernate:hibernate-core:jar:5.4.15.Final:compile
    [INFO] |  +- org.jboss.logging:jboss-logging:jar:3.3.2.Final:compile
    [INFO] |  +- org.javassist:javassist:jar:3.24.0-GA:compile
    [INFO] |  +- net.bytebuddy:byte-buddy:jar:1.10.10:compile
    [INFO] |  +- antlr:antlr:jar:2.7.7:compile
    [INFO] |  +- org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec:jar:1.1.1.Final:compile
    [INFO] |  +- org.jboss:jandex:jar:2.1.3.Final:compile
    [INFO] |  +- com.fasterxml:classmate:jar:1.5.1:compile
    [INFO] |  +- javax.activation:javax.activation-api:jar:1.2.0:compile
    [INFO] |  +- org.dom4j:dom4j:jar:2.1.3:compile
    [INFO] |  +- org.hibernate.common:hibernate-commons-annotations:jar:5.1.0.Final:compile
    [INFO] |  +- javax.xml.bind:jaxb-api:jar:2.3.1:compile
    [INFO] |  \- org.glassfish.jaxb:jaxb-runtime:jar:2.3.1:compile
    [INFO] |     +- org.glassfish.jaxb:txw2:jar:2.3.1:compile
    [INFO] |     +- com.sun.istack:istack-commons-runtime:jar:3.0.7:compile
    [INFO] |     +- org.jvnet.staxex:stax-ex:jar:1.8:compile
    [INFO] |     \- com.sun.xml.fastinfoset:FastInfoset:jar:1.2.15:compile
    [INFO] \- org.hibernate.javax.persistence:hibernate-jpa-2.1-api:jar:1.0.2.Final:compile
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 0.927 s
    [INFO] Finished at: 2020-09-26T10:23:46-04:00
    [INFO] ------------------------------------------------------------------------

Now [INFO] | +- javax.persistence:javax.persistence-api:jar:2.2:compile line is absent - effectively we asked Maven to use org.hibernate.javax.persistence:hibernate-jpa-2.1-api:jar:1.0.2.Final:compile.