Creating and Updating 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.
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,
beta-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
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 ID
The Grid daemon’s endpoint (URL and port) on one or both nodes. This procedure uses
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 by
grid keygen). The example environment uses the key files
$HOME/.grid/keys/alpha-agent.pubto indicate that you will be acting as your organization’s agent to add schemas from the alpha node.
IMPORTANT: The commands in this procedure show host names, IDs, Docker
container names, and other values from the example Grid environment that are
This file sets up the nodes
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
griddcontainer and start a bash session.
For the example environment, use this command to connect to the
gridd-alphacontainer and run Grid commands on
$ 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.
GRID_DAEMON_KEYto the base name of your public/private key files (the example environment uses
alpha-agent). This environment variable replaces the
-koption on the
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
GRID_DAEMON_ENDPOINTto the Grid daemon’s endpoint (URL and port), such as
http://localhost:8080. This environment variable replaces the
-urloption on the
root@gridd-alpha:/# export GRID_DAEMON_ENDPOINT="http://localhost:8080"
For Grid on Splinter, set
GRID_SERVICE_IDto the fully qualified service ID (such as
01234-ABCDE::gsAA) for the scabbard service on the circuit. This environment variable replaces the
--service_idoption on the
root@gridd-alpha:/# export GRID_SERVICE_ID="01234-ABCDE::gsAA"
Tip: See Prerequisites for the
splintercommands 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)
- 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 owner: myorg properties: - name: GDSN_3_1 data_type: STRING description: A string containing a GDSN 3.1 Trade Item product definition in XML format. required: true
Tip: Use a YAML linter to validate the new file is formatted correctly.
- Schema name, such as
docker cpto copy the file into the
$ docker cp product_schema.yaml gridd-alpha:/
Add the new schema as defined in the YAML file (for example,
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 showwith the schema name (such as
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
griddcontainer (such as
$ docker exec -it gridd-beta bash
b. Set the
GRID_SERVICE_IDenvironment variable to the full service ID for this node (such as
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
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 and have the “schema::can-update-schema” permission.
IMPORTANT: When updating a schema, the update file must only contain new property definitions; it cannot list or attempt to modify an existing property definition. Existing properties may not be removed or modified in order to preserve the validity of existing data.
- Create an update schema YAML file (such as
product_schema_update.yaml) with the same name and owner as before and the new property you’d like to add. For example:
- name: gs1_product owner: myorg properties: - name: my_new_property data_type: STRING description: New information that may be included. required: false ``` 1. Use `docker cp` to copy the file into the `gridd-alpha` container.
$ docker cp product_schema_update.yaml gridd-alpha:/
1. Use the `update` subcommand for `grid schema` to submit the YAML file's updates to the distributed ledger.
root@gridd-alpha:/# grid schema update product_schema_update.yaml
1. Use the `show` subcommand to view the update.
root@gridd-alpha:/# grid schema show gs1_product ```
Once you have an a product schema, you can create products based on this schema. For more information, see Creating Products.