Creating Your Own Schemas
Each registry can store data as entities. An entity is defined by its schema. This guide demonstrates how to create a schema to define your own entity.
The following is an example schema for a student entity. The comments should guide you as to which fields are required, and what fields should be adjusted as per your needs.
Note: Schema files cannot contain comments. The following example has been commented for your understanding only.
1
{
2
// This must be at the top of all schemas. See http://json-schema.org/understanding-json-schema/reference/schema.html#schema
3
"$schema": "http://json-schema.org/draft-07/schema",
4
// This is a schema object...
5
"type": "object",
6
// ...that declares a Student entity
7
"properties": { "Student": { "$ref": "#/definitions/Student" } },
8
// The actual definition of the Student entity
9
"definitions": {
10
// You can declare multiple entities in one schema file, just make sure you
11
// add the entity name in the `properties` field above
12
"Student": {
13
// The path to the declaration in the schema entity
14
"$id": "#/properties/Student",
15
// A Student is an object...
16
"type": "object",
17
// ...with the following required fields
18
"required": ["name", "phoneNumber", "email", "school"],
19
// The `phoneNumber` field must be unique across all Student entities
20
"uniqueIndexFields": ["phoneNumber"],
21
// The fields a Student entity can have
22
"properties": {
23
// Full name (string)
24
"name": { "type": "string" },
25
// Phone number (string)
26
"phoneNumber": { "type": "string" },
27
// Email (string)
28
"email": { "type": "string" },
29
// What school they are going to (string)
30
"school": { "type": "string" }
31
}
32
}
33
},
34
// Sunbird-RC specific configuration
35
"_osConfig": {
36
// The following field is only needed if the entity is a human that can
37
// login, grant consent, and manually attest claims. It will (usually) not
38
// be needed for something like a book or toy entity.
39
// The following fields are used to create a corresponding user in Keycloak,
40
// the authentication service used by Sunbird RC.
41
"ownershipAttributes": [
42
{
43
// The path to the field to consider the email of the entity
44
"email": "/email",
45
// The path to the field to consider the phone number of the entity
46
"mobile": "/phoneNumber",
47
// The path to the field to consider as unique ID of the entity
48
"userId": "/phoneNumber"
49
}
50
],
51
// The following fields are only needed if you are using the claim-attest
52
// flow for certain fields of the entity
53
// Which fields' values must be attested before they can be considered valid
54
"attestationAttributes": ["school"],
55
"attestationPolicies": [
56
// For each field mentioned in the `attestationAttributes` field, add
57
// an object like so:
58
{
59
// The name of the field
60
"property": "school",
61
// The path to the field (dot-separate fields if the field is nested, $
62
// is the root of the entity)
63
"paths": ["$.school"],
64
// Set the attestation type to `MANUAL` if another entity needs to login
65
// and verify the claim
66
"type": "MANUAL",
67
// What type of entity should be able to attest the claim OR the role an
68
// entity should have (in Keycloak) for them to be able to attest the claim
69
"attestorEntity": "Teacher",
70
// The condition for a certain entity to be able to attest the claim. In
71
// this case, the attestor Teacher entity must be in the same school as
72
// the Student entity to attest the claim
73
"conditions": "(ATTESTOR#$.school#.contains(REQUESTER#$.school#))"
74
}
75
]
76
}
77
}
Copied!
To add a new entity to the registry, place the JSON file defining its schema in the schemas folder. If you have setup the registry using the Registry CLI, place the JSON file in the config/schemas folder. If you are running the registry from its source, place the schemas in the java/registry/src/main/resources/public/_schemas folder. If you are using a docker-compose.yaml file to start the registry, the schema folder will be mentioned in the file under the volumes section in the registry container's configuration.
Then restart the registry by running the following:
1
# If using a docker-compose file:
2
$ docker compose up --force-recreate -d
3
# If using the Registry CLI:
4
$ registry restart
Copied!
If you restarted the containers manually (without the CLI), then wait approximately 40 seconds for the containers to start. You can view the status of the registry by running the following:
1
# If using a docker-compose file:
2
$ docker compose ps
3
# If using the Registry CLI:
4
$ registry status
Copied!
docker compose up --force-recreate -d is only required when a change is made to the configuration (e.g.: an environment variable is updated in the docker-compose.yaml file, a new entity schema file was placed in the schemas folder). If you simply want to restart the registry process running in the container, a simple docker compose restart or registry restart --soft will suffice.
Last modified 8d ago
Copy link
Edit on GitHub