Overview

■●■ GraphDL - Graph Definition Language

GraphDL is a full-stack language for defining data models and the relationships between them. It support the intuitive and natural expressiveness of a graph database, the flexibility of the document database, and the constraints with foreign keys and referential integrity of a relational database. The format is YAML with embedded JavaScript/TypeScript & JSX/HTML, and supports URL-based imports to compose Graphs together, as well as import any ES6 JavaScript module.

Examples

graphdl.yaml
User:
 _id:   email
 _name: ${name} <${email}>
 _icon: 🧑
 _sameAs: https://schema.org/Person
 name:  name
 email: email
 image: url
 posts: [Post.author]
 
Post:
 _id:         slugify(Title)
 _name:       title
 _icon:       📋
 _sameAs:     https://schema.org/BlogPosting
 title:       name
 description: description
 tags:        [string]
 content:     articleBody
 createdAt:   dateCreated
 createdBy:   creator
 author:      User.Email

JavaScript code is a native part of GraphDL, and GraphDL Schema is transpiled into a JavaScript Module with full TypeScript support. JSON Schema, OpenAPI, GraphQL, a Website, a React Admin App, and Documentation can also be optionally generated.

graphdl.yaml
✅ ToDo:
    title:       string!
    description: string
    status:      To Do | In Progress | Blocked | Done = To Do
    subtasks:    [ToDo->partOf]
    partOf:      ToDo.subtasks
    assignedTo:  User.assigned = createdBy()
    createdBy:   User.created = createdBy()
 
🧑‍💻 User:
    _sameAs:     https://schema.org/Person
    name:        string
    email:       email!
    assigned:    [ToDo->assignedTo]
    created:     [ToDo->createdBy]

The generated Javascript and Typescript code includes the base data models, as well as Validation logic, List, Search, Create, Update, & Delete logic for client and/or server side use, including APIs,

That can be deployed anywhere including Cloudflare Workers, Deno Deploy, Fly.io, AWS, Azure, GCP or with self-hosted containers

Nouns are the things in a Graph. Every Noun has Properties that describe its attributes. Nouns relate to each other through Verbs. Triggers are the potential Events that can happen to a Noun. A Resource is a specific instance of a Noun, and an Action is a specific instance of a Verb relating to specific instances of Nouns, and an Event is an instance of a Trigger.

■● Graph

A Graph is a collection of Nouns and Verbs that describe the relationships between Nouns.

■ Noun

A Noun is a person, place, thing, or idea and has Properties that describe it.

Customer:
  name: string
  email: email
  phone: phone
  notes: markdown

□ Resource

A Resource is a specific instance of a Noun and can be stored or transmitted in JSON as Data

For example, in User/john the Resource is john and the Noun is User.

{
  "_type": "User",
  "_id": "john",
  "name": "John Doe",
  "email": "[email protected]"
}

∷ Property

A Property are the attributes that describe a Noun or Verb. Properties that start with and underscore (_) like _type, _sameAs, or _icon or mean that they are internal properties that that describe the Noun or Verb and cannot be changed on any given Resource with the exception of _id which must be unique for every Resource.

● Verb

A Verb connects a Noun to a different Noun, and is expressed as [Subject].[Verb]: [Object].

For example, in User.subscribes: App the verb subscribes connects the Subject User to the Object App.

○ Action

An [Action] happens when an instance of a [Noun] (i.e. [Resource]) does a [Verb] to a different [Resource].

For example, in User/john.subscribes: App/ToDos the verb subscribes connects the [Subject Resource] User/john to the [Object Resource] App/ToDos.

◆ Trigger

A [Trigger] invokes an [Action] on a [Schedule], when a [Resource] is created, modified, or deleted, or when an [Action] happens.

◇ Event

An [Event] happens whenever a [Trigger] happening at a specific point in time, and can occur at scheduled times, whenever a [Resource] is created, updated, or deleted, or whenever an [Action] happens.

⧆ Query

A [Query] is the input criteria for a [Search] in a [Graph] that may or may not be constrained to a specific [Noun] or [Verb]

⊛ Search

A [Search] is as [Action] that returns a list of [Resources] that match a specific [Query].

入 API

An [API] is a [Function] that can be passed [Data] via a [Request] and returns [Data] in a [Response].

⬮ Integration

An [Integration] connects a [Graph] to a third-party [Provider] and can be used with [Triggers], [Searches], and [Actions] data.

⬯ Provider

A [Provider] is a third-party service that can be connected to a [Graph] via an [Integration].

❴❵ Data

[Data] is the information that is stored in a [Resource] in a JSON format.

❪❫ Function

A [Function] is Javascript code that can be placed on a [Verb] is executed when an [Action] happens.

❮❯ UI

A [UI] is Function that returns HTML and can be placed on a [Noun] and is executed when a [Resource] is Viewed.

☶ Site

A [Site] is a publicly-accesible [UI] and can be deployed to the cloud, and run in the cloud, at the edge, or in a browser

⧉ App

An [App] is an composition of [UI] powered by [APIs] with [Users] and [Tenants], and that can be deployed to the cloud, and run in the cloud, at the edge, in a browser, or on a device.

☱ Docs

[Docs] are the documentation for a [Graph]'s [Nouns], [Verbs], [API] and [App] that can be deployed to the cloud to be viewed in a browser.

▼ Role

A [Role] describes the relationship between a [User] and a [Tenant] with specific [Permissions] relating to [Resources] and [Actions] on a [Graph].

▽ User

A [User] is a person who has a [Role] in a [Tenant] and can access [Resources] and perform [Actions] in a [Graph].

△ Tenant

A [Tenant] is a business or organization that has a [Role] in a [Graph] and can access [Resources] and perform [Actions] in a [Graph].