Creating Schemas
This procedure explains how to create and manage Grid schemas using Grid’s command-line interface. Features such as Grid Product and Grid Location require a schema that specifies the format and type of the properties available when creating the item.
This procedure starts with steps to connect to a Splinter node and set
environment variables to simplify entering the grid
commands in the procedure.
Next, it explains how to define a schema YAML file, using a GS1 product schema
as an example, then use grid schema create
to submit a transaction that adds
the schema to the distributed ledger.
Finally, this procedure shows how to change a schema with grid schema update
.
Prerequisites
-
For Grid on Sawtooth:
- A working Grid node.
- A working Grid node.
-
For Grid on Splinter:
-
Two or more working Grid nodes. (See Running Grid on Splinter for the procedure to set up and run Grid in Docker containers.) The examples in this procedure show two nodes,
alpha-node-000
andbeta-node-000
, that are running in a Docker environment. -
An approved Splinter circuit with two or more member nodes. (See Creating Splinter Circuits for more information.) This procedure assumes that there is a circuit with
alpha-node-000
andbeta-node-000
as members. -
A fully qualified service ID for the scabbard service on this circuit, in the format
CircuitID::ServiceString
. (See Determine the Service ID for the commands to display this information.) This procedure uses the example ID01234-ABCDE::gsAA
.
-
-
The Grid daemon’s endpoint (URL and port) on one or both nodes. This procedure uses
http://localhost:8080
. -
The ID of an existing Pike organization that will own the new schema. You must be defined as an agent with full schema permissions for this organization. That is, one agent must be identified with your public key and must have permission to create and update schemas. (See Creating Organizations for more information.)
-
Existing public/private key files in
$HOME/.grid/keys/
(as generated bygrid keygen
). The example environment uses the key files$HOME/.grid/keys/alpha-agent.priv
and$HOME/.grid/keys/alpha-agent.pub
to indicate that you will be acting as your organization’s agent to add schemas from the alpha node.
Procedure
IMPORTANT: The commands in this procedure show host names, IDs, Docker
container names, and other values from the example Grid environment that are
defined by
grid/examples/splinter/docker-compose.yaml
and grid/examples/sawtooth/docker-compose.yaml
This file sets up the nodes alpha-node-000
and beta-node-000
and runs the
Grid and Splinter components in separate containers; these names appear in
example prompts and commands. (See Running Hyperledger Grid on
Splinter or Running Hyperledger Grid on
Sawtooth for more information.)
If you are not using this example environment, replace these items with the actual values for your environment when entering each command.
Connect to a Grid Node
-
Connect to the first node’s
gridd
container and start a bash session.For the example environment, use this command to connect to the
gridd-alpha
container and run Grid commands onalpha-node-000
.$ docker exec -it gridd-alpha bash root@gridd-alpha:/#
Set Up Your Environment
Set the following Grid environment variables to specify information for the
grid
commands in this procedure.
-
Set
GRID_DAEMON_KEY
to the base name of your public/private key files (the example environment usesalpha-agent
). This environment variable replaces the-k
option on thegrid
command line.root@gridd-alpha:/# export GRID_DAEMON_KEY="alpha-agent"
Note: Although this variable has “daemon” in the name, it should reference the user key files in
$HOME/.grid/keys
, not the Grid daemon’s key files in/etc/grid/keys
. -
Set
GRID_DAEMON_ENDPOINT
to the Grid daemon’s endpoint (URL and port), such ashttp://localhost:8080
. This environment variable replaces the-url
option on thegrid
command line.root@gridd-alpha:/# export GRID_DAEMON_ENDPOINT="http://localhost:8080"
-
For Grid on Splinter, set
GRID_SERVICE_ID
to the fully qualified service ID (such as01234-ABCDE::gsAA
) for the scabbard service on the circuit. This environment variable replaces the--service_id
option on thegrid
command line.root@gridd-alpha:/# export GRID_SERVICE_ID="01234-ABCDE::gsAA"
Tip: See Prerequisites for the
splinter
commands that display the circuit ID and four-character service ID string.
Define and Create a Schema
-
Create a schema definition file, in YAML format, that specifies the following information:
- Schema name, such as
gs1_product
(this string tells Grid that the schema will use the GS1 namespace and will be associated with all GS1 products) - Description
- Set of item properties (each with a name, data type, and value
that conforms to the data type)
- name: gs1_product description: GS1 product schema properties: - name: product_name data_type: STRING description: "" required: true - name: image_url data_type: STRING description: "" required: false - name: brand_name data_type: STRING description: "" required: true - name: product_description data_type: STRING description: "" required: true - name: gpc data_type: NUMBER number_exponent: 1 description: "" required: true - name: net_content data_type: STRING description: "" required: true - name: target_market data_type: NUMBER number_exponent: 1 description: "" required: true
Tip: Use a YAML linter to validate the new file is formatted correctly.
- Schema name, such as
-
Use
docker cp
to copy the file into thegridd-alpha
container.$ docker cp product_schema.yaml gridd-alpha:/
-
Add the new schema as defined in the YAML file (for example,
product_schema.yaml
).root@gridd-alpha:/# grid schema create product_schema.yaml
This command creates and submits a transaction to add the schema to the distributed ledger. If the transaction is successful, all other nodes in the circuit can view the schema.
Display Schema Information
-
List all existing schemas to verify that the new schema has been added.
root@gridd-alpha:/# grid schema list
-
To see the details for a specific schema, use
grid schema show
with the schema name (such asgs1_product
).root@gridd-alpha:/# grid schema show gs1_product
-
(Optional) You can connect to a different node and repeat the last two commands to verify that the schema has been shared with all nodes on the circuit.
a. Open a new terminal and connect to the other node’s
gridd
container (such asgridd-beta
).$ docker exec -it gridd-beta bash
b. Set the
GRID_SERVICE_ID
environment variable to the full service ID for this node (such as01234-ABCDE::xyBB
).root@gridd-beta:/# export GRID_SERVICE_ID="01234-ABCDE::xyBB"
c. Display all schemas. The output should be the same as on the first node.
root@gridd-beta:/# grid schema list
d. Display the details of a specific schema (such as
gs1_product
).root@gridd-beta:/# grid schema show gs1_product
Update a Schema
To change a schema, you must be an agent for the organization that is identified in the schema definition.
-
Modify the definition in the schema YAML file (such as
product_schema.yaml
).You don’t have to use the same file that was used to create the schema, but the file must specify the same name and present the properties in the same order.
-
Use the
update
subcommand forgrid schema
to submit the YAML file’s changes to the distributed ledger.root@gridd-beta:/# grid schema update product_schema.yaml
Next Steps
Once you have an a product schema, you can create products based on this schema. For more information, see Creating Products.