Domain Resources Design Document

[Swiddis]

Domain Resources: Creation and Usage

Introduction

The operation of SimpleSchema requires being able to create and query GraphQL Schemas that correspond to OpenSearch indices. A Schema represents a GraphQL service's type system capabilities, defining what operations are permitted in the service. This document explains the usage and architecture of Domains, the primary mechanism to configure and use GraphQL Schemas within SimpleSchema.

Usage

Domain Creation

A Domain's primary component is a Schema, which defines what operations the Domain needs to support. Creating a Domain requires providing a Schema, which is a collection of SchemaEntityTypes. The creation steps are:

1. Define Schema Entities that will be used in the Domain's Schema.

Schema Entity Types are created by POSTing them to the /object endpoint. The Entity needs a name, the appropriate type specifying that it's a SchemaEntityType, and GraphQL content.

// POST /_plugin/_simpleschema/object
{
	"schemaEntityType": {
		"name": "projectType",
		"type": "schemaEntityType",
		"content": "type Project { name: String \n tagline: String \n contributors: [User] }"
	}
}
// Response:
{
	"objectId": "sampleId12345"
}

2. Create a Domain

A domain needs a name, and a list of the desired SchemaEntityTypes. It's created by POSTing to the /domain endpoint.

// POST /_plugin/_simpleschema/domain
{
	"name": "projectDomain",
	"entityList": ["sampleId12345"]
}
// Response:
{
	"name": "projectDomain",
	"user": "author",
	"links": {
		"graphql": "domain/projectDomain/graphql",
		"index": "domain/projectDomain/index",
		"ontology": "domain/projectDomain/ontology"
	}
}

Domain Usage

The Domain's endpoint supports three functions: processing GraphQL queries (/graphql), reflecting the GraphQL schema (/ontology), and reflecting the underlying indices (/index). Some examples of these endpoints in action are provided below.

1. Queries

The Domain's /graphql endpoint will function as a normal GraphQL HTTP endpoint.

// GET /_plugin/_simpleschema/domain/projectDomain/graphql
{
	project(name: "SimpleSchema") {
		tagline
	}
}
// Response:
{
	"project": {
		"tagline": "A GraphQL Wrapper for OpenSearch"
	}
}

2. Ontology

The /ontology endpoint allows reflection on the Schema, such as getting the types.

// GET /_plugin/_simpleschema/domain/projectDomain/ontology
// Response:
{
	"projectDomain": {
		"types": {
			"Project": {
				"name": "String",
				"tagline": "String",
				"contributors": "[User]"
			}
		}
	}
}

3. Indices

The /index endpoint provides visibility on the underlying index mappings the Schema is using.

// GET /_pluin/_simpleschema/domain/projectDomain/index
// Response:
{
	"projectDomain": {
		"indices": [
			{
				"name": "sampleIndex",
				"mappings": [
					{
						"schema": {
							"path": "Project/name",
							"type": "String"
						},
						"index": {
							"path": "name",
							"type": "String"
						}
					},
					{
						"schema": {
							"path": "Project/tagline",
							"type": "String"
						},
						"index": {
							"path": "tagline",
							"type": "String"
						}
					},
					{
						"schema": {
							"path": "Project/contributors",
							"type": "[User]"
						},
						"index": {
							"path": "contributors",
							"type": "String"
						}
					}
				]
			}
		]
	}
}

Architecture

Domain Objects

Internally, the Domain object stores metadata necessary to fulfill the /graphql, /ontology, and /index functions. Its primary task is facilitating communication between the User and Core.

graph TD
	GR[GraphQL Request] --> Domain
	OR[Ontology Request] --> Domain
	IR[Index Request] --> Domain
	Domain ---> Core
	Core --> GraphQL
	Core --> Schema
	GraphQL --> Engine
	Schema --> Index
	Schema --> Ontology

Loading

It specifically contains:

• GraphQLEngine: The engine that translates GraphQL to internal query formats such as SQL or DSL.
  • The GraphQLEngine in turn contains a GraphQLSchema with the actual schema, and a TypeDefinitionRegistry that defines the types used in the schema.
  • The Engine also permits GraphQL Schema introspection.
• Schema: A structure containing references to Index and Ontology, used for further introspection.
  • Ontology is structure that defines Types, Relations, and Enums, essentially user-facing components.
  • Index is the structure defining connections to OpenSearch Indices, and also contains Mappings that allow translation between Indices and GraphQL Types.

Domain Compilation

Triggered by a Domain creation event, compilation involves the following steps:

1. GraphQL Type Templates are fetched from the System Index, populated with schemaEntityTypes.
2. Templates are combined into an Ontology object.
3. Indexs and Mappings are created to fulfill the requirements of the Ontology.
4. A Domain object is created and populated with the Ontology, Index set, and Mapping set.
5. The Domain object is serialized and stored in the System Index to be recoverable on new plugin instances.
6. The current Domain instance is cached in the current plugin instance.
7. The user is informed of the new domain name and endpoint.

As the Domain contains the GraphQLEngine, Ontology, and Index, it will contain methods for handling external requests and retrieving results from the appropriate objects. Examples of this are in the Workflows below.

Workflows

GraphQL Queries

Example flow for a user requesting a GraphQL query.

sequenceDiagram
    actor U as User
    participant S as Service
    participant DR as DomainRepository
    participant D as Domain
    participant E as Engine

    U ->> S: query { Book(id: 1) { ... } }
    S ->> DR: Get Book Domain
    DR ->> S: Book Domain
    S ->> D: Execute Query
    D ->> E: Form SQL Query
    E ->> D: SQL Query
    D ->> D: Execute Query
    D ->> S: Query Results
    S ->> U: { "id": 1, ... }

Loading

Ontologies

Example flow for a user viewing Ontology data.

sequenceDiagram
    actor U as User
    participant S as Service
    participant DR as DomainRepository
    participant D as Domain
    participant E as Ontology

    U ->> S: Get /ontology
    S ->> DR: Get Domain
    DR ->> S: Domain
    S ->> D: Format Ontology
    D ->> E: Format Ontology
    E ->> D: Formatted Ontology
    D ->> S: Formatted Ontology
    S ->> U: { "domainName": ... }

Loading

Indices

Example flow for a user viewing Index data.

sequenceDiagram
    actor U as User
    participant S as Service
    participant DR as DomainRepository
    participant D as Domain
    participant E as Index

    U ->> S: Get /index
    S ->> DR: Get Domain
    DR ->> S: Domain
    S ->> D: Format Indices
    D ->> E: Format Indices
    E ->> D: Formatted Indices
    D ->> S: Formatted Indices
    S ->> U: { "domainName": { "indices": [...] } }

Loading