How do I describe a hierarchical relationship between software objects? [closed]

Question

I'm trying to express a particular relationship between two software resources available in an API. The relationship is such that one of the resources is the "main" or "original" one and is required before the system can create the other resource. For example, the invoice object is derived from the customer resource, the "main" resource. What shall I call the relationship, in either direction? I could think of the following alternatives:

• Main resource and derived resource
• Origin resource and derived resource
• Super-resource and sub-resource
• Supra-resource and infra-resource
• Parent resource and child resource (I can't use this one because it's reserved for another form of relationship between objects.)

Answer 1

You don't call them with any of those terms. Not everything needs to be expressed in an object's name.

Using your example, you call an invoice "invoice" and a customer "customer", not "main customer" and "derived invoice", that does not make any sense.

Call things by their common names, don't add artificallly attributes to them which don't fit, that will only create confusion,

Answer 2

You should distinguish between what a thing within your code is or represents and what roles it can take on in specific contexts. So your customer and invoice objects should be called customer and invoice, respectively, as @DocBrown suggested.

Within the hierarchical representation, the terms parent/child are often used, it is somewhat unclear why exactly this isn't an option for you. An alternative role name pair is owner/owned which describes that on a technical level, the owned object can not exist without an owner. In multi-level hierarchies the roles are switched as you change your focus, for example, an invoice may be owned by a customer, but it may itself be the owner of invoice items.

In a REST API, I would normally use hierarchical resource names to access owned resources, such as customer/100/invoice/1 but YMMV. When your application requires accessing invoices by invoice number irrespective of customer, having an /invoice path makes more sense. But the role names owner and owned shouldn't appear anywhere in the API.

Answer 3

I assume that customer and invoices are just examples and you have dozen of pairs like that. But what is your purpose for using the term?

In very broad and neutral terms you are referring to a dependency between objects, considering that the Invoice is depending on a Customer:

• Customer is a dependency
• Invoice is a dependent depending on the dependency

You could consider to describe more precisely the relationship from a design perspective, but you‘ll quickly enter into interpretations and (sometimes long and unproductive) discussions between experts. For example:

• using UML terminology you could consider that Invoice is a component of a Customer that is a composite, both being related by a composite aggregation (i.e composition). But this means that if you delete a customer, you‘d also delete all its invoices, whereas accounting experts would tell that you can get rid of a customer but the invoice need to stay, for tax purpose and use a simple association instead.
• using DDD terminology you could consider that Invoice is an entity belonging to an aggregate with Customer as aggregate root. However, other viewpoints may object that both could be associated aggregates.

Finally, you could also answer your question from a user perspective:

• Customer is "master data"
• Invoice is "transactional data"

This terminology is specific to business applications and can be very useful when discussing with users or documenting for users (and a lot of successful software packages use this terminology, starting for example with SAP, Oracle and Microsoft dynamics to name only a few). It is however too imprecise for deeper discussions, e.g. when talking about data retention schemes, or when addressing dependencies between objects of the same category (e.g transactional objects: a sales order and a delivery schedule).