# json-schema-shorthand

> Shortcuts for json schema definitions

Latest version **3.1.1** (published 2026-04-30) · ISC license · 0 weekly downloads

## Install

```sh
npm install json-schema-shorthand
pnpm add json-schema-shorthand
yarn add json-schema-shorthand
bun add json-schema-shorthand
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2026-04-30 |
| First published | 2016-07-31 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 23.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Yanick Champoux |
| Maintainers | yanick |
| Keywords | json, schema |

## Links

- npm: https://www.npmjs.com/package/json-schema-shorthand
- Repository: https://github.com/yanick/json-schema-shorthand
- Homepage: https://github.com/yanick/json-schema-shorthand#readme
- Issues: https://github.com/yanick/json-schema-shorthand/issues
- npm.io page: https://npm.io/package/json-schema-shorthand

## Dependencies (2)

- [remeda](https://npm.io/package/remeda.md) ^2.34.0
- [@yanick/updeep](https://npm.io/package/@yanick/updeep.md) ^4.0.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.1.1 (latest) — 2026-04-30
- 0.3.1 (master) — 2020-01-31
- 3.1.0 — 2023-06-01
- 3.0.0 — 2023-05-31
- 2.0.0 — 2020-08-24
- 1.0.0 — 2020-07-30
- 0.3.2 — 2020-01-31
- 0.3.0 — 2018-02-15
- 0.2.0 — 2017-01-03
- 0.1.0 — 2016-08-01
- 0.0.1 — 2016-07-31

## README

# json-schema-shorthand

[JSON Schema](http://json-schema.org/) is a useful beast,
but its schema definition can be a little bit more long-winded
than necessary. This module allows to use a few shortcuts that
will be expanded into their canonical form.

## To install

    npm install json-schema-shorthand

## Typical use

    import * as j from 'json-schema-shorthand';

    let schema = j.object({
        foo: 'number',
        bar: array('string'),
    });

    // schema === {
    //    type: 'object',
    //    properties: {
    //        foo: { type: 'number' },
    //        bar: { type: 'array', items: { type: 'string' } }
    //    }
    // }

## Compatibility with [json-schema-to-ts](https://www.npmjs.com/package/json-schema-to-ts)

`json-schema-shorthand` can be used in conjecture with `json-schema-to-ts`.
Just remember to `as const` your schemas to get the most precise types out
of `FromSchema<>`.

    const res = j.shorthand({
        object: {
            foo: "number!",
        },
        } as const
    );

    expectTypeOf(s).toMatchTypeOf<{ foo: number; }>();

## Functions

### `j.shorthand( schema )`

Takes in a data structure
and expands any shorthand (see next section) found in it.

Also the default export of `json-schema-shorthand`.

    let schema = j.shorthand( { object: { foo: 'number' } });
    // => { type: 'object', properties: { foo: { type: 'number' } } }

### `j.number( description?, schema? )`

    let schema = j.number( 'number of thingies', { maximum: 5 });
    // => { type: 'number', description: 'number of thingies', maximum: 5 }

Expands into a number type.

### `j.integer( description?, schema? )`

    let schema = j.integer({ maximum: 5 });
    // => { type: 'integer', maximum: 5 }

Expands into an integer type.

### `j.string( description?, schema? )`

    let schema = j.string({ maxLength: 5 });
    // => { type: 'string', maxLength: 5 }

Expands into a string type.

### `j.array( itemsSchema, schema? )`

    let schema = j.array('number', { maxItems: 5 });
    // => { type: 'array', items: { type: 'number' }, maxItems: 5 }

Expands into an array type.

### `j.object( description?, properties, schema? )`

    let schema = j.object({ foo: 'string!' }, { description: "yadah" });
    // => { type: 'object',
    //      properties: { foo: { type: 'string' } },
    //      required: [ 'foo' ],
    //      description: "yadah" }

Expands into an object type.

### `j.allOf(schemas,extra)`, `j.oneOf(schemas,extra)`, `j.anyOf(schemas, extra)`

    let schema = j.allOf(j.array(), { items: 'number' });
    // => { allOf: [
    //      { type: 'array' },
    //      { items: { type: number } }
    //    ] }

Same for `oneOf` and `anyOf`.

### `j.not(description?, schema)`

    let schema = j.not(array());
    // => { not: { type: 'array' } }

## Shorthands

### Types as string

If a string `type` is encountered where a property definition is
expected, the string is expanded to the object `{ "type": type }`.

    {
        "foo": "number",
        "bar": "string"
    }

expands to

    {
        "foo": { "type": "number" },
        "bar": { "type": "string" }
    }

If the string begins with a `#`, the type is assumed to be a local reference and
`#type` is expanded to `{ "$ref": type }`.

    { "foo": "#/definitions/bar" }

becomes

    { "foo": { "$ref": "#/definitions/bar" } }

If the string begins with a `$`, the type is assumed to be a general reference and
`$type` is expanded to `{ "$ref": type }`.

    { "foo": "$http://foo.com/bar" }

becomes

    { "foo": { "$ref": "http://foo.com/bar" } }

### `object` property

`{ object: properties }` expands to `{ type: "object", properties }`.

    shorthand                              expanded
    ------------------------               ---------------------------
    foo: {                                  foo: {
        object: {                               type: "object",
            bar: { }                            properties: {
        }                                           bar: { }
    }                                           }
                                            }

### `array` property

`{ array: items }` expands to `{ type: "array", items }`.

    shorthand                              expanded
    ------------------------               ---------------------------
    foo: {                                  foo: {
        array: 'number'                         type: "array",
    }                                           items: {
                                                    type: 'number'
                                                }
                                            }

### `required` property

If the `required` attribute is set to `true` for a property, it is bubbled
up to the `required` attribute of its parent object.

    shorthand                              expanded
    ------------------------               ---------------------------

    foo: {                                  foo: {
        properties: {                           required: [ 'bar' ],
          bar: { required: true },              properties: {
          baz: { }                                bar: {},
        }                                         baz: {}
    }                                       }

The type or `$ref` of a field can also be appended a `!` to mark it
as required.

    shorthand                              expanded
    ------------------------               ---------------------------

    foo: {                                  foo: {
        properties: {                           required: [ 'bar', 'baz' ],
          bar: 'number!'                        properties: {
          baz: '#baz_type!'                       bar: {   type: 'number' },
        }                                         baz: { '$ref': '#baz_type' }
    }                                       }

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