Open Data Model Schema

The schema uses part of the GraphQL type type definition.

Note

The Open Data Model does not support GraphQL arguments.

The schema defines the structure of the custom model, which consists on:

If you intent to put comments in your schema, please have a look at the recommended way to do it.

There is a schema sample that contains all the definitions detailed below.

Node types

A node type is declared by the following syntax:

type Type_name { 
}

Type_name : the type of the node which represents the name of the custom type. It could be any name satisfying the following rules:

  1. must start with an upper-case letter
  2. may not contain white spaces (blank, tabs)
  3. may not start with "DH_" in order to avoid confusion with internal Data Hub types
  4. may not be one of the reserved types
Reserved type Name Description
Query reserved for queries definition
Mutation reserved for mutations definition
DataHubSite reserved Data Hub type
DataHubSource reserved Data Hub type
DataHubVariable reserved Data Hub type

There can be multiple type definitions in a single schema.

Node properties

A node property is declared, within a node type, by the following syntax:

type Type_name {
    Property_name : property_type
}

Property_name : the name of a node property which represents the name of the custom type property. It could be any name satisfying the following rules:

  1. must start with letter, ideally upper-case (by convention)
  2. may not contain white spaces (blank, tabs)

property_type is the type of the property, which can be a scalar, a custome node or a built-in Data Hub type.

There can be multiple properties in a single node.

According to GraphQL modifiers, '!' indicates that the property will never be null and [] indicates a list of types.

Scalar types

A scalar type is one of the GraphQL scalar types or "DateTime".

Important

The type names are case-sensitive

Type Name Description
Int A signed 32‐bit integer
Float A signed double-precision floating-point
String A UTF‐8 character sequence
Boolean true or false
ID Either a String or an Int
DateTime A string that represents a Date and Time in a sortable way, i.e yyyy-MM-dd hh:mm:ss

Data Hub node types

Data Hub types are the ones that represent the native Data Hub entities.

Data Hub node type Data Hub native entity Properties
DataHubSite Site Properties
DataHubSource Source Properties
DataHubVariable Variable Properties

Relations

Relation are expressed by GraphQL directives. They are allowed on custom and built-in Data Hub node types only and can be either direct or traversal.

Direct relation

A direct relation defines a direct link between one node type and another node type. Such a relation has a mandatory type and some optional properties that may "qualify" the relation. The declaration is

    @direct_relation(Type: "relation_type" Direction: IN/OUT Prop1:type Prop2:type ...)

relation_type : the name of the relation. It could be any name satisfying the following rules:

  1. must start with a letter
  2. may not contain white spaces (blank, tabs)
  3. may not start with "DH_" in order to avoid confusion with internal Data Hub relations

IN/OUT: IN to specify that the relation enters the node, OUT to specify that the relation leaves the node. If the Direction is not specified, it will be OUT by default.

Prop1 and Prop2: some optional properties attached to the relation.

type: one of the scalar types, nodes types are not allowed.

Here is an example of such a direct relation definition

type ParentNode {
    ...
    Children : [ChildNode] @direct_relation(Type: "PARENT_OF" Age:Int Direction: OUT)
}
type ChildNode {
    ...
}

Traversal relation

A traversal relation defines a possible link between 2 nodes (source and destination) that are not directely connected. The Open Data Model engine will start from the source node and will try to reach the destination node doing a maximum number of hops (default is 5). All destination nodes that are reachable and that have an incoming/outgoing relation of the specified type(s) will be considered as linked to the source node.

The declaration is

    @traverse_relation(Type: "relation_type" Depth: depth)

relation_type: the type of relation that must touch the destination nodes. It could be a single type or a comma-separated list of type. In this last case, the type condition will be ORed.

depth : the maximum hops allowed to reach the destination node from the source node. It must range between 1 and 10, defaut is 5 if omitted.

Here is an example of such a traversal relation

type ParentNode {
    ...
    Children : [ChildNode] @traverse_relation(Type: "MEMBER_OF_GROUP" Depth:3)
}
...
type ChildNode {
    ...
}

Accessing Form values

Data Hub provides Forms on native site and source entities. The schema can declare a Form value by extending the built-in Data Hub node type containing the form and by specifying the full part of the form value using an dh_form directive, as follow:

extend type DataHubSource {
    form_field_name: scalar_type @dh_form(Form: "form_name", Group: "group_name", Field: "field_name")
}

form_field_name is a free name that must comply with the node property rules.

scalar_type is the scalar type of the form field.

form_name, group_name and field_name are respectively the Form, Group and Field name of the form field. Once done, DataHubSource now contains an additional property named form_field_name that can be used is queries.

There can be multiple form fields defined on DataHubSite and/or DataHubSource.

Accessing relation properties

As explained in relations definition, relations may contain properties that can be used as filter in queries. There is also a way to get the value of such properties using relation_field directive, like this:

type Node {
    property_name : scalar_type @relation_field(RelationType: relation_type, FieldName: field_name)
}

property_name is a free name that must comply with the node property rules.

scalar_type is the scalar type of the property.

relation_type is the type of the relation owning the property named field_name.

Important
  • The Node must be a target of the relation.
  • If multiple relations of the type relation_type target a node, the node will be repeated in the output as many time as the number of relations reaching the node. Each node instance will contain the same properties except the one reflecting the relation.

Here is a sample of accessing relation property

type ParentNode {
    ...
    ParentNode : [ChildNode] @direct_relation(Type: "PARENT_OF" Age:Int)
}
type ChildNode {
    AgeFromRelation : Int @relation_field(RelationType: "PARENT_OF" FieldName: "Age")
}

Queries

The query definition follows the GraphQL query standard but does not support GraphQL arguments

Important

Query is case-sensitive

Example:

type Query {
	Customers : [Customer]
	Regions : [Region]
}