The guide will outline the different data schemas that are stored on the Integra blockchain and also dive into great detail about each field in these schemas. Finally, the guide will define which APIs use which fields and how the fields can be used for various outcomes.
Data Schema Overview
When referring to data schema in this guide, it simply means the organization or structure of the information stored on the blockchain. There are 3 main schemas on the Integra blockchain but when developing the blockchain authentication layer, only 2 of the schemas are critical to have a complete understanding.
| Schema Name | Item Name | Description |
|---|---|---|
| Identity | identityType | This field allows a huge level of flexibility for what is passed and stored. It allows classification of various data stored on the blockchain. An example value is "com.integraledger.lmatid" or "com.integraledger.identityregistry.Key" |
| integraId | IntegraId is the identity field for any record stored on Integra's blockchain. It has to be an unique value across all values. It should be a UUID/GUID and if it is not passed in one will be generated and returned in the response object. IntegraId blockchain records can be retrieved by using IdentityExists/{guid}. | |
| recordId | RecordId is has one primary function for Smart Documents. This is another UUID/GUID that is generated in code and assigned to the QR code URL that is placed in the document. The URL will grab the record from the URI and get the blockchain record using RecordExists/{guid}. | |
| metaData | MetaData field is optional. This field can be used for version control of documents, information about the document origin/system, or whatever other information that pertains to the document or record set. DO NOT STORE PERSONAL OR PROPRIETARY INFORMATION IN THIS FIELD. This field can be queried using metadataexists API call. | |
| opt1 | Opt1 field is optional. Opt1 is for any sort of document set or foreign key data that should be stored in relation to the document or corresponding documents. This field can be queried using opt1exists and will return a JSON object of all records meeting the condition. The master record for a document set would be a perfect use for this field. | |
| opt2 | Opt2 field is optional. Opt2 is for the same purposes as the other Opt fields. It allows for structuring document sets. See information box below the table for an example of structured data storage on blockchain. This field can be queried using opt2exists and will return a JSON object of all records matching the condition. | |
| opt3 | Opt3 field is optional. Opt3 is for the same purposes as the other Opt fields. It allows for structuring document sets. See information box below the table for an example of structured data storage on blockchain. This field can be queried using opt3exists and will return a JSON object of all records matching the condition. | |
| value | Value is required. This field is the hash of the document or dataset that is being blockchain authenticated. The minimum recommended hashing algorithm that should be used is SHA-256. The hash can be queried using ValueExists QueryString and will return a JSON object of the document if one matches the hash. | |
| integraPublicKeyId | IntegraPublicKeyId is required on the main network, optional for testing on the test network. For information on getting an IntegraId please visit Integra Identity Basics for more information. In addition to being required, on the main network tokens associated with the IntegraId will be required. For more information please visit Tokens. | |
| signedValue | SignedValue is required on the main network, option for testing on the test network. This value will be generated using the private key of the IntegraId. The value will not be able to be decrypted but values with a public key can be test against the signed value. See Digital Signing for more information about the process. | |
| transactionId | TransactionId is not an input, this is blockchain unique identifier for the record/transaction that was just generated. This transactionId is important to be able to link to the actual transaction on the blockchain. To link to the transaction on explorer, the format is https://explorer.integraledger.com/#/tx/transactionId where the value after /tx/ is the transactionId. | |
| creationDate | creationDate is not an input, this is the date the record/transaction was created, not when it was successfully written as a block to the chain. | |
| UserKeyRegistry | Owner | Owner is required. The owner value should be the IntegraId that is created by https://identity.integraledger.com/ or using a created UUID/GUID. For more information please refer to Integra Identity Basics. |
| keyValue | KeyValue is required. This field should be the public key for the IntegraId. The public key should be text of the actual key and not a file. For additional information refer to Public and Private Key Pairs. | |
| $class | $class is generated automatically by registerKey when a new integraId/key is created. This value will always be "com.integraledger.identityregistry.Key". | |
| transactionId | TransactionId is not an input, this is blockchain unique identifier for the record/transaction that was just generated. This transactionId is important to be able to link to the actual transaction on the blockchain. To link to the transaction on explorer, the format is https://explorer.integraledger.com/#/tx/transactionId where the value after /tx/ is the transactionId. | |
| creationDate | creationDate is not an input, this is the date the record/transaction was created, not when it was successfully written as a block to the chain. | |
| Tokens | integraId | IntegraId is required. This IntegraId is the account that the tokens will be assigned to. More information about tokens can be found by visiting Tokens. To view tokens for a given IntegraId visit https://explorer.integraledger.com/#/transactions?type=integra_id&q=integraId. |
| amount | Amount is required. This is a numeric value that represents the number of tokens. | |
| issuedTxnId | issuedTxnId is the field that will ensure that the tokens are associated with an ISSUED transaction on the blockchain. This field will not be shown if the tokens are CREDITED. | |
| txType | TxType can be of the values CREDIT, ISSUED or REDEEMED. This field deals with the action of the tokens to the given account. |
Opt field values for structured data
To better understand structured data and document sets, using an example will shed light on the concepts and storage on Integra. A real estate shopping mall property is a great example. The entire mall would have a top level IntegraId, this would represent the entire property. This integraId could be stored in Opt1 for all documents related to this property. Then there are units within the property, each one of these units would also have an IntegraId. All documents associated with these units can be stored with the property integraId as opt1, the unit IntegraId as opt2 and the foreign key for the actual bill as opt3 that points to the accounting system's record. They can be queried for document set completeness on the property level or the unit level.