Naming conventions for classes/properties specialized in the profiling process

[mbrush]

This page is to document / continue discussions about the practice of using more descriptive/informative naming conventions for classes and property specializations created as part of the VA profiling process - where the derived class/property should include is base core-im type in its name.

• e.g. specializing of the Statement class into VariantPathogenicityStatement, not into VariantPathogenicity
• e.g. specializing the Statement.subject property into variantSubject or subjectVariant, not variant
• e.g. specializing the Statement.qualifier property into modeOfInheritanceQualifier, not modeOfInheritance

From the outset this type of naming convention has been IMO a critical part of the framework, but in their recent implementation efforts Alex and Larry have proosed to do away with this practice. Below I will copy/expand on text from recent Slack threads, to seed further discussion.

Larry's take:

I also don’t necessarily agree with embedding the name of the superclass or data type into the attribute name as this becomes a slippery slope on where it ends. That type of variable naming practice is well understood in programming to be something newbies generally do while learning but is highly frowned upon in most best practices guides. I would think our desire to add data type names to the end of classes and attributes really falls into the “helping newcomers understand the schema more quickly “ category. But these type of training wheels are difficult to remove later and are generally applied inconsistently and create noise in an artifact that is primarily meant for computational use.

Matt's response :

I agree your arguments make sense in the context of a local, project-specific schema (and as I have said, implementation profiles are free to not follow this convention). But to me they are less convincing in the context of a global GA4GH standard, where a broader, more diverse, and less familiar community of users will see the models and data. Nor do they convince me in the context of the modeling/profiling framework at the core of VA - where the connection between a core domain agnostic model and derived statement specific profiles is critical. Here, the more descriptive naming convention ensures unambiguous semantics and a clear connection between layers of standards, and is IMO absolutely essential.

We have this debate of perspectives over and over - traditional schema development vs development of a profiling-based global standard. And I will continue to push on the point that we are doing something new and innovative that requires shedding some of the traditional norms for what I see as a greater good, and what I think is essential for the success of the VA approach.

I do get that to traditional developers, schema and data are ultimately for computational use. This is particularly true of the implementation schema and data you all are creating for your specific applications. But I would argue that this is less true for the VA standard models and data . . . which will be seen by new users of varied expertise, backgrounds, and interest who will continually be coming upon these standard models, and looking at the data they support. These users will be trying to understand the semantics of this data, and the process through which Statement models were derived form the core-im using the profiling approach. In these settings, a clear connection between the standard profiles and the core-im is paramount - and facilitated by consistent and explicit naming conventions on properties. Again, I am not saying that project implementation profiles need to follow my explicit naming practice - if they want to drop 'qualifier' or 'statement' form the end of their property names, that is their prerogative, But in the standard models, I think it is critical that these remain.

At the end of the day I just think it is critically important that a user looking to understand a collection VA data set including pathogenicity classifications, prognostic interpretations, therapeutic response, oncogenicity classifications, and cohort allele frequencies - can come to this task from the perspective of a single foundational model (the core-im), and immediately see this model manifest in diverse VA datasets. IMO this dramatically lowers the barrier to users understanding and comparing the data - allowing them to clearly pick out the core assertion put forth in each record, and the evidence and provenance supporting this. Without the these naming conventions, profiled class and property names will provide no immediate connection back to the core-im model, and the foundational model unifying these datasets becomes much harder to recognize (users have to dig through the schema or documentation to see this). The task of understanding and integrating and applying VA knowledge becomes unnecessarily more challenging, as we would have stripped away a central value proposition of the VA approach.

Finally, I've yet to hear a convincing explanation of concrete harm done by including an additional term at the end of a few class or property names (other than going against tradition, or the fear of being perceived as noobs by those with a more traditional perspective). Digging into this, and providing more rationale for why this is so 'highly frowned upon', is perhaps one direction the conversation here may take? As may be Larry/Alex's take on the value that I am arguing for these naming conventions (considered from the perspective of the Standard Profiles, not project-specific implementation models) In this way, we might get at whether harm done by this practice may or may not outweigh what I see as essential benefits it offers for the VA modeling framework.

Sorry to lay it on so think - but obviously I feel pretty strongly about this, Of course I don't want to do anything that would drive adopters away or frustrate them with extra work. I may be convinced otherwise - but I don't see the conventions I am promoting as being a significant barrier - esp since we are only talking about the names of a few classes and properties in a given profile. (e.g. this amounts to adding an extra word to the names of one class name and four property names in the Var Path profile, and to one class name and three property names in the caf profile).

[larrybabb]

I am in support of Matt's perspective at this point. He has a consistent and reasonable principles behind the proposal to name the SPOQ related attributes and descendant profiles. Since VA is the Standard for the SPOQ info model and derivative profiles we should follow these conventions. If these conventions begin causing issues we can re-take up this discussion. IMO it is not prudent to delay forward progress on this issue.

As far as the implementation profiles, we have clearly stated that while we recommend they use the same naming conventions, they ultimately can do whatever is most useful for adoption and efficiency in their given implementation use cases.

That said, I would like to hear if others disagree with this outcome at this time. In the meantime, we will begin applying this convention to all Standard IM and profile schemas, while keeping the pilot implementers existing names intact.