Skip to main content

Feedback

Loading...
Version: 4.x

TradeTrust document schema

To explain on TradeTrust's document schema, we will use a sample document. For this example, a verifiable document will be used.

We have 2 schema versions, OA Schema version 2, and OA Schema version 4 alpha which is more aligned with W3C VC data model.

Raw document​

Let's take a closer look at a raw document:

{
  "$template": {
    "name": "INVOICE",
    "type": "EMBEDDED_RENDERER",
    "url": "https://generic-templates.tradetrust.io"
  }, // needed for presentation of data in a decentralised renderer
  "issuers": [
    {
      "name": "Company A",
      "documentStore": "0x93092C2B449712281008112870063fF439367C00",
      "revocation": {
        "type": "NONE"
      },
      "identityProof": {
        "type": "DNS-TXT",
        "location": "example.tradetrust.io"
      }
    }
  ], // required to get the information of the issuer
  "network": {
    "chain": "MATIC",
    "chainId": "80002"
  }, // needed to determine the network of the document
  "id": "1111",
  "date": "2018-02-21",
  "customerId": "564",
  "terms": "Due Upon Receipt",
  "billFrom": {
    "name": "ABC Company",
    "streetAddress": "Level 1, Industry Offices",
    "city": "Singapore",
    "postalCode": "123456",
    "phoneNumber": "60305029"
  },
  "billTo": {
    "company": {
      "name": "DEF Company",
      "streetAddress": "Level 2, Industry Offices",
      "city": "Singapore",
      "postalCode": "612345",
      "phoneNumber": "61204028"
    },
    "name": "James Lee",
    "email": "def@company.com"
  },
  "billableItems": [
    {
      "description": "Service Fee",
      "quantity": 1,
      "unitPrice": 200,
      "amount": 200
    },
    {
      "description": "Labor: 5 hours at $75/hr",
      "quantity": 5,
      "unitPrice": 75,
      "amount": 375
    }
  ],
  "subtotal": 625,
  "tax": 0,
  "taxTotal": 0,
  "total": 625
}

Wrapped document​

We will need to wrap a TradeTrust document to generate a hash to ensure the integrity of the document. You can read more about it over at the document integrity section.

Now, lets take a look at a wrapped document:

{
  "version": "https://schema.openattestation.com/2.0/schema.json",
  "data": {
    "$template": {
      "name": "51ce82e4-d772-45c3-b854-8f50e6d0f05c:string:INVOICE",
      "type": "c07c3e4b-f5aa-4ac7-a0ba-35be56895895:string:EMBEDDED_RENDERER",
      "url": "bdaf86f4-8faf-4c8a-b00b-91ae97c23315:string:https://generic-templates.tradetrust.io"
    },
    "issuers": [
      {
        "name": "9772fe01-91c4-46af-9687-211b7b2f573e:string:Company A",
        "documentStore": "c6f41b35-49c8-450a-864d-20b065e22bee:string:0x93092C2B449712281008112870063fF439367C00",
        "revocation": {
          "type": "27865177-2b5e-4b45-92cb-f9f8d9cbd712:string:NONE"
        },
        "identityProof": {
          "type": "5e38c996-ffba-466a-bee7-aa31fbbf31e1:string:DNS-TXT",
          "location": "dc50caf2-2f3d-43ae-bf55-2ef5ac8c0d57:string:example.tradetrust.io"
        }
      }
    ],
    "network": {
      "chain": "d7011829-cdaf-4f54-8c23-8492e1c65404:string:MATIC",
      "chainId": "d8b0a3b0-58e9-465b-a5aa-dbd154877ebc:string:80002"
    },
    "id": "1e987726-d6d7-41f1-9859-0a06b0f87e12:string:1111",
    "date": "a90b9d97-b51a-4a72-97d4-297160ecd2f2:string:2018-02-21",
    "customerId": "fb300720-07a1-4cac-84d8-5ae230d29637:string:564",
    "terms": "ca45944a-6d13-4acd-88bc-e6dacf1ee5a7:string:Due Upon Receipt",
    "billFrom": {
      "name": "a4ce7ad8-a634-4c73-8ddc-6db70c7a77d8:string:ABC Company",
      "streetAddress": "fc65a8b0-82b9-4dab-9ee0-b2d1fb7b637f:string:Level 1, Industry Offices",
      "city": "bf653d90-61b0-4b8f-bbcd-8f6cc0895d57:string:Singapore",
      "postalCode": "5296a8b0-d2f1-47e8-b9d9-330525202990:string:123456",
      "phoneNumber": "f84be7f5-019a-4578-bf20-760a1ce51299:string:60305029"
    },
    "billTo": {
      "company": {
        "name": "565d8098-6c4b-4e95-9b62-ac580f8a8864:string:DEF Company",
        "streetAddress": "96b82c4e-887f-4aa7-9b59-110069eabad6:string:Level 2, Industry Offices",
        "city": "b3682df3-db5b-4276-b0b5-0932c6beff98:string:Singapore",
        "postalCode": "0c63fb9c-cee8-4bfc-bbcc-710791ee3d88:string:612345",
        "phoneNumber": "8f1651fb-fa21-4efb-bdcd-01951a85487e:string:61204028"
      },
      "name": "06110012-738a-4534-91b0-c9e3b9dca9e4:string:James Lee",
      "email": "e50cf21d-37bd-42ba-b592-b5ee268d01f3:string:def@company.com"
    },
    "billableItems": [
      {
        "description": "a7f53a1c-28f3-43da-adb4-8ca3686e0a74:string:Service Fee",
        "quantity": "5772a41e-df14-4a0d-aaf1-ae0b470523e9:number:1",
        "unitPrice": "2cda167e-f533-4402-940c-3279c8176c67:number:200",
        "amount": "d62ca746-bc06-40aa-962f-d81d85418741:number:200"
      },
      {
        "description": "6a8d455d-142f-4d15-9356-b4b85ff51fed:string:Labor: 5 hours at $75/hr",
        "quantity": "601ecae8-4ad2-4898-9ca7-5e4f94a5ffa5:number:5",
        "unitPrice": "9216bfe7-2f04-4d65-8273-698d4682e9e6:number:75",
        "amount": "d467b10c-0e4c-4e39-b434-3d996fcd3c50:number:375"
      }
    ],
    "subtotal": "666e7962-f674-44cf-82db-70a93939194b:number:625",
    "tax": "8cca3bf7-0ad4-4957-bb2b-9b4d3137cc5b:number:0",
    "taxTotal": "50c4605f-3931-4f10-bb1f-94d6c6850474:number:0",
    "total": "6e329e75-996f-4d35-9a04-65870ae174f7:number:625"
  },
  "signature": {
    "type": "SHA3MerkleProof",
    "targetHash": "080623ba6a9e12bfd0ad496226fb10cd4252d10d3b9eee6771fd348fef58a123",
    "proof": [],
    "merkleRoot": "080623ba6a9e12bfd0ad496226fb10cd4252d10d3b9eee6771fd348fef58a123"
  }
}

This will give us both targetHash and merkleRoot. You can read more about these hashes and how these hashes are derived upon here.

Key fields in the schema​

Key fields to note:

  • $template
  • issuers
  • network

The other fields in the document are dependant on the type of document you want to use. They will differ accordingly, as TradeTrust framework does not restrict the data of your document.

$template

The $template key describes the template used to render the document. It should have the following keys:

  • name is the name of the template to be use by template renderer to determine the template to use.
  • type will always take the value of EMBEDDED_RENDERER for documents rendered in this manner.
  • url will be the remote URL where your decentralised renderer resides.

issuers

The issuers key describes who issued this document. It should have the following keys:

  • name is a name label.
  • documentStore / tokenRegistry is the address of your deployed document store or token registry smart contract.
  • revocation is an optional field that stores the revocation status of the document.
  • revocation.type has the value of NONE or REVOCATION_STORE.
  • revocation.location is the address of your deployed document store or Online Certificate Status Protocol (OCSP) responder url.
  • identityProof.type is the method type used for identifying issuer. DNS-TXT or DNS-DID
  • identityProof.location is the domain URL where DNS txt records of documentStore / tokenRegistry address is created.

network

The network key is used to determine which network the document is issued on. It should have the following keys:

  • chain is the type of blockchain in which the document is issued on.
  • chainId is the value of the network in which is used to connect to the blockchain.

You can get the list of supported networks here.