انتقل إلى المحتوى الرئيسي

Subjects 101

Subjects form the foundation of decentralized development in Grams. Subjects is an interface definition language and a set of tools that allows developers to build decentralized applications in multiple programming languages. A Subjects model enables developers to compose varied viewpoints for defining and managing their application's state and behavior, as well as to define interaction rules.

Anatomy of a Subject​

The term “subject” defines the idea of reflecting a smaller, more focused perception of a complex shared model, including:

  • State: Represents current data or status.
  • Behavior: Dictates the Subject's actions.
  • Triggers: Events a Subject can initiate.
  • Subscriptions: Monitors specific events to invoke certain behaviors.

Example of a Subject Model​

subject Organization {
   version: "1.0.0"
   states: [Team]
   behaviors: [JoinTeam]
}

state Team {
   members: TeamMembers
}

list TeamMembers {
   member: TeamMember
}

structure TeamMember {
   @required
   name: string
}

behavior JoinTeam {
   input: string
}
What's this syntax?

Subject models are defined using either the Subjects IDL or the JSON AST. The JSON AST representation of a model is typically an artifact created by build tools to make them easier to use by other tooling.

Getting Started with Subjects​

  • Desktop App: For a visual approach, our application interface is available for download.
  • CLI: For terminal enthusiasts:
    npm install -g @grams-dev/subjects
    gsx create myNamespace # or use 'gsx init myNamespace' to add it to your existing package

Creating a new subject namespace will create the below folder structure in the terminal's working directory:

- myNamespace/
   - subjects/
      - myNamespace.subject
   - .gitignore
   - subjects-build.json
   - package-lock.json
   - package.json
   - README.md
   - tsconfig.json

Subjects are declared inside a namespace to provide an encapsulation for multiple subjects and contracts within an application. We therefore recommend using gsx at the root of your npm package.

Want a complete dApp?

Try out our package manager gpm which simplifies creating and managing complete decentralized applications.

Shapes and Traits​

A Subjects model consists of shapes and traits. Shapes are instances of types. Traits are used to add more information to shapes that might be useful for transpiling, building, or documentation.

Shapes​

Shape types are grouped into three categories:

  • Simple types: Simple types are types that do not contain nested types or shape references.
  • Aggregate types: Aggregate types contain configurable member references to others shapes.
  • Subject types: Types that define a Subject and its nested members like state and behaviors.

Traits​

Trait types are grouped into five core categories, but you can create as many as you would like!

Building the model​

You can build your model against any of the supported plugins, or even create your own plugin. Simply run:

gsx build

Building a more customized Subjects model requires modifying the configuration file, subjects-build.json. This file is used to describe how a model is created and what projections of the model to create, as well as which plugins to run.

The following is an example subjects-build.json configuration:

{
   "namespace": "my.namespace"
   "version": "1.0",
   "license": "Apache-2.0",
   "sources": ["subjects"],
   "plugins": [
      {
         "name": "ast",
         "outputDirectory": "model"
      },
      {
         "name": "typescript",
         "outputDirectory": "client"
      },
      {
         "name": "solidity",
         "outputDirectory": "contracts"
      }
   ]
}

Next Steps​

There's plenty more to explore in Subjects. The Subjects specification can teach you everything you need to know about the Subjects model. Guides can teach you more about the build process, including how to use transformations, projections, plugins, and more. Advanced Guides will cover topics including managing registeries and creating custom plugins.