Can we use more consistent terminology for entity attribute/field/property?

[njr-11]

Jakarta Data is currently very inconsistent in how it refers to entity attributes/fields/properties. Or sometimes persistent fields. Or sometimes (persistent) fields and properties. By using different terms, there is some concern that users, especially newer users who are often the ones who most need to rely on the documentation, will believe they are referring to different things.

Whether or not we go back and try to be more consistent with what we have already done is one matter, but I would like to at least figure out what is preferred going forward before we starting adding documentation for v1.1 and beyond.

I did some quick searches across the Javadoc and spec documents to approximately figure out what the current usage is:

117 occurrences of attribute: 108 in Javadoc. 9 in spec doc.
94 occurrences of property: 59 in Javadoc. 35 is spec doc.
220 occurrences of field: 98 in Javadoc. 122 in spec doc.
11 occurrences of field or property and similar: 8 in Javadoc. 3 in spec doc.
52 occurrences of persistent field: 19 in Javadoc. 43 in spec doc.

A subset of this usage is encoded into the API and cannot change even if we wanted to:

• Attribute is used in class names Attribute, SortableAttribute, TextAttribute within the static metamodel (and also in the *Record implementation classes, which are lesser concern because users should not look at those)

• property is a record component name of the Sort API.

And we just recently added for v1.1 (so it could still be changed if we want),

• field is a record component name of the BasicRestriction API.

[gavinking]

I tried for years to convince the world to use "attribute" here, but finally I gave up and now I mostly just recite "field or property" or "fields and properties".

[otaviojava]

I like attribute as well.

[otaviojava]

In today's meeting we agreed with attribute