Discussion on modeling modes in m30pm

[j-simmons-phd]

I have identified three modeling use cases for m30pm, and I want to discuss them here (as well as some terminology that would go along with them).

Use Cases (First Pass)

1. Define modeling language schemas (such as what we are about to do with m30ml)
2. Describe methodology that defines how to use new modeling language schemas, which would need to be modeled using some modeling language (for m30ml, we are planning to do this modeling in m30ml)
3. Use an existing modeling language (based on schema and description) to develop projects (oshw projects in dof methodology and related schema)

Use Cases Discussion

Collapsing Down to Two Use Cases

Use Case 1 is all about creating LinkML schemas, so this is very definitely its own use case. But, if we look at Use Case 2 and Use Case 3, both are about modeling with one of the schemas created in Use Case 1, so really they are alternate applications of a true second Use Case. Let's rename them Use Case 2.1 and Use Case 2.2 with a new Use Case 2.

1. Define modeling language schemas as LinkML schemas
2. Use defined modeling language schema to
   1. Describe methodology that defines how to use a modeling language schema
   2. Develop projects consistent with methodology and schema set

Modeling Modes

So, we have two distinct modeling modes consistent with the two main use cases.

1. LinkML Schema Mode
2. Modeling with a Specified Schema Mode

I recommend we keep things simple and limit m30pm to working in either mode 1 or mode 2.

Next I recommend we manage m30pm's mode by project (that is, a project is either set up to support mode 1 or mode 2, not both). For projects like m30ml that have both a schema component and methodology component, I think we can address this by use of sub-projects within a mono-repo.

I will also state that I believe there will be far more projects that are developed under Use Case 2, especially Use Case 2.2). And because of that, I would recommend that m30pm root projects (that is ones that are not a sub-project to a parent project, aka not managed under the packages/ folder in a project) are only allowed to be ones modeled using Mode 2. As a corollary, that would mean any projects developed in mode 1 would have to be sub-projects.

This would mean a project like m30ml would be organized something like this.

m30ml/
|-package.json 
|-.... # model content defining m30ml methodology, modeled in m30ml-schema
|-packages/
  |-m30ml-schema/
    |-package.json
    |-... # schema definition, possibly broken down into sub-schemas (different discussion), modeled in LinkML

Naming the Modeling Modes

It is important that we give definitive names to the modeling modes, as they will influence the naming conventions of m30ml projects and of m30pm command names. And, I think we have two options for naming the modeling modes.

Option 1

• Schema Mode
• Model Mode

This option has the benefit of aligning with LinkML terminology. But, it might be awkward for our user base since LinkML talks about modeling schemas. Note, I think we want to call the other mode Model Model given the primary language for this mode is m30ml (Mach 30 Modeling Language) and it would be deeply inconsistent to say we are doing something other than modeling when working with Mach 30 Modeling Language.

Option 2

• Definition Mode
• Model Mode

In this option, we lightly borrow the idea of definitions vs usages from SysML v2 and we reinforce the idea that you have to define how you will model before you can model. This is the option I prefer, and it would lead to changing the example above from m30ml-schema to m30ml-def.

What do you all think?

[capsulecorplab]

There's also a third option; the OML terminology of "vocabulary" and "description". Personally, I like the use of "Schema" compared to "Definition" or "Vocabulary" as it's already common vernacular used for YAML schemas. "Defining a schema" also feels less confusing than saying "defining a definition". Though, I suppose "defining a vocabulary" rolls off the tongue okay.

[j-simmons-phd]

Honestly @capsulecorplab, I could have sworn you were not keen on the use of the term schema. So, when I was deriving these use cases I wanted to offer at least one alternative to schema as a term.

Also, in my head definition was short for language definition and I was thinking more along the lines of add a language definition than define a language definition.

I can see the appeal of vocabulary, but I am not a fan of description. At the end of the day, if everyone is comfortable with using the term schema, I think the alignment with linkml community and our preexisting use of the term makes that option the stronger one.

[capsulecorplab]

The point of contention, if I recall correctly, was more so confusion around the use of the word "model" in the LinkML documentation, as it can sometimes refer to the schema and not the data describing the schema in usage.

[capsulecorplab]

Any reason we can't have the option to alias "schema"?

[j-simmons-phd]

In terms of the CLI tool UX I am sure we could work that out. I think the more important question is about how documentation and tooling will refer to projects that define languages like m30ml and dof. Do we want to see the documentation and tooling refer to language definitions or schemas (even if you can create a language definition sub-project using an aliased option called schema).

I lean in the direction of picking one set of terminology for our userbase for both simplicity and consistency. And, the easiest option (and one that might pick up a few linkml users) would be using the term schema.

[j-simmons-phd]

Per meeting on 2024-04-30, @capsulecorplab and @j-simmons-phd concur the decision is to go with Option 1.