Nesting objects or linking?

[bartbink]

docs/contexts/eucc/credentials/eu-company-certificate.json

EUCC Schema

In the EUCC we follow the sugested Json schema from Archipels. When stating claims stored in a wallet we follow the Ecdsa 2023 translation.

Nesting or linking

What I saw in the Json Schema and the implementation is the mixed approach to nesting objects and referring to separate objects. We nest objects like Address and link to objects like Person.

Proposal

I propose to do one or the other. In the information model all objects are linked, not nested. In a credential however we have a choice, nesting or linking.

Linking reason 1
So as an information modeler I don't nest, but I link to other entities. This gives more control and avoids repetition (linking to the same address-object it the Registered Office is the same as the Correspondence address).
When modeling Organization a link is made to Address for registered office and correspondence address.

When modeling EUCC there are obligatory objects credentialSubject, credentialStatus and credentialSchema. The credential links to a separate Natural Person Credential. It can, in the same manner, link to other credentials like Address.

Linking reason 2
When looking at selective disclosure we need control as well. selective disclosing parts of a nested object is complicated. When the objects are not nested, selective disclosure is realised the same for every credential.

Linking reason 3
Maybe the most important reason, make a choice, or link to objects, or nest objects. Otherwise there should be rules when to nest and when not to nest. The latter will result in strange behaviour in the wallet when presenting credentials especially with selective disclosure.

[rkxx]

I am afraid there is no choice between linking or nesting. The only choice is either nesting or nesting and linking. Why?

Structured JsonObjects contain JsonObjects unless they are "flat". We need structured JsonObjects to express company claims properly.

So we only have to make the decision if we want to use linking beside nesting or not.

I strongly recommend to use linking for objects which exist independently of their parent. Otherwise, uncorrelated objects needs to be created for every relationship. In the information model we are using Aggregation and Composition relationships. That's best practice in the unified modelling world. Aggregation is a HAS-A relationship (linking). The linked object exists independently of the parent. Composition is a PART-OF relationship (nested). The nested object dies with its parent. It doesn't exists independently.

classDiagram
    
    class LegalEntity{
        <<abstract>>
        id
    }
    class LegalPerson{
        <<credentialSubject>>
        legalName
        legalIdentifier
        legalFormType
        registeredAddress
        contactPoint
        registrationDate
        legalEntityStatus
        legalRepresentative
        legalEntityActivity
    }
    class LegalRepresentative{
        <<anonymous>>
        legalEntityId
        role
        scopeOfRepresentation
    }
    class ContactPoint{
        <<anonymous>>
        contactPage
        hasEmail
        hasTelephone
    }
    class NaturalPerson{
        <<credentialSubject>>
        familyName
        givenName
        gender
        birthDate
        birthPlace
        postalAddress
        taxDomicile
        isAlive
        jobTitle
        citizenship
        domicile
    }
    class Nace020{
        businessCode
        businessDescription
    }
    class Domicile{
        postalCode,
        addressCountry,
        addressLocality
    }
    LegalPerson "1" *-- "0..1" ContactPoint
    LegalPerson "1" *-- "0..1" Nace020
    LegalPerson "1" *-- "0..n" LegalRepresentative
    LegalRepresentative "0..n" o-- "1" LegalEntity
    LegalEntity <|-- NaturalPerson
    LegalEntity <|-- LegalPerson
    NaturalPerson "1" *-- "1" Domicile

Loading

We use Composition (nesting) for any relationship (indicated by filled black diamond) except for the relationship to the NaturalPerson, where we use an Aggregation (linking) relationship (indicated by filled white diamond). The NaturalPerson credential subject exists independently in its own credential and can be reused for different relationships (UBO, Signatory, ShareHolder, ...). We could nest the claims of the person everywhere in the parent, but this would clatter up the parent and not express that it is the same person. It would be just bad practise.

Conclusion: Composition (nesting) should be used if the child object doesn't exists independently. Composition results in structured JsonObjects. Aggregation (linking) should be used for objects existing independently of the parent (e.g. a NaturalPerson). Linking is implemented using unique identifiers (e.g. a globally unique credential subject node identifier).