---
# System prepended metadata

title: Master Data

---

# Master Data

## Executive Summary

The goal is to represent master data of a legal entity as a collection of claims/credentials. The entity itself is represented as a Decentralized Identifier (DID) which allows to cryptographically verify statements by the entity and allows an agent acting on behalf of the organization to authenticate with other organizations.


Current version of master data JSON-LD context can be found here: https://raw.githubusercontent.com/iil-network/contexts/master/masterdata.jsonld

## Prior Work

### SupplyOn SIM Standard
https://docs.google.com/spreadsheets/d/1QJjGtrAEz52rBftJsm6_3XVTrqFcN9A354D7dMqOutU/edit#gid=0

### CDQ
https://meta.cdq.ch/CDQ_data_model
https://meta.cdq.ch/Category:Data_model_concept
https://meta.cdq.ch/Community_business_partner_data


### W3C Organizational Vocabulary
https://www.w3.org/TR/vocab-org/

### W3C Registered Organization Vocabulary
https://www.w3.org/TR/vocab-regorg/

### W3C vCard Ontology - for describing People and Organizations
https://www.w3.org/TR/vcard-rdf/

### EU Business Graph
https://www.eubusinessgraph.eu/
https://github.com/euBusinessGraph/eubg-data
https://docs.google.com/document/d/1dhMOTlIOC6dOK_jksJRX0CB-GIRoiYY6fWtCnZArUhU/edit#

### GLEIF
* Level 1 Ontology: https://www.gleif.org/ontology/v1.0/L1/index-en.html
* Level 2 Ontology: https://www.gleif.org/ontology/v1.0/L2/index-en.html
* Entity Legal Form Ontology: https://www.gleif.org/ontology/v1.0/EntityLegalForm/index-en.html
* Registration Authority Ontology: https://www.gleif.org/ontology/v1.0/EntityLegalForm/index-en.html
* Base Ontology: https://www.gleif.org/ontology/v1.0/Base/index-en.html

### GS1 Core Business Vocabulary

[Link](https://www.gs1.org/sites/default/files/docs/epc/CBV-Standard-1-2-r-2016-09-29.pdf)

### Schema.org
https://schema.org

### Gaia X Participant

```plantuml
@startuml
Participant }|..|| En
@enduml

```

## Master Data Data Model

Scope (for now) is *public part* for a *legal entity*, but not everything has to be provided!

```mermaid
classDiagram
      ParentOrg "1" <-- "*" RegisteredOrganization : subOrganizationOf
      RegisteredOrganization "1" --> "1" Site : hasRegisteredSite
      Site "1" --> "1" SiteAddress : hasAddress
      RegisteredOrganization "1" --> "n" ContactPerson : hasMember
      RegisteredOrganization "1" --> "n" Identifier : hasIdentifier
      RegisteredOrganization "1" --> "n" BankAccount : hasBankAccount
      RegisteredOrganization "1" --> "n" Certification : hasCertification
      class ParentOrg{
          id (DID)
          legalName
      }
      class RegisteredOrganization{
          id (DID)
          legalName
          altName
          website

      }
      class Site{
          id (DID?)
      }
      class Identifier{
       type
       value
      }
      class SiteAddress{
       streetAddress
       zipCode
       city
       region
       country
       poBox
      }
      class ContactPerson{
      id (did)
      givenName
      legalName
      role
      }
      class BankAccount{
      id
      iban
      bic
      }
     
```

### Types of Identifiers

What do we need to support?

* LEI (Legal Entity Identifier)
* DUNS
* vatID 
* USCC (Unified Social Credit Code)
* GLN (Global Location Number)

#### Contact Persons

Contact persons are mainly public figures, e.g. officers mentioned in a commercial register. Contact persons can also be mentioned only by DID or an internal ID. 
An internal ID could be used to establish a connection between a company agent and the personal agent of the contact person (as described in the next section). The contact person can then share personal data herself.


##### Contacting an Officer

We could add the following Aries protocol to initiate a connection with an officer

![](https://i.imgur.com/dcUdvgM.png)

We could use the same for private contact information. A company could publish available roles/positions, and a requesting company could ask for a connection to the specific employee in that role/position.


## Master Data VP Data Model
```mermaid
classDiagram
    MasterDataVP "1" <-- "1" MasterDataVC
    MasterDataVP "1" <-- "n" ThirdPartyW3CVC
    MasterDataVP "1" <-- "n" IndyCredentialVC
   
```

A master data verifiable presentation is a signed container of an array W3C VCs. The credentialSubject of each VC MUST match the issuer and subject properties of the VP. On a high level we can distinguish three types of VCs in this array
1. A VC of type MasterData. This VC contains self-attested information and does not require a proof property, because it will be wrapped in a signed VP.
2. W3C VCs of types supported for a MasterDataVP about the subject from third party issuers. These VCs MUST have a proof property.
3. W3C VCs of type IndyCredential (and of types supported by a MasterDataVP). These VCs do not require a proof property. 


### An example of a IndyCredentialVC

Assumption holder has a bank account credential provided as an Indy credential containing
```
iban
bic
````
The credential has a specific schema and credential definition (and an implicit issuer)

We wrap this information in a W3C VC:
```
{

    "@context": ["https://www.w3.org/2018/credentials/v1",
                 "https://raw.githubusercontent.com/iil-network/contexts/master/masterdata.json"
         ],
  "id": "urn:234234",
  "type": ["VerifiableCredential", "IndyCredential", "BankAccountCredential"],
   "issuanceDate": "2017-12-05T14:27:42Z",
  "issuer": "did:sov:iil:asdfsafs",
  "schemaId": "dfsdfsdafasd",
  "credDefId": "fsdfsdfsad"
  "credentialSubject": {
    
    "@id":"did:sov:iil:sdfasfdsf",
    "iban": "4252354325",
    "bic": "2342342"
  }
 
}
```

The term IndyCredential needs to specify the used issuer, schemaId, and credDefId properties.
The properties inside the credentialSubject are specified by BankAccountCredential.
The VC does not need a proof, but it will indicate to the Company Agent, that it can request a proof of this information via an Aries proof request using the information provided in this VC.


## JSON-LD Implementation


Terms currently do not agree with the Data Model graphic above. In the graphic, we used terms from other vocabularies/ontologies (especially for the relationships). These will be mapped in the context.

```
"credentialSubject": {
        "id": "did:sov:iil:sadfafs",
        "type": "LegalEntity",
        "legalName": "Bosch Healthcare Solutions GmbH",
        "altName": "Bosch Healthcare",
        "logo": "https://upload.wikimedia.org/wikipedia/de/3/31/Bosch-logotype.svg"
        "identifier": [
          {
            "vatNumber": "123456789"
          }
        ],
        "registeredSite": {
          "id": "did:sov:iil:asfdsf",
          "address": {
            "streetAddress": "Stuttgarter Strasse 130",
            "zipCode:": "71332",
            "city": "Waiblingen",
            "region": "Baden-Wuerttemberg",
            "country": "Germany"
          }
        },
        "ultimateParent": "did:sov:ill:fdgrqwgqr",
        "contactPerson": [
          {
            "id": "urn:3t436436415",
            "firstName": "Florian",
            "lastName": "Schaaf",
            "role": "ceo"
          }
        ]
      }
```


### Complete Example

Play with it at JSON-LD Playground: https://tinyurl.com/ya296aed




```
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
    ],
  "type": "VerifiablePresentation",
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://raw.githubusercontent.com/iil-network/contexts/master/masterdata.jsonld"
      ],
      "id": "urn:dsfasdfsaf",
      "type": [
        "VerifiableCredential",
        "MasterDataCredential"
      ],
      "issuer": "did:sov:iil:sadfafs",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:sov:iil:sadfafs",
        "type": "LegalEntity",
        "legalName": "Bosch Healthcare Solutions GmbH",
        "altName": "Bosch Healthcare",
        "logo": "https://upload.wikimedia.org/wikipedia/de/3/31/Bosch-logotype.svg"
        "identifier": [
          {
            "vatNumber": "123456789"
          }
        ],
        "registeredSite": {
          "id": "did:sov:iil:asfdsf",
          "address": {
            "streetAddress": "Stuttgarter Strasse 130",
            "zipCode:": "71332",
            "city": "Waiblingen",
            "region": "Baden-Wuerttemberg",
            "country": "Germany"
          }
        },
        "ultimateParent": "did:sov:ill:fdgrqwgqr",
        "contactPerson": [
          {
            "id": "urn:3t436436415",
            "firstName": "Florian",
            "lastName": "Schaaf",
            "role": "ceo"
          }
        ]
      }
    },
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://raw.githubusercontent.com/iil-network/contexts/master/indycredential.jsonld", "https://raw.githubusercontent.com/iil-network/contexts/master/bankaccount.json"
      ],
      "id": "urn:dsfasdfsafsafd",
      "type": [
        "VerifiableCredential",
        "IndyCredential",
        "BankAccountCredential"
      ],
      "indyIssuer": "did:sov:iil:ffwfr2424",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "schemaId": "",
      "credDefId": "",
      "credentialsubject": {
        "id": "did:sov:iil:sadfafs",
        "bankAccount": {
          "iban": "2344524",
          "bic": "2423424"
        }
      }
    }
  ]
}

```

With LD Signature:

```
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
    ],
  "type": "VerifiablePresentation",
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://raw.githubusercontent.com/iil-network/contexts/master/masterdata.jsonld"
      ],
      "id": "urn:dsfasdfsaf",
      "type": [
        "VerifiableCredential",
        "MasterDataCredential"
      ],
      "issuer": "did:sov:iil:sadfafs",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:sov:iil:sadfafs",
        "type": "LegalEntity",
        "legalName": "Bosch Healthcare Solutions GmbH",
        "altName": "Bosch Healthcare",
        "logo": "https://upload.wikimedia.org/wikipedia/de/3/31/Bosch-logotype.svg"
        "identifier": [
          {
            "vatNumber": "123456789"
          }
        ],
        "registeredSite": {
          "id": "did:sov:iil:asfdsf",
          "address": {
            "streetAddress": "Stuttgarter Strasse 130",
            "zipCode:": "71332",
            "city": "Waiblingen",
            "region": "Baden-Wuerttemberg",
            "country": "Germany"
          }
        },
        "ultimateParent": "did:sov:ill:fdgrqwgqr",
        "contactPerson": [
          {
            "id": "urn:3t436436415",
            "firstName": "Florian",
            "lastName": "Schaaf",
            "role": "ceo"
          }
        ]
      }
    },
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://raw.githubusercontent.com/iil-network/contexts/master/indycredential.jsonld", "https://raw.githubusercontent.com/iil-network/contexts/master/bankaccount.json"
      ],
      "id": "urn:dsfasdfsafsafd",
      "type": [
        "VerifiableCredential",
        "IndyCredential",
        "BankAccountCredential"
      ],
      "indyIssuer": "did:sov:iil:ffwfr2424",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "schemaId": "",
      "credDefId": "",
      "credentialsubject": {
        "id": "did:sov:iil:sadfafs",
        "bankAccount": {
          "iban": "2344524",
          "bic": "2423424"
        }
      }
    }
  ],

    "proof": {
      "type": "Ed25519Signature2018",
      "verificationMethod": "did:key:Adqw7ULX1oKKRodGymdA3u23igdngimhE9MoE5sUaTEm#Adqw7ULX1oKKRodGymdA3u23igdngimhE9MoE5sUaTEm",
      "proofPurpose": "assertionMethod",
      "created": "2020-07-03T13:00:25Z",
      "jws": "eyJhbGciOiAiRWREU0EiLCAiYjY0IjogZmFsc2UsICJjcml0IjogWyJiNjQiXX0..YvsxTMWTkFuAJWg2NGCernWdcOsUhpEO94BfXEV2OFUeJawQD3CsEMxYOTN9UBgGcyfKeeQR-A-aM0F1kvPEDw"
    }
  }
```