Getting Started with TypeScript

Create your first health record, serialize it to RDF, and build a local Pod — in five minutes

Documentation / Getting Started / TypeScript
Cascade Protocol SDK v1.0 — Requires Node.js 18+. All processing runs locally on your machine.

Prerequisites

Before you begin, make sure you have the following installed:

✓
Node.js 18+
Runtime
✓
npm or yarn
Package manager
✓
TypeScript 5.4+
Optional, for type checking

Verify your Node.js version:

node --version
# v18.0.0 or higher
1

Install the SDK

Create a new project directory and install the Cascade Protocol SDK:

Terminal 
mkdir my-cascade-app && cd my-cascade-app
npm init -y
npm install @cascade-protocol/sdk

If you want to type-check your scripts with TypeScript, also install the compiler:

Terminal 
npm install -D typescript tsx
npx tsc --init

The SDK has zero runtime dependencies. It provides typed interfaces for all Cascade Protocol data types, vocabulary constants, and serialization utilities for RDF/Turtle format.

2

Create your first record

Create a file called create-record.ts and add the following. This creates a medication record and serializes it to RDF/Turtle format:

create-record.ts 
import { serialize } from '@cascade-protocol/sdk';
import type { Medication } from '@cascade-protocol/sdk';

// Create a medication record with required fields
const medication: Medication = {
  id: 'urn:uuid:' + crypto.randomUUID(),
  type: 'MedicationRecord',
  medicationName: 'Lisinopril',
  isActive: true,
  dose: '10 mg',
  frequency: 'Once daily',
  route: 'Oral',
  startDate: '2025-06-15T00:00:00Z',
  rxNormCode: 'http://www.nlm.nih.gov/research/umls/rxnorm/314076',
  dataProvenance: 'ClinicalGenerated',
  schemaVersion: '1.3',
};

// Serialize the record to RDF/Turtle
const turtle = serialize(medication);
console.log(turtle);

Run the script:

Terminal 
npx tsx create-record.ts
Expected output 
@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix health: <https://ns.cascadeprotocol.org/health/v1#> .
@prefix rxnorm: <http://www.nlm.nih.gov/research/umls/rxnorm/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890>
    a health:MedicationRecord ;
    health:medicationName "Lisinopril" ;
    health:isActive true ;
    health:dose "10 mg" ;
    health:frequency "Once daily" ;
    health:route "Oral" ;
    health:startDate "2025-06-15T00:00:00Z"^^xsd:dateTime ;
    health:rxNormCode <http://www.nlm.nih.gov/research/umls/rxnorm/314076> ;
    cascade:dataProvenance cascade:ClinicalGenerated ;
    cascade:schemaVersion "1.3" .

The serialize() function converts the typed JavaScript object into a complete Turtle document with the correct namespace prefixes, RDF types, and XSD datatype annotations. Each field maps to a predicate in the Cascade Protocol vocabulary.

About the UUID

Each record needs a unique id in URN UUID format. The crypto.randomUUID() function is built into Node.js 18+ and generates a cryptographically random identifier. Your actual output will show a different UUID than the example above.

3

Build a Pod

A Pod is the Cascade Protocol's local data container. It organizes health records into directories by category (clinical, wellness, profile) and generates an index file that describes the Pod's contents. Create a new file called build-pod.ts:

build-pod.ts 
import { PodBuilder } from '@cascade-protocol/sdk/pod';
import type { Medication } from '@cascade-protocol/sdk';
import { mkdirSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';

// 1. Create a medication record
const medication: Medication = {
  id: 'urn:uuid:' + crypto.randomUUID(),
  type: 'MedicationRecord',
  medicationName: 'Lisinopril',
  isActive: true,
  dose: '10 mg',
  frequency: 'Once daily',
  route: 'Oral',
  startDate: '2025-06-15T00:00:00Z',
  rxNormCode: 'http://www.nlm.nih.gov/research/umls/rxnorm/314076',
  dataProvenance: 'ClinicalGenerated',
  schemaVersion: '1.3',
};

// 2. Build the Pod
const pod = new PodBuilder({
  title: 'My Health Pod',
  description: 'Getting started example',
});

pod.addMedication(medication);
const files = pod.build();

// 3. Write all files to disk
for (const file of files) {
  const fullPath = join('./my-pod', file.path);
  mkdirSync(dirname(fullPath), { recursive: true });
  writeFileSync(fullPath, file.content);
}

console.log('Pod created with', files.length, 'files:');
for (const file of files) {
  console.log('  ', file.path);
}

Run it:

Terminal 
npx tsx build-pod.ts
Expected output 
Pod created with 2 files:
   clinical/medications.ttl
   index.ttl

The PodBuilder handles:

  • File routing: Medications go to clinical/medications.ttl, vital signs from devices go to wellness/vital-signs.ttl, and so on.
  • Prefix merging: When multiple records of the same type are added, their Turtle output is merged into a single file with shared namespace prefixes.
  • Index generation: An index.ttl file is created that describes the Pod container using the W3C Linked Data Platform vocabulary.

Pod structure

After running the script, your my-pod directory contains:

my-pod/
  index.ttl — Pod manifest (LDP container description)
  clinical/
    medications.ttl — Your medication record as RDF/Turtle

You can inspect the generated Turtle file directly:

Terminal 
cat my-pod/clinical/medications.ttl
4

Verify with the CLI

The Cascade Protocol CLI includes a SHACL-based validator that checks your Pod against the protocol's constraint shapes. Install it globally and validate your Pod:

Terminal 
# Install the CLI globally
npm install -g @cascade-protocol/cli
Terminal 
# Validate the Pod structure and data
cascade validate ./my-pod
Expected output 
Validating Pod at ./my-pod ...

  clinical/medications.ttl  1 record   PASS
  index.ttl                 container  PASS

Result: 1 file validated, 0 errors, 0 warnings

You can also inspect the Pod metadata:

Terminal 
# View Pod metadata
cascade pod info ./my-pod

The validator uses SHACL (Shapes Constraint Language) to verify that each record conforms to the Cascade Protocol schema. It checks required fields, data types, value constraints, and vocabulary usage.

What happened to your data?

Everything just happened locally on your machine.

  • Your medication record was written to ./my-pod/clinical/medications.ttl as RDF/Turtle.
  • No data was sent to any server. The SDK and CLI operate entirely offline.
  • No account was created. There is no sign-up, no API key, and no telemetry.
  • You can delete ./my-pod to remove everything: rm -rf ./my-pod

Read the Security & Compliance Guide for a full description of the trust model and data flow architecture.

← Back to Documentation