Recipes

TypeScript enums

TypeScript enums are objects that sometimes have reverse mappings, so Object.values doesn't reliably list their values. enum-to-array does:

import { enumToValues } from 'enum-to-array';
import { enumSchema, type SchemaType } from 'juniper';

enum Status {
    ACTIVE = 'active',
    BANNED = 404,
}

const status = enumSchema({ enum: enumToValues(Status) });
type StatusType = SchemaType<typeof status>;
        
type StatusType = Status

status.toJSON();
// { enum: ['active', 404] }

Validating $ref paths you manage yourself

.ref(path) emits a $ref to a location Juniper doesn't control. When the target is also built with Juniper, prefer define, which places the definition for you and can't dangle.

Vendor extensions

Attach OpenAPI x- extensions, or any other custom keyword, with .metadata():

import { stringSchema } from 'juniper';

stringSchema().metadata('x-internal', true).toJSON();
// { type: 'string', 'x-internal': true }

Keys that are already JSON Schema keywords are rejected:

import { numberSchema } from 'juniper';

numberSchema().metadata('maximum', 5);
Argument of type '["maximum", 5]' is not assignable to parameter of type '["Error: \"maximum\" is a JSON Schema keyword. Set it with its own method."] & [Record<"maximum", number>]'.
  Type '["maximum", 5]' is not assignable to type '["Error: \"maximum\" is a JSON Schema keyword. Set it with its own method."]'.
    Source has 2 element(s) but target allows only 1.