or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

colors.mddata-formats.mddate-time.mdfinancial.mdgeographic.mdidentifiers.mdindex.mdnetwork.mdnumeric.mdspecialized.mdstring-text.mdutilities.md
tile.json

identifiers.mddocs/

Identifier Scalars

Unique identifier validation including UUIDs, ObjectIDs, JWTs, and other ID formats. These scalars provide validation for various identifier systems commonly used in modern applications.

Capabilities

UUID Scalar

Validates Universally Unique Identifier (UUID) format.

/**
 * GraphQL scalar for UUID validation
 * Accepts standard UUID format (8-4-4-4-12 hexadecimal digits)
 * Supports versions 1, 3, 4, and 5
 */
const GraphQLUUID: GraphQLScalarType;

Example Values:

  • "550e8400-e29b-41d4-a716-446655440000"
  • "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  • "f47ac10b-58cc-4372-a567-0e02b2c3d479"

GUID Scalar

Validates Globally Unique Identifier (GUID) format - alias for UUID.

/**
 * GraphQL scalar for GUID validation
 * Alias for UUID, accepts the same format
 */
const GraphQLGUID: GraphQLScalarType;

Example Values:

  • Same as UUID format
  • "550e8400-e29b-41d4-a716-446655440000"

ObjectID Scalar

Validates MongoDB ObjectID format.

/**
 * GraphQL scalar for MongoDB ObjectID validation
 * Accepts 24-character hexadecimal string
 */
const GraphQLObjectID: GraphQLScalarType;

Example Values:

  • "507f1f77bcf86cd799439011"
  • "507f191e810c19729de860ea"
  • "5f8f4e2c1b2c3d4e5f6g7h8i"

Cuid Scalar

Validates Collision-resistant Unique Identifier (CUID) format.

/**
 * GraphQL scalar for CUID validation
 * Accepts collision-resistant unique identifiers
 * Format: c[timestamp][counter][fingerprint][random]
 */
const GraphQLCuid: GraphQLScalarType;

Example Values:

  • "cjld2cjxh0000qzrmn831i7rn"
  • "cjld2cyuq0000t3rmniod1foy"
  • "cjld2d0180000w3rmkfp2yxed"

JWT Scalar

Validates JSON Web Token (JWT) format.

/**
 * GraphQL scalar for JWT validation
 * Accepts JWT format: header.payload.signature (base64url encoded)
 */
const GraphQLJWT: GraphQLScalarType;

Example Values:

  • "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

DID Scalar

Validates Decentralized Identifier (DID) format.

/**
 * GraphQL scalar for DID validation
 * Accepts W3C Decentralized Identifier format
 * Format: did:method:method-specific-id
 */
const GraphQLDID: GraphQLScalarType;

Example Values:

  • "did:example:123456789abcdefghi"
  • "did:web:example.com"
  • "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"

Usage Examples

import { 
  GraphQLUUID,
  GraphQLObjectID,
  GraphQLJWT,
  GraphQLCuid
} from "graphql-scalars";

// In a GraphQL schema
const UserType = new GraphQLObjectType({
  name: "User",
  fields: {
    id: { type: GraphQLUUID },
    mongoId: { type: GraphQLObjectID },
    sessionToken: { type: GraphQLJWT },
    correlationId: { type: GraphQLCuid },
  },
});

// Using with type definitions
const typeDefs = `
  scalar UUID
  scalar ObjectID
  scalar JWT
  scalar Cuid
  
  type User {
    id: UUID
    mongoId: ObjectID
    sessionToken: JWT
    correlationId: Cuid
  }
  
  type Query {
    user(id: UUID!): User
    userByObjectId(mongoId: ObjectID!): User
  }
  
  type Mutation {
    authenticate(token: JWT!): AuthResult
  }
`;

GraphQL Operations:

# Query using UUID
query GetUser($userId: UUID!) {
  user(id: $userId) {
    id
    name
    email
  }
}

# Mutation with JWT
mutation Authenticate($token: JWT!) {
  authenticate(token: $token) {
    success
    user {
      id
      name
    }
  }
}

Variables:

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.Rq8IxqeX7eA6GdeE8bAr3JLprgfWfDKkjuQi7lqgaQ"
}

Validation Behavior

Each identifier scalar performs format-specific validation:

  • UUID/GUID: Validates 8-4-4-4-12 hexadecimal pattern with proper version bits
  • ObjectID: Ensures exactly 24 hexadecimal characters
  • Cuid: Validates collision-resistant format with proper structure
  • JWT: Checks three base64url-encoded segments separated by dots
  • DID: Validates W3C DID specification with method and identifier parts

Type Definitions

// String constants for schema building
const UUID: string;      // "scalar UUID"
const GUID: string;      // "scalar GUID"
const ObjectID: string;  // "scalar ObjectID"
const Cuid: string;      // "scalar Cuid"
const JWT: string;       // "scalar JWT"
const DID: string;       // "scalar DID"

Mock Data

// Mock data generators for testing
const UUIDMock: () => string;
const GUIDMock: () => string;
const ObjectIDMock: () => string;
const CuidMock: () => string;
const JWTMock: () => string;
const DIDMock: () => string;

Practical Use Cases

UUIDs are ideal for:

  • Primary keys in distributed systems
  • Session identifiers
  • API request correlation IDs

ObjectIDs are perfect for:

  • MongoDB document identifiers
  • Legacy system integration
  • Database migration scenarios

JWTs are commonly used for:

  • Authentication tokens
  • Authorization claims
  • Secure information exchange

CUIDs excel at:

  • Client-side ID generation
  • Offline-first applications
  • Collision-resistant scenarios

DIDs are used for:

  • Decentralized identity systems
  • Blockchain applications
  • Self-sovereign identity solutions