Skip to content
logoBack to home screen

Adding Metadata

You can add metadata to models in the following ways:

  • via the graphical metadata editor
  • via the ModelMetaDataEditor interface in an initializer
  • via annotations (e.g. @Mandatory)

In general, annotations are more convenient for a coder, but they only provide a limited subset of the full modelling capabilities, while the metadata editor and the cartridge initializer both have access to the full potential of modelling.

Your choice of the preferred method of adding metadata is, however, not that simple. It is important to understand where the metadata is applied before to actually apply it.

Metadata and Model Types

There are a lot of factors that influence decision of where to place certain metadata. The semantical differentiation in skeleton and enriching models is a good starting point for you to decide.

We distinguish two basic model types: skeleton models and enriching models.

Skeleton Model

A skeleton model defines custom types (GmEntityType, GmEnumType) and may depend on other models. If no other dependency is needed, it needs to at least depend on the root-model. A skeleton model must not declare type overrides.

For more information about overrides, see Metamodel.

If other dependencies are needed, each dependency is a skeleton model as well.

Currently a skeleton model is represented via:

  • Java interface class files
  • Java enum class files
  • Java annotations used in those class files

Metadata can be applied on entity types (and related properties), enum types (and related constants) and property overrides reachable by GmMetaModel.types. Essentially this means that a skeleton model should only contain annotatable essential metadata.

Enriching Model

An enriching model on the other hand does not declare custom types (empty types collection). It may depend on other models which can be either a skeleton as well as another enriching model.

An enriching model may declare type overrides and those can declare any type of metadata on it. Unlike the skeleton model, an enriching model is not restricted to annotatable essential meta data.

Enriching models are represented by incremental changes to the cortex - ManipulationPriming in form of .man files (e.g. changes done via the metadata editor) or code primings in the form of initializers (e.g. Java).

An enriching model therefore enriches your skeleton model with those data that would get lost in the asset roundtrip (creating an asset, publishing it in an asset store, depending on it) on a skeleton model otherwise as, for example, custom meta data is not represented as a Java annotation and therefore would not be present in a deployed asset .jar file.

In a runtime environment as well as in current setups, this clear separation is not always into place. There, skeleton models hold non-essential metadata as well. This should be avoided as it may cause information loss if not handled properly.

Consider the following when adding metadata:

  • What is the real skeleton of my model, so which metadata should be brought to anybody who depends on my model?
  • Is this metadata annotatable essential metadata, can it stand the whole roundtrip (creating an asset, publishing it in an asset store, depending on it)?
  • Which kind of metadata is use-case driven?

Adding Metadata via ModelMetaDataEditor

The ModelMetaDataEditor is an interface used for adding metadata to GmMetaModel instances. It takes care of navigation through the underlying GmMetaModel hierarchies and creating the appropriate model element overrides.

For more information, see BasicModelMetaDataEditor.

A common place of adding metadata programmatically are initializers, which add information to a collaborative SMOOD persistence. As models and their metadata reside in the cortex access, a respective session to it is required.

In the example below, we are adding an instance of the Confidential metadata defined in the initializer Wire space.

For more information about wire spaces, see Wire in Detail.

The declaration of the Confidential metadata in the Wire space may look as follows:

@Managed
@Override
public MetaData confidential() {
	Confidential md = create(Confidential.T);
	return md;
}

Note that metadata might already exist and therefore just be referenced via a Wire Contract.

For more information about the Confidential metadata, see Confidential.

To add the metadata:

  1. Create a new instance of BasicModelMetaDataEditor and provide the model you want to add the metadata to as the argument:
ModelMetaDataEditor editor = new BasicModelMetaDataEditor(modelYouWantToAddMetadataTo);
  1. Use the proper API method to add the metadata to the entity or property. In this example, we're adding metadata to the PlatformAssetExtensionRequest entity type:
   editor.onEntityType(PlatformAssetExtensionRequest.T).addMetaData(initializer.confidential());

If you have the Demo cartridge in your setup, inspect the DemoCartridgeInitializer class to see how metadata is added in a real-world scenario.