Should abstract classes have their maturity specified explicitly?

[larrybabb]

Within the GKS repo schema source files there is a maturity property which we intend to use to identify the maturity of a given element in the schema. Folks generally think of the overall class as the Element and thus it's maturity is about 100% of it's schema definition. However, since we are able to add properties or suggest properties and wait on implementers to mature them we need to be able to deal with parital maturity or properties that are not up to par with the maturity that the class has attained.

This is dealt with in FHIR by placing a D, TU or N at the class level and then any property that is less than the level of the class gets its maturity level specified. The assumption is that any property that does not have a specified maturity level assumes the maturity level of the class.

We discussed this when we started down this path thinking we would follow this approach. Now we need to finalize the plan.

In addition we are using inheritance in our schemas (much like FHIR does with their datatypes). So we need to determine if we should apply the maturity property to all classes whether or not they are the concrete classes actually being implemented.

If we do not apply the maturity property to the core-im and other classes that some of our classes our inherited from then how can we determine the maturity of any properties that are defines in these abstract classes which may not have been implemented or used by anyone vs those that are in great use.

Just as we might apply the rule that

• all properties on a class assume the same level of maturity as the class unless otherwise specified. And, no property can have a specified maturity equal to or greater than the class.

We should also have a rule that

• all abstract/super classes assume the highest level of maturity of its descendant classes. And all properties on abstract classes will assume the highest level of maturity on that property in the descendants.

[larrybabb]

From Alex Wagner 10:31 AM

It depends on what is meant by “abstract class”. Anything with properties–heritable or not–should have maturity associated with those properties, which are used by concrete classes.

But, in JSON Schema you can define schemas that are groups of other schemas; a pattern we often use (e.g. Variation is one of Molecular Variation , Systemic Variation).

When we discussed these groups previously, we considered that the logic for updating them would effectively create cascading version changes that were not desirable.

Do you see a need for us to do this?

[larrybabb]

I'm not sure. I think when we enhance the maturity work to address property level maturity we will need to put the maturity on all properties that differ from the class at which point those properties may only exist in the classes that are 'heritable'

For example, in Entity no one is using the alternateLabels property so based on our policy that we only mature elements that are implemented somewhere we would want to leave that property in draft while the Entity class would be at trial use . Right?

I think the Variation, MolecularVariation and SystemicVariation classes are special case (that I was not considering). For those I think we would presume their maturity would be equal to the highest maturity of any of the individual oneOf classes they are defined by.

[larrybabb]

For now I suggest we put the maturity flag on ALL classes and defer the property level maturity discussion. If there are any properties that do not get used in a trial use class we will lower there maturity to draft when the property-level maturity is implemented in our schema processing workflow.

[larrybabb]

I know it's not appropriate to mark your own suggested answer as the answer, but I'm in a time crunch so please weigh in if this is unacceptable asap.

[ahwagner]

I think this is right, provided that we define a "class" here (since JSON Schema doesn't have classes) as a schema with defined properties, heritableProperties, required, or heritableRequired. This will prevent us from needing to track maturity on schema definitions that primarily function in an "organizational role" (as @rrfreimuth put it), such as MolecularVariation and SystemicVariation, that do not add any structural elements or redefine properties.

[rrfreimuth]

My 2 cents, FWIW.

The maturity model was intended to communicate information about relative stability of data classes. Abstract classes are not implemented directly so there is a gray area here. This gets fuzzier when the abstract class is used as shorthand for data type polymorphism.

If an abstract class serves only an organizational role and does not convey any special semantics (which might be revised and thus change the meaning of its concrete child classes), then it could be viewed as a technical artifact that does not require a maturity level. The implemented data class could be modeled equally as a single class containing all attributes directly, or as a class at the bottom of an arbitrarily deep inheritance hierarchy from which its attributes are derived. From the implementation POV, it is the structure and semantics of the instantiated class that matters, and inheritance only matters if it imposes meaning.

IMO, classes like Entity do not convey meaning in a way that is likely to impact an implementer's view of the maturity of a child class. It is a class that defines generic attributes that can be inherited so the rest of the model is cleaner. Therefore, I would probably tend to consider inherited attributes like alternateLabels to be defined in each concrete class and discussed in that limited context. If it is found that some classes use the attribute and others do not, that might inform the organization of the abstract classes but it wouldn't change any meaning.

I don't have strong feelings about this, I'm only offering ideas to try to streamline the process.

[larrybabb]

I completely agree with you on an academic level. But we are dealing with json schema and since we do not define the properies in the concrete classes (only extend them occassionally when we need to constrain them further) it is impossible to specify the maturity of a common property from the Entity level on each ultimate concrete class.

The intended purpose of inheritance is that the property is valid for all subclasses so that once we decide it is valid we should evolve it's maturity to reflect that (for all concrete classes). If for some reason an abstract class property was determined to be not useful or necessary in some concrete classes we could either move that property to a different branch of the class hierarchy or do what is normally done in inheritance models and assume those subclasses do not need it and therefore it is purely optional (but this would not impact the maturity at large).

If you look at FHIR they put maturity on all classes regardless if they are concrete or not (and datatypes). Resource is a great example. This is a class that is not used directly but subclassed yet it needs to evolve it's maturity.

[rrfreimuth]

I agree on all points, and your second para is what I was eluding to when I said "If it is found that some classes use the attribute and others do not, that might inform the organization of the abstract classes".

I thought the question was more about the policy of how to push maturity labels up to abstract classes, than the mechanics of doing so. My proposal was essentially don't worry about stuff at the abstract level unless it has meaning (domain semantics of the object) at the concrete level. If you'd prefer to label everything, go for it. 😄