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.
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 and 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 alpha-node-000 and beta-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 ID 01234-ABCDE::gsAA.
The Grid daemon’s endpoint (URL and port) on one or both nodes. This procedure uses https://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 by grid 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 on Splinter environment that is defined by grid/examples/splinter/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 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 on alpha-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 uses alpha-agent). This environment variable replaces the -k option on the grid 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 as http://localhost:8080. This environment variable replaces the -url option on the grid 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 as 01234-ABCDE::gsAA) for the scabbard service on the circuit. This environment variable replaces the --service_id option on the grid 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)

The following example shows how to use cat to 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.

Add the new schema as defined in the YAML file (for example, product_schema.yaml).
```
 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 show with the schema name (such as gs1_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 as gridd-beta).
```
   $ docker exec -it gridd-beta bash
```
b. Set the GRID_SERVICE_ID environment variable to the full service ID for this node (such as 01234-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 for grid 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.