# @ipld/schema

> IPLD Schema parser and CLI utilities for JavaScript

Latest version **7.0.12** (published 2026-03-30) · (Apache-2.0 AND MIT) license · 0 weekly downloads

## Install

```sh
npm install @ipld/schema
pnpm add @ipld/schema
yarn add @ipld/schema
bun add @ipld/schema
```

Provides the command `ipld-schema`.

## Health

**Score 55/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 7.0.12 |
| Published | 2026-03-30 |
| First published | 2022-08-19 |
| Weekly downloads | 0 |
| License | (Apache-2.0 AND MIT) |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 754.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Rod |
| Maintainers | daviddias, mikeal, vmx, alanshaw, achingbrain, vascosantos, rvagg, lidel, npm-service-account-ipld |

## Links

- npm: https://www.npmjs.com/package/@ipld/schema
- Repository: https://github.com/ipld/js-ipld-schema
- Homepage: https://github.com/ipld/js-ipld-schema#readme
- Issues: https://github.com/ipld/js-ipld-schema/issues
- npm.io page: https://npm.io/package/@ipld/schema

## Dependencies (3)

- [yargs](https://npm.io/package/yargs.md) ^18.0.0
- [get-stdin](https://npm.io/package/get-stdin.md) ^10.0.0
- [multiformats](https://npm.io/package/multiformats.md) ^13.4.2

## Recent versions

- 7.0.12 (latest) — 2026-03-30
- 7.0.11 — 2026-02-06
- 7.0.10 — 2026-01-23
- 7.0.9 — 2026-01-21
- 7.0.8 — 2025-12-11
- 7.0.7 — 2025-12-04
- 7.0.6 — 2025-12-03
- 7.0.5 — 2025-11-24
- 7.0.4 — 2025-10-16
- 7.0.3 — 2025-10-15
- 7.0.2 — 2025-10-14
- 7.0.1 — 2025-08-12
- 7.0.0 — 2025-07-11
- 6.0.10 — 2025-06-11
- 6.0.9 — 2025-05-28
- … 45 more at https://npm.io/package/@ipld/schema/versions

## README

# @ipld/schema

JavaScript [IPLD](http://ipld.io/) Schema parser, validator, and code generator.

## What are IPLD Schemas?

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/

## Features

- **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

## Installation

```bash
npm install @ipld/schema
```

For CLI usage:
```bash
npm install -g @ipld/schema
```

## Quick Start

### Basic Schema Definition

IPLD Schemas use a simple, readable syntax:

```js
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)
}
```

## Schema Language Basics

### Basic Types

```ipldsch
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)
```

### Structs (Objects)

```ipldsch
type Person struct {
  name String
  age Int
  email String optional          # Optional field
  nickname String (implicit "")  # Default value
}
```

### Lists and Maps

```ipldsch
# 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}
}
```

### Enums

```ipldsch
type Status enum {
  | Active
  | Inactive
  | Pending
}

# With custom string values
type Color enum {
  | Red ("red")
  | Green ("green")
  | Blue ("blue")
} representation string
```

### Type Aliases

```ipldsch
type UserID = String
type Timestamp = Int
type EmailAddress = String
```

## Data Representations

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.

### Example: Tuple Representation

```js
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 }
```

## Code Generation

Generate type-safe code from your schemas:

### Go

```js
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 optionals
```

### Rust

```js
import { generateRust } from '@ipld/schema/gen/rust.js'

const rustCode = generateRust(schema)
// Generates Rust structs with serde derives and Option<T> for optionals
```

### TypeScript

```js
import { generateTypeScript } from '@ipld/schema/gen/typescript.js'

const tsCode = generateTypeScript(schema)
// Generates TypeScript interfaces and runtime validators
```

## Advanced Features

### Field Renames

Control JSON field names separately from your schema field names:

```ipldsch
type ServerConfig struct {
  serverPort Int (rename "server_port")
  debugMode Bool (rename "debug_mode")
  apiKey String (rename "api_key")
}
```

### Annotations

Add language-specific type information:

```ipldsch
# 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
}
```

### Custom Transforms

Handle special encoding requirements:

```js
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 })
```

## Command Line Interface

The `ipld-schema` command provides tools for working with schemas:

### Validation

```bash
# Validate schema files
ipld-schema validate schema.ipldsch

# Extract and validate schemas from markdown
ipld-schema validate README.md
```

### Conversion

```bash
# Convert to JSON format
ipld-schema to-json schema.ipldsch

# Pretty print as canonical schema
ipld-schema to-schema schema.ipldsch
```

### Code Generation

```bash
# Generate JavaScript validators
ipld-schema to-js schema.ipldsch

# Generate TypeScript definitions
ipld-schema to-tsdefs schema.ipldsch
```

## API Reference

### Parsing Schemas

- `fromDSL(dsl: string)` - Parse schema DSL into an AST
- `toDSL(schema: Schema)` - Convert AST back to DSL

### Validation

- `create(schema: Schema, type: string, options?)` - Create a validator
  - Returns `{ toTyped, toRepresentation }`
  - `toTyped(data)` - Validate and convert from storage format
  - `toRepresentation(data)` - Validate and convert to storage format

### Code Generation

- `generateGo(schema, options)` - Generate Go code
- `generateRust(schema, options)` - Generate Rust code
- `generateTypeScript(schema, options)` - Generate TypeScript code

## License & Copyright

Copyright 2019-2025 Rod Vagg

Licensed under either of

 * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)
 * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)

### Contribution

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.

---
_Source: https://npm.io/package/@ipld/schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._