Schema definition and entities

Schema providers

The schema defines the structure of the data you want to save. It is possible to define the schema using different schema providers, there are two providers included in the core library. You can also define your own provider, see Extend Quinimbus Persistence.

JSON Schema provider

You can define the schema using JSON files. This is a way to define the structure without writing any Java code, but you will lose some comfort features while writing your business logic.

Record Schema provider

If you define your data model as Java record class you can use annotations to add the needed meta data for the schema definition. This way you can also directly use these classes as model classes in your own code.

Schema structure

The structure of a schema is simple. You have to define a unique ID for the schema, additionally a version and the list of entity types is needed.

JSON

{
  "id": "schema-id",
  "version": 1,
  "entityTypes": {
    //...
  }
}

Record

// This annotation has to be included in any @Entity annotation of the schema
@Schema(id = "schema-id", version = 1)

Register your schema

If you're not using any integration like CDI you can import the schema manually in the PersistenceContext.

var context = ServiceLoader.load(PersistenceContext.class).findFirst().orElseThrow();

// if you have some preconfigured provider instance
var schema1 = context.importSchema(provider);

// if you have some provider to be configured by a ConfigNode
var schema2 = context.importSchema(provider, configNode);

// to load the schema from JSON to be read from a Reader
var schema3 = context.importSchemaFromSingleJson(reader);

// to load the schema from one or multiple record classes
var schema4 = context.importRecordSchema(DataRecord1.class, DataRecord2.class);

Entity Types

A schema contains one or more entity types. Each entity type has an unique ID and several fields. One of the fields has to be the key of the entity type.

Fields

Each field needs to have a unique identifier. Also you have to define the type and optionally the structure of the field.

JSON

{
  "id": "schema-id",
  "version": 1,
  "entityTypes": {
    "entityIdentifier": {
      "properties": {
        "simplePropertyIdentifier": {
          "type": "PROPERTYTYPE"
        },
        "listPropertyIdentifier": {
          "type": "PROPERTYTYPE",
          "structure": "LIST"
        }
      }
    }
  }
}

Record

@Entity(schema = @Schema(id = "schema-id", version = 1))
public record EntityIdentifier(
    PropertyType simplePropertyIdentifier,
    List<PropertyType> listPropertyIdentifier
){}

Property Types

The following table shows the supported property types. The record schema provider will use some mapping for the types, in the JSON provider the type will be provided directly.

Property type	Description	Json type	Record field mapping
Boolean	Boolean value	BOOLEAN	Boolean, boolean
Embedded	Structured object	EMBEDDED	? extends Record
Enum	Enum value	ENUM	? extends Enum
Integer	Integer value	INTEGER	Long, long, Integer, int, Short, short, Byte, byte
LocalDate	Local date value	LOCALDATE	LocalDate
String	Simple text values	STRING	String
Timestamp	Timestamp value	TIMESTAMP	Instant

Enum property type

The enum property type needs a configuration. The allowed values have to be definied. Using the record schema provider the values of the enum type of the field will be used automatically, using JSON you have to define them as follows.

  "type": {
    "ENUM": ["A", "B", "C"]
  }

Embedded property type

You can nest entity structures using the embedded property type. The definition of such a structure is completely different in JSON and record definition.

JSON

  "type": {
    "EMBEDDED": {
      "properties": {
        // define the properties of the nested structure in the same way
        // as in the entity definition
      }
    }
  }

Record

// You can use any record type as nested property type.
// The only dependency is to add one annotation to the embedded record type.
@Embeddable
public record EmbeddedType(/*...*/){}

Property Structures

The structure of a property is defined independently from the type. There are three possible structures at the moment

Structure type	Json type	Record field mapping
Single property	SINGLE	Type
Ordered list property	LIST	List<Type>
Unordered set of unique property values	SET	Set<Type>

If you use a generic type structure for records you have to define the type in a dublicate way because of the type erasure. See the following example:

@EntityField(type = Type.class) List<Type> listProperty

Entity IDs

WARNING

This documentation is not complete yet, please come back soon.