# @atproto/syntax

> Validation for atproto identifiers and formats: DID, handle, NSID, AT URI, etc

Latest version **0.7.6** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @atproto/syntax
pnpm add @atproto/syntax
yarn add @atproto/syntax
bun add @atproto/syntax
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.7.6 |
| Published | 2026-09-11 |
| First published | 2023-08-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 2 |
| Unpacked size | 180.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9651 |
| Maintainers | dholms, pfrazee, devinivy, estrattonbailey, matthieu-bluesky |
| Keywords | atproto, did, nsid, at-uri |

## Links

- npm: https://www.npmjs.com/package/@atproto/syntax
- Repository: https://github.com/bluesky-social/atproto
- Homepage: https://atproto.com
- npm.io page: https://npm.io/package/@atproto/syntax

## Dependencies (2)

- [tslib](https://npm.io/package/tslib.md) ^2.8.1
- [iso-datestring-validator](https://npm.io/package/iso-datestring-validator.md) ^2.2.2

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.7.6 (latest) — 2026-09-11
- 0.0.0-spaces-alpha-20260915165437 (alpha) — 2026-09-15
- 0.6.0-next.0 (next) — 2026-05-18
- 0.0.0-spaces-alpha-20260915164701 — 2026-09-15
- 0.0.0-spaces-alpha-20260913191958 — 2026-09-13
- 0.0.0-spaces-alpha-20260910230440 — 2026-09-10
- 0.0.0-spaces-alpha-20260910223605 — 2026-09-10
- 0.0.0-spaces-alpha-20260910222405 — 2026-09-10
- 0.0.0-spaces-alpha-20260910214032 — 2026-09-10
- 0.7.5 — 2026-08-26
- 0.0.0-spaces-alpha-20260818163953 — 2026-08-18
- 0.0.0-spaces-alpha-20260818023850 — 2026-08-18
- 0.0.0-spaces-alpha-20260818021221 — 2026-08-18
- 0.7.4 — 2026-08-06
- 0.7.3 — 2026-08-03
- … 31 more at https://npm.io/package/@atproto/syntax/versions

## README

# @atproto/syntax: validation helpers for identifier strings

Validation logic for [atproto](https://atproto.com) identifiers - DIDs, Handles, NSIDs, and AT URIs.

[![NPM](https://img.shields.io/npm/v/@atproto/crypto)](https://www.npmjs.com/package/@atproto/syntax)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)

## Usage

### Handles

Syntax specification: <https://atproto.com/specs/handle>

```typescript
import { isValidHandle, ensureValidHandle, isValidDid } from '@atproto/syntax'

isValidHandle('alice.test') // returns true
ensureValidHandle('alice.test') // returns void

isValidHandle('al!ce.test') // returns false
ensureValidHandle('al!ce.test') // throws

ensureValidDid('did:method:val') // returns void
ensureValidDid(':did:method:val') // throws
```

### NameSpaced IDs (NSID)

Syntax specification: <https://atproto.com/specs/nsid>

```typescript
import { NSID } from '@atproto/syntax'

const id1 = NSID.parse('com.example.foo')
id1.authority // => 'example.com'
id1.name // => 'foo'
id1.toString() // => 'com.example.foo'

const id2 = NSID.create('example.com', 'foo')
id2.authority // => 'example.com'
id2.name // => 'foo'
id2.toString() // => 'com.example.foo'

const id3 = NSID.create('example.com', 'someRecord')
id3.authority // => 'example.com'
id3.name // => 'someRecord'
id3.toString() // => 'com.example.someRecord'

NSID.isValid('com.example.foo') // => true
NSID.isValid('com.example.someRecord') // => true
NSID.isValid('example.com/foo') // => false
NSID.isValid('foo') // => false
```

### AT URI

Syntax specification: <https://atproto.com/specs/at-uri-scheme>

```typescript
import { AtUri } from '@atproto/syntax'

const uri = new AtUri('at://bob.com/com.example.post/1234')
uri.protocol // => 'at:'
uri.origin // => 'at://bob.com'
uri.hostname // => 'bob.com'
uri.collection // => 'com.example.post'
uri.rkey // => '1234'
```

## License

This project is dual-licensed under MIT and Apache 2.0 terms:

- MIT license ([LICENSE-MIT.txt](https://github.com/bluesky-social/atproto/blob/main/LICENSE-MIT.txt) or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0, ([LICENSE-APACHE.txt](https://github.com/bluesky-social/atproto/blob/main/LICENSE-APACHE.txt) or http://www.apache.org/licenses/LICENSE-2.0)

Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

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