JavaScript IPLD Schema parser, validator, and code generator.
IPLD Schemas define a type system for content-addressed data. Think of them like TypeScript or Protocol Buffers, but designed for immutable, linked data structures. They help you:
- 🛡️ Validate that your data matches an expected structure
- 🔄 Transform between compact binary formats and developer-friendly JSON
- 🏗️ Generate type-safe code in multiple languages (Go, Rust, TypeScript)
- 🔗 Link between data structures using content identifiers (CIDs)
Learn more at https://ipld.io/docs/schemas/
- Parse and validate IPLD Schema DSL (Domain Specific Language)
- Runtime validation with automatic format conversion
- Code generation for Go, Rust, and TypeScript
- Advanced type features: optional fields, defaults, renames, type aliases
- Multiple data representations for space-efficient storage
- CLI tools for validation and code generation
npm install @ipld/schemaFor CLI usage:
npm install -g @ipld/schemaIPLD Schemas use a simple, readable syntax:
import { fromDSL } from '@ipld/schema/from-dsl.js'
import { create } from '@ipld/schema/typed.js'
// Define your schema
const schema = fromDSL(`
# A simple user profile schema
type UserProfile struct {
username String
email String
age Int
isActive Bool
}
`)
// Create a validator
const validator = create(schema, 'UserProfile')
// Validate some data
const userData = {
username: 'alice',
email: 'alice@example.com',
age: 25,
isActive: true
}
const validatedData = validator.toTyped(userData)
if (validatedData === undefined) {
console.error('Invalid data!')
} else {
console.log('Valid user profile:', validatedData)
}type MyString String # UTF-8 string
type MyInt Int # Signed integer
type MyFloat Float # Floating point
type MyBool Bool # Boolean
type MyBytes Bytes # Binary data
type MyLink &Any # IPLD Link (CID)
type Person struct {
name String
age Int
email String optional # Optional field
nickname String (implicit "") # Default value
}
# List of strings
type Names [String]
# Map from string to integers
type Scores {String: Int}
# Nested structures
type Team struct {
name String
members [Person]
metadata {String: String}
}
type Status enum {
| Active
| Inactive
| Pending
}
# With custom string values
type Color enum {
| Red ("red")
| Green ("green")
| Blue ("blue")
} representation string
type UserID = String
type Timestamp = Int
type EmailAddress = String
IPLD Schemas separate the logical structure (what developers work with) from the storage format (how it's encoded). This allows for space-efficient storage while maintaining developer-friendly APIs.
import { fromDSL } from '@ipld/schema/from-dsl.js'
import { create } from '@ipld/schema/typed.js'
const schema = fromDSL(`
# Store as array instead of object to save space
type Point struct {
x Float
y Float
} representation tuple
`)
const validator = create(schema, 'Point')
// Work with nice objects in your code
const point = { x: 10.5, y: 20.3 }
// But it's stored as a compact array
const stored = validator.toRepresentation(point)
console.log(stored) // [10.5, 20.3]
// And automatically converted back
const restored = validator.toTyped(stored)
console.log(restored) // { x: 10.5, y: 20.3 }Generate type-safe code from your schemas:
import { fromDSL } from '@ipld/schema/from-dsl.js'
import { generateGo } from '@ipld/schema/gen/go.js'
const schema = fromDSL(`
type Person struct {
name String
age Int optional
}
`)
const goCode = generateGo(schema, { packageName: 'person' })
// Generates Go structs with proper JSON tags and pointer types for optionalsimport { generateRust } from '@ipld/schema/gen/rust.js'
const rustCode = generateRust(schema)
// Generates Rust structs with serde derives and Option<T> for optionalsimport { generateTypeScript } from '@ipld/schema/gen/typescript.js'
const tsCode = generateTypeScript(schema)
// Generates TypeScript interfaces and runtime validatorsControl JSON field names separately from your schema field names:
type ServerConfig struct {
serverPort Int (rename "server_port")
debugMode Bool (rename "debug_mode")
apiKey String (rename "api_key")
}
Add language-specific type information:
# Use big integers in Go
# @gotype(big.Int)
type Balance Int
type Transaction struct {
# Custom serialization in Rust
# @rustserde(with = "chrono::serde::ts_seconds")
timestamp Int
# Multiple annotations
# @gotag(`json:"tx_id" db:"transaction_id"`)
id String
}
Handle special encoding requirements:
const customTransforms = {
Base64String: {
// Decode base64 strings to bytes
toTyped: (str) => {
try {
return Uint8Array.from(atob(str), c => c.charCodeAt(0))
} catch {
return undefined
}
},
// Encode bytes to base64 strings
toRepresentation: (bytes) => {
return btoa(String.fromCharCode(...bytes))
}
}
}
const validator = create(schema, 'MyType', { customTransforms })The ipld-schema command provides tools for working with schemas:
# Validate schema files
ipld-schema validate schema.ipldsch
# Extract and validate schemas from markdown
ipld-schema validate README.md# Convert to JSON format
ipld-schema to-json schema.ipldsch
# Pretty print as canonical schema
ipld-schema to-schema schema.ipldsch# Generate JavaScript validators
ipld-schema to-js schema.ipldsch
# Generate TypeScript definitions
ipld-schema to-tsdefs schema.ipldschfromDSL(dsl: string)- Parse schema DSL into an ASTtoDSL(schema: Schema)- Convert AST back to DSL
create(schema: Schema, type: string, options?)- Create a validator- Returns
{ toTyped, toRepresentation } toTyped(data)- Validate and convert from storage formattoRepresentation(data)- Validate and convert to storage format
- Returns
generateGo(schema, options)- Generate Go codegenerateRust(schema, options)- Generate Rust codegenerateTypeScript(schema, options)- Generate TypeScript code
Copyright 2019-2025 Rod Vagg
Licensed under either of
- Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
- MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.