Existing definitions¶
When deciding which definitions to use in your project, you might consider utilizing existing definitions. Existing definitions allow your application to read records and write records originally created by another application. This enables simple cross-application data sharing.
Ways to discover definitions¶
There are two primary mechanisms for discovering existing definitions:
- Inspect the indexes of known DIDs to see which definitions they have
- Inspect the Github repos of open source projects to see which definitions they're using
Inspecting indexes¶
Use the IDX CLI to inspect the indexes of known DIDs.
Prerequisites¶
- You must have a properly configured IDX CLI. See using the CLI to get started.
- You must have a list of known DIDs that are relevant to your application, such as existing users or target users. You can get creative assembling this list using any means available to you. It's worth noting that many 3ID DIDs have blockchain accounts publicly linked to their DID, which can be used to lookup their DID from their blockchain account.
List all definitions¶
Use the idx index:inspect
command to view all definitions for a given DID:
idx index:inspect <UserDID>
idx index:inspect did:key:z6MkuEd4fm7qNq8hkmWFM1NLVBAXa4t2GcNDdmVzBrRm2DNm
✔ IDX document loaded
✔ kjzl6cwe1jw14bdsytwychcd91fcc7xibfj8bc0r2h3w5wm8t6rt4dtlrotl1ou (IDX basicProfile)
✔ Definition: Basic Profile (Basic profile information for a DID)
✔ Schema: ceramic://k3y52l7qbv1frxjdr9qpn9ldvbxb0jg4eig7wtjkdu6gk84vyazw9j4txf4o6d2io (IDX BasicProfile)
This response shows an example of a DID with a basic profile stored in its index.
View a definition¶
Use the idx definition:info
command to view a given definition. If the provided definition is valid it will display the contents of the definition. If it's invalid it will throw an error.
idx definition:info <DefinitionDocID>
idx definition:info kjzl6cwe1jw14bdsytwychcd91fcc7xibfj8bc0r2h3w5wm8t6rt4dtlrotl1ou
✔ Definition loaded
{
name: 'Basic Profile',
schema: 'ceramic://k3y52l7qbv1frxjdr9qpn9ldvbxb0jg4eig7wtjkdu6gk84vyazw9j4txf4o6d2io',
description: 'Basic profile information for a DID',
id: DocID(kjzl6cwe1jw14bdsytwychcd91fcc7xibfj8bc0r2h3w5wm8t6rt4dtlrotl1ou)
}
View a schema¶
Use the idx definition:schema
command to view the schema for a given definition:
idx definition:schema <SchemaDocID>
idx definition:schema kjzl6cwe1jw14blngzz896wlixmclprl7nxkpj9s1fgiph2quok8894q7f5mkk0
✔ Schema loaded
{
type: 'object',
title: 'BasicProfile',
'$schema': 'http://json-schema.org/draft-07/schema#',
properties: {
url: { type: 'string', maxLength: 240 },
name: { type: 'string', maxLength: 150 },
emoji: { type: 'string', maxLength: 2 },
image: { '$ref': '#/definitions/imageSources' },
gender: { type: 'string', maxLength: 42 },
birthDate: { type: 'string', format: 'date', maxLength: 10 },
background: { '$ref': '#/definitions/imageSources' },
description: { type: 'string', maxLength: 420 },
affiliations: { type: 'array', items: { type: 'string', maxLength: 140 } },
homeLocation: { type: 'string', maxLength: 140 },
nationalities: {
type: 'array',
items: { type: 'string', pattern: '^[A-Z]{2}$', maxItems: 5 },
minItems: 1
},
residenceCountry: { type: 'string', pattern: '^[A-Z]{2}$', maxLength: 2 }
},
definitions: {
IPFSUrl: { type: 'string', pattern: '^ipfs://.+', maxLength: 150 },
imageSources: {
type: 'object',
required: [ 'original' ],
properties: {
original: { '$ref': '#/definitions/imageMetadata' },
alternatives: {
type: 'array',
items: { '$ref': '#/definitions/imageMetadata' }
}
}
},
imageMetadata: {
type: 'object',
required: [ 'src', 'mimeType', 'width', 'height' ],
properties: {
src: { '$ref': '#/definitions/IPFSUrl' },
size: { '$ref': '#/definitions/positiveInteger' },
width: { '$ref': '#/definitions/positiveInteger' },
height: { '$ref': '#/definitions/positiveInteger' },
mimeType: { type: 'string', maxLength: 50 }
}
},
positiveInteger: { type: 'integer', minimum: 1 }
}
}
Inspecting repositories¶
Use Github or other code collaboration platforms to inspect the repositories of open source projects that use IDX. To locate these projects, you can either view the ecosystem page or lookup the Github topics for #idx and #identityindex. Once you find a set of projects, you will be looking for their JavaScript files which perform get
and set
calls on the IDX API. If they are using aliases, you will see the definitionIDs in their aliases
object. Otherwise, you will see definitionIDs directly in their calls.
After gathering a list of definitionIDs, follow the steps above to view a definition and view a schema.
Add to your project¶
After you have decided which existing definitions you would like to use in your project, add them to the alias
object in your JavaScript file as shown in adding aliases.