Transitivity of JSON schemas - should BaseSecurityTransaction inherit from BaseTransaction?

[roehst]

Hi, folks!

1. What I am trying to do

I am writing a tool to translate the JSON schema files to a .dot file, so we can get a quick glimpse of all the relations using GraphViz.

• Edges in the graph correspond to allOf entries in Schemas.

2. Case

In schema https://opencaptablecoalition.com/schema/objects/transactions/acceptance/StockAcceptance.schema.json I see the following entries in allOf:

  "allOf": [
    {
      "$ref": "https://opencaptablecoalition.com/schema/primitives/objects/BaseObject.schema.json"
    },
    {
      "$ref": "https://opencaptablecoalition.com/schema/primitives/objects/transactions/BaseTransaction.schema.json"
    },
    {
      "$ref": "https://opencaptablecoalition.com/schema/primitives/objects/transactions/BaseSecurityTransaction.schema.json"
    },
    {
      "$ref": "https://opencaptablecoalition.com/schema/primitives/objects/transactions/acceptance/BaseAcceptance.schema.json"
    }
  ]

I see that BaseSecurityTransaction does not include BaseTransaction as an allOf entry.

As far as plotting is concerned, having BaseTransaction inherit from BaseSecurityTransaction would make the plot much cleaner.

But first, I would like to understand the schema better.

3. Question

I found no issues or discussions regarding Inheritance for this specific case.

Should BaseSecurityTransaction inherit from BaseTransaction? If not, what is the rationale for this choice?

Thanks in advance.

[pjohnmeyer]

@roehst, the short answer to your question is "no, BaseSecurityTransaction should not inherit from BaseTransaction".

The allOf construct in JSON Schema should be seen more as composition as opposed to inheritance. JSON Schema does not, in fact, have an "inheritance" concept. allOf says "for this schema, all of the rules in these other schemas also apply." Early on we did have a more hierarchical schema, but it made it harder to understand / navigate the schema when looking at a single leaf object type.

Would you say the choice of the prefix Base is misleading? I've been feeling that way from time-to-time but haven't had a motivator to address it.

[jacobyavis]

Hey @roehst, @pjohnmeyer

I agree that the prefix "Base" made sense early on, but since switching to a composition structure (done in PR #80 in January) it has come to be somewhat misleading nomenclature.

I think changing the naming scheme for all primitives would certainly have value for this project, and prevent further confusion on this from new members

Instead of e.g.:
BaseObject
BaseTransaction
BaseSecurityTransaction
...

I can think of a few possible substitute names:
1.
HasObjectDef
HasTransactionDef
HasSecurityTransactionDef
...

HasObjectTraits
HasTransactionTraits
HasSecurityTransactionTraits
...

HasObjectAttributes
HasTransactionAttributes
HasSecurityTransactionAttributes
...

I put my favourite at the top, the Has*Def variant.

We could also leave off the word "Has" in any of the above options as well, but I think it helps to demonstate the "has a" relationship that is composition.

Thoughts?

[pjohnmeyer]

@jacobyavis of your options I think I like 2) best followed by 1.

I'd like to offer up an alternative, though, and that is to eliminate all prefixes and suffixes.

Object
Transaction
SecurityTransaction
...

To me I read the schema like this:

"A StockAcceptance is allOf these things: an Object, a Transaction, a SecurityTransaction, and an Acceptance. It also meets the following criteria... ".

I don't think we need the prefixes or suffixes on the primitives at all. What do you think?

[roehst]

Yes, the naming of the entities make up an hierarchy in my mind.

I read it as base security transactions are base transactions which are base objects, implying that the base object reference would me redundant.

Which left me confused also about what was the relation of BaseAcceptance and the other JSON schemas in the allOf composition.