cds-validate

💡 Why This Exists

Every SAP CAP developer has written code like this:

// ❌ This is what most CAP projects look like today
srv.before('CREATE', 'Students', (req) => {
  if (!req.data.name || req.data.name.trim() === '')
    req.error(400, 'Name is required', 'name');
  if (!req.data.email)
    req.error(400, 'Email is required', 'email');
  if (req.data.email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(req.data.email))
    req.error(400, 'Invalid email format', 'email');
  if (req.data.gpa !== undefined && typeof req.data.gpa !== 'number')
    req.error(400, 'GPA must be a number', 'gpa');
  if (req.data.gpa !== undefined && (req.data.gpa < 0 || req.data.gpa > 4))
    req.error(400, 'GPA must be between 0 and 4', 'gpa');
  // ... and this repeats for every single entity ...
});

The problems:

cds-validate solves all of this in one line:

// ✅ One line. Type-safe. Auto-coercion. OData errors. Partial UPDATE support.
srv.before('CREATE', 'Students', validate(StudentSchema));

📦 Installation

# npm
npm install cds-validate zod

# pnpm
pnpm add cds-validate zod

# yarn
yarn add cds-validate zod

Requirements

🚀 Quick Start

Option A: Write your own Zod schema

const { validate } = require('cds-validate');
const { z } = require('zod');

const StudentSchema = z.object({
  name:     z.string().min(1, 'Name is required'),
  email:    z.string().trim().email('Invalid email'),
  gpa:      z.coerce.number().min(0).max(4).optional(),
  enrolled: z.boolean().optional(),
});

module.exports = (srv) => {
  srv.before('CREATE', 'Students', validate(StudentSchema));
  srv.before('UPDATE', 'Students', validate(StudentSchema)); // auto-partial!
};

Option B: Auto-generate from your CDS model (zero manual work)

const { schemaFromEntity, validate } = require('cds-validate');

module.exports = async (srv) => {
  const StudentSchema = await schemaFromEntity('Students');

  srv.before('CREATE', 'Students', validate(StudentSchema));
  srv.before('UPDATE', 'Students', validate(StudentSchema));
};

That's it. Invalid requests now return clean OData 422 errors automatically.

⚙️ How It Works

Here's what happens when a request hits your validated endpoint:

  Client sends POST /Students { name: "", email: "bad", gpa: 5 }
                          │
                          ▼
              ┌───────────────────────┐
              │   validate(schema)    │  ◀── Your middleware
              │                       │
              │  1. Detect event type │
              │     CREATE → full     │
              │     UPDATE → partial  │
              │                       │
              │  2. schema.safeParse  │
              │     (req.data)        │
              └───────────┬───────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
         ✅ Valid                 ❌ Invalid
              │                       │
              ▼                       ▼
    ┌─────────────────┐   ┌──────────────────────┐
    │  Normalize data  │   │    error-mapper       │
    │  • Type coerce   │   │    ZodError → OData   │
    │  • Trim strings  │   │    422 response        │
    │  • Apply defaults│   │                        │
    │                  │   │  ┌──────────────────┐  │
    │  Overwrite       │   │  │ { code: 422,     │  │
    │  req.data with   │   │  │   message: "..." │  │
    │  parsed result   │   │  │   target: "email"│  │
    └─────────────────┘   │  │   details: [...]  │  │
              │            │  └──────────────────┘  │
              ▼            └──────────┬─────────────┘
    ┌─────────────────┐               │
    │  Continue to     │               ▼
    │  your handler    │     ┌─────────────────┐
    │  with clean data │     │  req.error()    │
    └─────────────────┘     │  → stops request │
                             └─────────────────┘

Key behaviors:

📖 API Reference

validate(schema, options?)

The main middleware — validates req.data.

srv.before('CREATE', 'Students', validate(StudentSchema));
srv.before('CREATE', 'Students', validate(StudentSchema, { strict: true }));

💡 normalize: true is powerful — it gives you free type coercion ("42" → 42), string trimming, default values, and Zod transforms without any extra code.

validateQuery(schema, options?)

Validates req.query — perfect for controlling OData query parameters.

const PaginationSchema = z.object({
  $top:  z.coerce.number().int().max(100, 'Max 100 records').optional(),
  $skip: z.coerce.number().int().min(0).optional(),
});

srv.before('READ', 'Products', validateQuery(PaginationSchema));

validateParams(schema, options?)

Validates req.params — for bound action/function parameters.

const TransferParams = z.object({
  fromAccount: z.string().uuid(),
  toAccount:   z.string().uuid(),
  amount:      z.coerce.number().positive(),
});

srv.before('transferFunds', validateParams(TransferParams));

Handles both object ({ id: '...' }) and array ([{ id: '...' }]) forms of req.params automatically.

schemaFromEntity(entityName, options?)

🏗️ The killer feature — auto-generates Zod schemas from your CDS model.

const StudentSchema = await schemaFromEntity('Students');
// Equivalent to manually writing:
// z.object({ ID: z.string().uuid().optional(), name: z.string(), ... })

CDS → Zod type mapping:

Field rules:

mapZodError(zodError) / cdsTypeToZod(element)

Low-level utilities for custom validation flows:

const { mapZodError } = require('cds-validate');

// Use in your own validation logic
const result = MySchema.safeParse(data);
if (!result.success) {
  const capError = mapZodError(result.error);
  req.error(capError); // → OData 422 response
}

🌍 Real World Examples

const { validate, schemaFromEntity } = require('cds-validate');

module.exports = async (srv) => {
  const entities = ['Employees', 'Departments', 'Projects', 'Tasks', 'Timesheets'];

  for (const entity of entities) {
    const schema = await schemaFromEntity(entity);
    srv.before('CREATE', entity, validate(schema));
    srv.before('UPDATE', entity, validate(schema));
  }
  // That's 10 validation handlers in 5 lines of code!
};

const ExternalPayloadSchema = z.object({
  transactionId: z.string().uuid(),
  amount:        z.coerce.number().positive(),
  currency:      z.enum(['USD', 'EUR', 'GBP', 'INR']),
  timestamp:     z.string().datetime(),
  metadata:      z.record(z.string()).optional(),
});

// Strict mode: reject any unknown fields from external clients
srv.before('CREATE', 'ExternalTransactions',
  validate(ExternalPayloadSchema, { strict: true })
);

// Fiori Elements reads OData error.details[].target to highlight fields
const InvoiceSchema = z.object({
  vendorId:    z.string().uuid('Please select a valid vendor'),
  amount:      z.coerce.number().positive('Amount must be positive'),
  invoiceDate: z.string().min(1, 'Invoice date is required'),
});

srv.before('CREATE', 'Invoices', validate(InvoiceSchema));
// → Fiori automatically shows red borders on invalid fields!

const ApproveParams = z.object({
  orderId:     z.string().uuid(),
  approverNote: z.string().max(500).optional(),
  priority:    z.enum(['low', 'medium', 'high']).default('medium'),
});

srv.before('approveOrder', validateParams(ApproveParams));

const ReadGuard = z.object({
  $top:     z.coerce.number().max(100, 'Maximum 100 records per request').optional(),
  $skip:    z.coerce.number().min(0).optional(),
  $orderby: z.string().optional(),
});

// Clients can't request 10,000 records at once anymore
srv.before('READ', 'LargeDataSet', validateQuery(ReadGuard));

module.exports = async (srv) => {
  // Start from CDS model...
  const baseSchema = await schemaFromEntity('Students');

  // ...then extend with custom business rules
  const strictSchema = baseSchema.extend({
    email: z.string().trim().toLowerCase().email(),
    gpa:   z.coerce.number().min(0).max(4),
  });

  srv.before('CREATE', 'Students', validate(strictSchema));
};

const OrderSchema = z.object({
  type:         z.enum(['standard', 'express', 'overnight']),
  amount:       z.coerce.number().positive(),
  deliveryDate: z.string().datetime().optional(),
}).refine(
  (data) => data.type !== 'express' || data.deliveryDate != null,
  { message: 'Express orders require a delivery date', path: ['deliveryDate'] }
);

🧪 Error Response Format

All errors follow the OData JSON error format — compatible with SAP Fiori, UI5, and any OData client:

// Single field error
{
  "error": {
    "code": 422,
    "message": "Invalid email format",
    "target": "email",
    "details": [
      { "message": "Invalid email format", "target": "email" }
    ]
  }
}

// Multiple field errors
{
  "error": {
    "code": 422,
    "message": "Validation failed with 3 errors",
    "target": "name",
    "details": [
      { "message": "Name is required",        "target": "name" },
      { "message": "Invalid email format",     "target": "email" },
      { "message": "Number must be at most 4", "target": "gpa" }
    ]
  }
}

// Nested field error (e.g., address.zipCode)
{
  "error": {
    "code": 422,
    "message": "Zip must be 5 characters",
    "target": "address/zipCode",          // ← OData path syntax
    "details": [
      { "message": "Zip must be 5 characters", "target": "address/zipCode" }
    ]
  }
}

❓ FAQ

const base = await schemaFromEntity('Students');
const custom = base.extend({
  email: z.string().trim().toLowerCase().email(),
  gpa: z.coerce.number().min(0).max(4),
});

🗂️ Repository Structure

cds-validate/
├── .github/workflows/
│   └── ci.yml                     CI/CD: lint → test (Node 18/20/22) → build → publish
├── packages/
│   └── cds-validate/              The npm package
│       ├── src/
│       │   ├── index.ts               Public API entry point
│       │   ├── types.ts               TypeScript interfaces
│       │   ├── validator.ts           validate(), validateQuery(), validateParams()
│       │   ├── error-mapper.ts        ZodError → OData 422 errors
│       │   └── schema-builder.ts      CDS model → Zod schema
│       ├── tests/
│       │   ├── error-mapper.test.ts   8 tests
│       │   ├── validator.test.ts      16 tests
│       │   └── schema-builder.test.ts 32 tests
│       ├── README.md                  Detailed API documentation
│       ├── CHANGELOG.md               Version history
│       ├── PUBLISHING_GUIDE.md        npm publishing guide
│       └── LICENSE                    MIT
├── demo-app/                      Example CAP app for testing
├── package.json                   Monorepo root
└── pnpm-workspace.yaml            pnpm workspace config

🔄 Version History

Full changelog: CHANGELOG.md

Versioning

This project follows Semantic Versioning:

• Patch (1.0.x) — Bug fixes
• Minor (1.x.0) — New features, backwards compatible
• Major (x.0.0) — Breaking API changes

🤝 Contributing

Contributions, issues, and feature requests are welcome!

# Clone and setup
git clone https://github.com/Nagarjundas1994-AiAgents/cds-validate.git
cd cds-validate
pnpm install

# Development
cd packages/cds-validate
pnpm test              # Run 56 tests
pnpm test:watch        # Watch mode
pnpm test -- --coverage  # Coverage report
pnpm lint              # TypeScript type-check
pnpm build             # Compile to dist/

Workflow

1. 🍴 Fork the repository
2. 🌿 Create a feature branch: git checkout -b feature/my-feature
3. ✅ Write tests first, then implementation
4. 🧪 Ensure all tests pass: pnpm test
5. 📤 Submit a Pull Request

📄 License

MIT — free for personal and commercial use.