Definition versions

Definitions are dynamic structures which are easily modified, e.g. fields are added, removed or modified. This means, that when a document is created, the next one isn’t necessarily based on the same structure. To ensure compatibility with older versions and to prevent data being inaccessible, a versioning system has been provided.

The modifiable structure is persisted using a DynamicDefinitionVersion, which results in a version for every change made to the defined structure. Documents then refer to a specific definition version and as such can have a different structure whilst having the same definition.

Versions have two important concepts:

  • Every version of the same definition has a unique version name

  • Versions can be published. Once a version is published, it will automatically be linked from the definition as the latest version.

Default interface

The default interface uses the versioning strategy when creating and modifying definitions. As soon as changes are made to a definition, a new version will be created. The naming of these versions is entirely user-definable, but for ease of use, a default naming strategy has been provided that uses number increments e.g. 1, 2 …​

Before the changes will actually be available for use, the version should be published. Once a version is published, it is no longer modifiable and it will automatically be used when creating new documents for the corresponding definition.

Creating a version in code

Creating a definition requires the following steps:

  • A structure defined in yaml or json

  • Creating a raw definition based on the provided structure

  • Creating a definition version for a definition with the aforementioned raw definition

First off, we define the structure for the definition and create a raw definition. Creating a raw definition is necessary to confirm that the the structure can be parsed to a definition of the corresponding type.

Example creating a raw definition
@Autowired
private RawDefinitionService rawDefinitionService;
@Autowired
private ObjectMapper objectMapper;

Yaml yaml = new Yaml();
Object raw = yaml.load( new ClassPathResource( path ).getInputStream() ); (1)
String convertedJson = objectMapper.writeValueAsString( raw ); (1)

RawDefinition rawDefinition = rawDefinitionService.readRawDefinition( convertedJson, typeName ); (2)
1 If your definition structure is provided in the yaml format, it must first be converted to a json format. In this example, the structure is available in a file on the classpath.
2 A RawDefinition object is created based on a json structure and a specific definition type. Before a type can be used, it must be registered on the DynamicDefinitionTypeConfigurationRegistry.

If the raw definition is successfully created, the document structure is of a parsable format. Now we can create a new version, using the content of the raw definition.

Example creating a definition version using a definition and a version
@Autowired
private RawDefinitionService rawDefinitionService;
@Autowired
private ynamicDefinitionVersionRepository definitionVersionRepository;

DynamicDefinitionVersion definitionVersion = new DynamicDefinitionVersion();
definitionVersion.setDefinition( definition ); (1)
definitionVersion.setPublished( true ); (2)
definitionVersion.setVersion( "alpha-3.1.3" ); (3)
definitionVersion.setDefinitionContent( rawDefinitionService.writeDefinition( rawDefinition ) ); (4)
definitionVersion = definitionVersionRepository.save( definitionVersion );
1 A version is always linked to a specific definition.
2 Publishing a version will ensure that the version is linked as the latest version of the definition.
3 A version name must be specified. There is no default naming strategy when creating definitions in code.
4 The raw definition that has been created is converted back to json and then added.

Using a version in code

Documents are mostly created and modified through the DynamicDocumentWorkspace. When a document (or document version) is loaded into a workspace, the linked definition version is automatically fetched and loaded in for further use.

Workspaces can also be created with a specific definition version or a definition. If no specific definition version is specified, the latest version will be used in the workspace. Documents can then be created for that definition (version).

See the javadoc for more information on which methods can be used.