Proposal on how to handle Decorations

[bekand]

Proposal on how to handle Decorations

Introduction

The Morphir IR contains all the domain models and business logic that we defined in our model, but sometimes
we want to add more information that can not be captured in the language.

The Morphir project has had many requirements for the ability to annotate specific items in a Morphir model with information beyond that provided by the IR. Many languages feature such a capability through mechanisms like annotations or decorations. To start we have collected the following features from the various requests:

User stories

• As a Morphir backend developer:
  1. I would like to annotate certain Morphir constructs with structured extra information as a way to provide my backend processor with information that isn't available in the IR.
  2. I would like a standard way to retrieve relevant decoration values so that I am insulated from the underlying decoration implementation. This should include the ability to retrieve all decoration values for a given item, and the ability to find all items associated with a particular decoration type.
  3. I would like a process to add my decoration requirements to the Morphir tooling.
• As a Morphir author:
  1. I would like a way to choose what backends/decorations are used in my workspace.
  2. I would like to know the structure of the decorations required by the backends that I'm using.
  3. I would like a way to edit the decoration values for my Morphir app in order to use my desired backend tools.
  4. I would like a way to edit the decoration values for items in imported Morphir libraries in order to comply with backend tools requirements.
  5. I would like my decoration values to be packaged and distributed along with my Morphir IR.

What gets decorated?

Our current plan is to decorate Morphir nodes below the package level.

What is a node?

Nodes inside a Morphir IR can be packages, modules, top level types or values inside those modules, or types and values inside other types and values. (Think fields of a record type, n^th element of a tuple type, or an if statement inside a function.)

How do we define a decoration?

Creating a new decoration would require the author to create or have access to a Morphir package with an IR describing the shape of the decoration.

How do we add and edit Decorations?

Creating a new decoration would require the author to :

1. create or have access to a decoration package describing the shape of the decoration, and
2. configure it in the main morphir.json of the project.

After configuration, we would be able to start decorating our Morphir model using the Morphir Web.

How do we store Decorations?

We would store Decorations in independent ("sidecar") JSON files with a specific key-value pair format.

How do we access Decorations from our backend tools?

We would define three APIs:

1. one to return every decoration for a given Morphir IR node (specified by a NodeID. See the section "NodeID - a way to identify Morphir IR nodes" for details)
2. one to return the list of nodes decorated with a given decoration.
3. one to return the full IR decorated (as attributes) with the specified set of decorations

How are Decorations distributed?

Since a decoration is defined by a Morphir IR, the definitions themselves can be distributed as any other Morphir package.
At this time there is no package management solution for Morphir, but it's likely going to be an NPM based one so we can safely assume that decorations will be available in the local file-system in a specific directory.

As for the "sidecar" files, they would be packaged together with the model they are decorating, and they can be published the same way as a normal Morphir package.

How do we configure which Decorations are included in our workspace?

Different backends might require the same model to be decorated with a different set of decorations.

As a modeler

See the "How to set up Decorations for your Morphir project?" section.

As a developer

You would be able to specify a list of Morphir packages, which implicitly defines a set of available decorations (based on what decorations are included in those packages).

How to set up Decorations for your Morphir project?

As mentioned earlier in this document, the shape (type) of the decorations would be defined in a Morphir package, and the values stored using the standard JSON serialization format that all Morphir tools integrate with.

Now let's see how you would set them up. This can be done in a few easy steps:

• Create or find the Morphir package that describes the decoration
• Set up the decoration for your model
• Start adding decorations

Creating or finding the Morphir package that describes the decoration

The first thing you would need is a Morphir IR that describes the shape of the decoration. If you want to use an existing
decoration you just need to make sure you have access to the package containing it.

If you want to create your own decoration, you need to create and publish a Morphir package with an IR describing your decoration.
The type describing the decoration should look like

 type Decoration modules types values =
 Decoration modules types values

This way we would be able to specify different Decoration types for different kinds of nodes. If we don't want a specific decoration to be applicable to a certain kind of node, we could use Elm's unit () type to indicate that.
For example

 Decoration String () ()

would mean a decoration that is specified as String on modules, and not applicable to types or values.
Our tooling would look for this Decoration typedefinition as an entrypoint into a decoration IR.

Setting up the decoration for your model

Decorations can be configured in the morphir.json. The decorations field is a list of one or more decoration packages (either package URLs, or paths to local files)

{
    "name": "My.Package",
    "sourceDirectory": "src",
    "decorations":
	[
		"pkg:...", 
                "file:..."
	]    
}

Adding decorations

Once this is all set up, you would be able to use Morphir Web (DevelopApp) to start adding decorations on your model. First you need to run morphir-elm develop, and open a browser at the specified port on localhost. In the UI you would see a "Decorations" tab on the right after selecting a module, value or type. The tab should display all the decorations you specified with editors that allow you to add or modify values.

(The editors would be the same ones used in our Insight module, so you would get type specific editors where applicable, depending on the decoration types, with error messages, etc.)

Every edit would be saved automatically as you make changes in a JSON file.
If you open the file you should see something like this:

{
	"My.Package:Foo:types:bar": "...",
	"My.Package:Baz:values:bat": "..."
}

It's an object with NodeIDs that identify the part of the model that you put the decoration on, and decoration values that you specified in the UI.

It would also possible to edit this JSON file manually, or to use your own tools to generate and modify it, as long as the keys are valid NodeIDs, and the values are in accordance with the type specification of the decoration at hand.

Open question: Where would the storage file be located?

• If it can be user specified, we need to make sure it is published with the package.
• If not, we need to come up with a convention.

[AttilaMihaly]

While reading through the proposal I noticed that we use the term "decoration" both to talk about the shape/definition of a decoration and also the actual decorations assigned to Morphir IR nodes. Should we differentiate these and call them "decoration schema" and "decoration instance"? Or maybe different wording but something that differentiates them.

[stephengoldbaum]

Yes, it gets confusing otherwise. I like Decoration Schema.

[KindsonTheGenius]

The heading "How Do We Access Decorations from our Backend Tools" seems to describe how to access decorations from the Morphir Web tool
Consuming decorations from backend tools is discussed here Proposal on Backend Decoration Processing