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 on Splinter environment
that is defined by
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 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)
The following example shows how to use
catto create the file
product_schema.yaml, with sample contents that match the product definition shown in Creating Products.
root@gridd-alpha:/# cat > product_schema.yaml - name: gs1_product description: GS1 product schema properties: - name: product_name data_type: STRING description: Consumer friendly short description of the product suitable for compact presentation. required: true - name: image_url data_type: STRING description: URL link to an image of the product. required: false - name: brand_name data_type: STRING description: The brand name of the product that appears on the consumer package. required: true - name: product_description data_type: STRING description: "An understandable and useable description of a product using brand and other descriptors. This attribute is filled with as little abbreviation as possible, while keeping to a reasonable length. This should be a meaningful description of the product with full spelling to facilitate essage processing. Retailers can use this description as the base to fully understand the brand, flavour, scent etc. of the specific product, in order to accurately create a product description as needed for their internal systems. Examples: XYZ Brand Base Invisible Solid Deodorant AP Stick Spring Breeze." required: true - name: gpc data_type: NUMBER number_exponent: 1 description: 8-digit code (GPC Brick Value) specifying a product category according to the GS1 Global Product Classification (GPC) standard. required: true - name: net_content data_type: STRING description: The amount of the consumable product of the trade item contained in a package, as declared on the label. required: true - name: target_market data_type: NUMBER number_exponent: 1 description: ISO numeric country code representing the target market country for the product. required: true
Tip: Enter CTRL-C to exit and save the contents.
- Schema name, such as
Add the new schema as defined in the YAML file (for example,
root@gridd-alpha:/# grid schema create product_schema.yaml
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.
Modify the definition in the schema YAML file (such as
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.
grid schemato submit the YAML file’s changes to the distributed ledger.
root@gridd-beta:/# grid schema update product_schema.yaml
Once you have an a product schema, you can create products based on this schema. For more information, see Creating Products.