SHEX-ORM Schema

CLI tool to convert SHEX shapes to schemas and TypeScript definitions (“shape types”) that can be used for creating graph ORM objects.

How to Use

Install @ng-org/shex-orm as dev dependency or globally (--global).

npm install --save-dev @ng-org/shex-orm

Then run

npx rdf-orm build --input ./src/shapes/shex --output ./src/shapes/orm

The input directory needs to contain shex files with one or more shape definitions each, for example:

PREFIX ex: <http://example.org/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

ex:ExpenseShape {
  a [ex:Person] ;                  # Required type <http://example.org/Person>
  ex:name xsd:string ;             # Required string
  ex:email xsd:string * ;          # Zero or more strings (set)
  ex:height xsd:float ;            # Required number
  ex:age xsd:integer ;             # Required integer
  ex:friends IRI * ;               # Set of IRIs
  ex:isRecurring xsd:boolean ;     # A boolean value
  ex:address @ex:AddressShape ;    # A nested object shape.
  ex:paymentStatus [ex:Paid ex:Pending ex:Overdue] ; # Enum
}

# In the same or another file...
ex:AddressShape EXTRA a {
  a [ ex:Address ] ;
  ex:name xsd:string ;
}

SHEX Cardinality Reference

Syntax	Meaning	TypeScript Type
`prop xsd:string`	Required, exactly one	`string`
`prop xsd:string ?`	Optional, zero or one	`string \| undefined`
`prop xsd:string *`	Zero or more	`Set<string>`
`prop xsd:string +`	One or more	`Set<string>` (non-empty)
`prop IRI`	Reference to another object	`string` (IRI)
`@ex:PersonShape`	nested object	`Person`

The output directory will contain the typescript files with type definitions and the converted schema.

You will then pass the shape type of a shape definition to the ng sdk:

import { useShape } from "@ng-org/orm/react";
import { TestObjectShapeType } from "../shapes/orm/testShape.shapeTypes";

export function TestComponent() {
    const testObjects = useShape(TestObjectShapeType, {graphs: ["did:ng:i"]});
    ...
}

For an example, see the expense-tracker-graph example application.

Generated Output

For each SHEX file, the tool creates three TypeScript files:

A schema file like person.schema.ts
A typings file like person.typings.ts
A shape type file like person.shapeTypes.ts which contains a ShapeType that consists of the schema, the type, and the IRI of the main shape. This is what you pass to the ORM.

The transformers for converting SHEX to schema and typings files are based on @ldo/traverser-shexj.

Default Properties

@type: The RDF type IRI (from rdf:type) is always converted to the property name @type by default
@id (subject IRI) and @graph (graph NURI): These properties are automatically added to all typed objects as readonly properties

Cardinality Handling

Predicates with a cardinality higher than 1 (i.e., maxCardinality > 1 or maxCardinality === -1 for unlimited) are represented as TypeScript Set<T> types.

Reference

Interfaces

BaseType

Defined in: types.ts:23

The base type that all generated objects inherit from.

Extends

Record<string, any>

Indexable

[key: string]: any

Properties

@id

@id: string

Defined in: types.ts:25

The IRI of the subject.

Predicate

Defined in: types.ts:54

The schema of a property.

Properties

dataTypes

dataTypes: DataType[]

Defined in: types.ts:56

Allowed type of object. If more than one is present, either of them is allowed.

extra?

optional extra: boolean

Defined in: types.ts:66

If other (additional) values are permitted. Useful for literals.

iri

iri: string

Defined in: types.ts:58

The RDF predicate URI.

maxCardinality

maxCardinality: number

Defined in: types.ts:62

Maximum allowed number of values. -1 means infinite.

minCardinality

minCardinality: number

Defined in: types.ts:64

Minimum required number of values.

readablePredicate

readablePredicate: string

Defined in: types.ts:60

The alias of the predicateUri when serialized to a JSON object.

Shape

Defined in: types.ts:36

Shape of an object.

Properties

iri

iri: string

Defined in: types.ts:38

The ID (IRI) of the shape.

predicates

predicates: Predicate[]

Defined in: types.ts:40

The predicates (properties) of the shape.

ShapeType

Defined in: types.ts:15

The ORM shape type generated from a SHEX schema with rdf-orm build --input ./path/to/shex-files --output ./path/to/shape-types

Type Parameters

T

T extends BaseType

Properties

schema

schema: Schema

Defined in: types.ts:17

The schema object of the shape.

shape

shape: string

Defined in: types.ts:19

The ID (IRI) of the shape.

Type Aliases

DataType

DataType = object

Defined in: types.ts:44

An allowed data type or literal.

Properties

literals?

optional literals: number[] | string[] | boolean

Defined in: types.ts:46

The required literal value(s). Additional values are allowed, if extra is true.

shape?

optional shape: string | Shape

Defined in: types.ts:48

If valType is "shape", the nested shape or its reference. Use reference for serialization.

valType

valType: "number" | "string" | "boolean" | "iri" | "shape"

Defined in: types.ts:50

The type of object value for a triple constraint.

Schema

Schema = object

Defined in: types.ts:31

Index Signature

[id: string]: Shape