NodeID - a way to identify Morphir IR nodes

[bekand]

NodeID - a way to identify Morphir IR nodes

Introduction

Several requirements of the Decorations feature require us to have the ability to refer to specific nodes inside of a Morphir IR. To that end, the following proposal describes "NodeID", a way to refer to Morphir IR nodes in a way that resembles URLs.

Structure

A NodeID can have two slightly different structures depending on if we are refering to modules or definitions (types/values).

• When refefering to modules:
  "<Package>:<Module>"
• When refering to definitions: "<Package>:<Module>:<localName><.type or .value>#<nodePath>", where nodePath is optional

Examples of valid NodeIDs:

• "Morphir.Reference.Model:BooksAndRecords"
• "Morphir.Reference.Model:BooksAndRecords:deal.type"
• "Morphir.Reference.Model:BooksAndRecords:deal.value#1"

Referring to modules

We can refer to modules by their Qualified Name. Types and Values are differentiated with a .type or .value suffix on the last Name before the NodePath part. If no such suffix is present, the ID in question must refer to a module
For example:
"Morphir.Reference.Model:BooksAndRecords"
refers to the Books and Records module inside the Morphir.Reference.Model package.

Referring to top level types and values

We can refer to Morphir types and values inside modules with their Fully Qualified Name, suffixed with a .type or .value tag. This is necessary, because it is valid (and not unusual) for a Morphir module to contain both a type and a value under the same name (e.g.: A Number module containing a type called Int and a function called int).

"Some.Package:SomeModule:foo.type" would refer to the Foo type inside the SomeModule module inside the Some.Package package. while "Some.Package:SomeModule:foo.value" would refer to the foo function inside the SomeModule module inside the Some.Package package.

NodePath - Referring to types and values inside other types and values

We can refer to nodes inside top level type or value node with a node path.

A node path is composed of node path steps, which can be either a string when referring to something by name (for example a record field, or function arguments), or an integer, when referring to something by it's position (for example in the case of lists, tuples, pattern match cases, but can also be used for function arguments)

For example if, you have a type defined as:

type alias Foo =
 { tupleField : (Int, String)
  , name : String
 }

then a NodeID with the following node path (starting with #)

"Morphir.Package:FooModule:foo.type#tuplefield:1"

would refer to the String member of the tupleField field of the Foo type.

The general rule of thumb would be that when things have a well defined name (e.g.: record fields or arguments of a function definition) they would be referred to with a string, and anything else with an index.

Frequent usecases

1. Record fields: As seen in the above example, record fields are identified by a string. A nodeID ending with ...foo#fieldName refers to the fieldName field of the foo record
2. Function types: If a type named someType is declared as
   a -> b -> c -> d you will be able to refer to a as someType.type#args:0, c as someType.type#args:2 and d as someType.type#output
3. Function definitions: If a function is defined as

add3 : Int -> Int -> Int -> Int
add3 a b c =
...

you will be able to refer to the arguments by index (as seen in the previous case), or by specifying the argument name, like add3.value#args:b

[AttilaMihaly]

As we discussed on our community call yesterday we want to slightly change this and move the type/value flag as a suffix of the local name. This has a few benefits:

• Modules no longer need to be specifically flagged because not having a local name part clearly identifies it as a module path.
• Languages that only support types (TypeSpec, OpenAPI, JSON Schema, ...) won't have to deal with an extra prefix that is not useful for them.
• Tools that use tree navigation will integrate better because the path will align with tree traversal of package/module/local name.

So the examples would change as such:

• module:Morphir.Reference.Model:BooksAndRecords -> Morphir.Reference.Model:BooksAndRecords
• type:Morphir.Reference.Model:BooksAndRecords:deal -> Morphir.Reference.Model:BooksAndRecords:deal.type
• value:Morphir.Reference.Model:BooksAndRecords:deal#1 -> Morphir.Reference.Model:BooksAndRecords:deal.value#1

[AttilaMihaly]

There was another slight adjustment proposed on our regular community call: when there is no specific .type or .value suffix then the path should be interpreted as a type name. This is safe to do because it has no chance of colliding with module names since those won't contain a local name part. So here is the updated mapping:

• module:Morphir.Reference.Model:BooksAndRecords -> Morphir.Reference.Model:BooksAndRecords
• type:Morphir.Reference.Model:BooksAndRecords:deal -> Morphir.Reference.Model:BooksAndRecords:deal or Morphir.Reference.Model:BooksAndRecords:deal.type
• value:Morphir.Reference.Model:BooksAndRecords:deal#1 -> Morphir.Reference.Model:BooksAndRecords:deal.value#1

[DamianReeves]

@AttilaMihaly , @stephengoldbaum , @bekand where did we finally land on this. I'm looking at the morphir-elm and the implementation of NodeID does not match what is described in the NodePath section of this idea. It doesn't seem / is being used as the path separator character after the # and instead it is :. If this is correct could we get an update on the target state on this thread, with some examples please?

I have a use-case for NodeID as we implement our interpreter and data model abstractions , and also want to start the implementation of decorations for morphir-scala .

See:

https://github.com/finos/morphir-elm/blob/8f34ae561040f8bceb26ba249f4da798b0994f81/src/Morphir/IR/NodeId.elm#L171-L189

[bekand]

Hi Damian. You are correct, the implementation has drifted from the original proposal after some internal discussion. I updated the document above, to reflect these changes.
So a valid NodeID and NodePath to a seats field in an Pickup record type in a Models module in a Cars package would be Cars:Models:pickup.type#seats.
Other than the separators (which I have updated) the one big difference between the target state described above and the current implementation is when it comes to function types and values, due to how they are stored in a curried form in Morphir.
For example when it comes to a function that looks like a -> b -> c you would have to think about it as a -> f, where f is another function with a b -> c signature. This means that a NodePath to a would be #0 while one to b would be #1:0 and the one to c would be #1:1.
We had talks about changing how this works, as it might be confusing and clunky to use, and can result in weirdly long Node Paths, but haven't settled on a solution yet, as we are not using NodePath yet internally, nor have we had any other project use it as far as I know.
So this is an area where the current implementation needs work to be aligned with the proposal.

[DamianReeves]

Thanks for the update and explanation for context.