Index types
An IndexType describes a business object that is searchable in OpenSearch. It defines the mapping
(field names, types), the versioning scheme, and the alias names used for reading and writing.
Index types are defined in separate Maven artifacts and consumed as dependencies by service instances.
Naming conventions
| Concept | Pattern | Regex | Examples |
|---|---|---|---|
| System | Name of the business application | [A-Z][a-z0-9]+ | JME, WVS, Precious |
| BusinessObject | Type of the business object | [A-Z][a-z0-9]+ | DecreeDocument, Registration |
| MajorVersion | Breaking schema version | Integer | 1, 2 |
| MinorVersion | Backwards-compatible schema version | Integer | 0, 1 |
| Sequence | Rollover partition number | 6-digit zero-padded integer | 000001, 000002 |
Physical index
A physical OpenSearch index holds the documents for one IndexTypeVersion and one rollover
partition. The write alias always points to the current write index; when ISM rollover fires, the
alias is atomically re-pointed to the new partition.
Pattern: <System>_<BusinessObject>_v<MajorVersion>-<Seq>
| Example |
|---|
jme_decree_document_v1-000001 |
www_declaration_v2-000001 |
precious_registration_v1-000002 |
IndexWriteAlias
The write alias points to the currently writable partition for a specific major version. All document writes target this alias rather than a physical index, so rollover is transparent to the service.
Pattern: <System>_<BusinessObject>_v<MajorVersion>_write
| Example |
|---|
jme_decree_document_v1_write |
www_declaration_v2_write |
precious_registration_v1_write |
IndexReadAlias
The read alias points to all partitions of an IndexType across all major versions. Use this alias
for search queries so results span the entire history.
Pattern: <System>_<BusinessObject>_read
| Example |
|---|
jme_decree_document_read |
www_declaration_read |
precious_registration_read |
IndexType artifact
An IndexType artifact is generated by the
jeap-opensearch-index-type-registry-maven-plugin
from a mapping definition file. The artifact provides:
- An
IndexTypeDescriptorSpring bean that registers the index type with the service - A generated Java data class with
@JsonProperty("snake_case_name")annotations for every field - The OpenSearch mapping JSON embedded in the artifact
Service instances consume an index type artifact as a Maven dependency. The IndexTypeDescriptor is
auto-discovered via Spring bean scanning and registered with the IndexTypeRepository at startup.
Field naming
All field names in the data.properties section of an IndexType mapping must be snake_case. The
registry Maven plugin enforces this at build time — any camelCase field name fails the build.
The generated data class carries @JsonProperty annotations on every field so that Jackson writes
the correct snake_case names to OpenSearch, regardless of how the SearchItem provider serialised the
data on the wire.
Schema versioning
Each IndexType has a MajorVersion (breaking change) and a MinorVersion (backwards-compatible
change). The minor version is stored in the _meta.schema_version field of the OpenSearch mapping
and compared at startup — if it differs the service pushes an updated mapping to the current write
index. A major version bump requires a new index (new major version pattern and new write alias).