{"id":13880715,"url":"https://github.com/triggerdotdev/json-schema-fns","last_synced_at":"2025-07-02T08:09:10.278Z","repository":{"id":57122523,"uuid":"444373610","full_name":"triggerdotdev/json-schema-fns","owner":"triggerdotdev","description":"Modern utility library and typescript typings for building JSON Schema documents","archived":false,"fork":false,"pushed_at":"2024-07-31T13:12:03.000Z","size":24,"stargazers_count":12,"open_issues_count":3,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-15T00:15:38.849Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/triggerdotdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-04T10:16:52.000Z","updated_at":"2024-10-12T18:58:12.000Z","dependencies_parsed_at":"2024-03-13T05:34:46.772Z","dependency_job_id":"068ebd91-7050-4e3b-aad9-76d8160993a2","html_url":"https://github.com/triggerdotdev/json-schema-fns","commit_stats":null,"previous_names":["jsonhero-io/json-schema-fns"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-schema-fns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-schema-fns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-schema-fns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-schema-fns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triggerdotdev","download_url":"https://codeload.github.com/triggerdotdev/json-schema-fns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981268,"owners_count":21193147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:03:25.264Z","updated_at":"2025-04-15T00:15:54.518Z","avatar_url":"https://github.com/triggerdotdev.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# json-schema-fns\n\n\u003e Modern utility library and typescript typings for building JSON Schema documents dynamically\n\n\u003c!-- ![Coverage lines](./badges/badge-lines.svg) --\u003e\n\u003c!-- ![Tests](https://github.com/jsonhero-io/json-schema-fns/actions/workflows/test.yml/badge.svg?branch=main) --\u003e\n\u003c!-- [![Downloads](https://img.shields.io/npm/dm/%40jsonhero%2Fjson-schema-fns.svg)](https://npmjs.com/@jsonhero/json-schema-fns) --\u003e\n\u003c!-- [![Install size](https://packagephobia.com/badge?p=%40jsonhero%2Fjson-schema-fns)](https://packagephobia.com/result?p=@jsonhero/json-schema-fns) --\u003e\n\n## Features\n\n- Build JSON Schema documents for various drafts (currently only draft-2020-12 but more coming soon)\n- Strongly typed documents using Typescript\n- Allows you to build correct JSON Schema documents using dynamic data\n\n## Usage\n\nCreate a simple draft-2020-12 document:\n\n```ts\nimport { s } from \"json-schema-fns\";\n\nconst schema = s.object({\n  properties: [s.requiredProperty(\"foo\", s.string()), s.property(\"bar\", s.int())],\n});\n\nschema.toSchemaDocument();\n```\n\nWill result in\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema#\",\n  \"$id\": \"https://jsonhero.io/schemas/root.json\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"foo\": { \"type\": \"string\" },\n    \"bar\": { \"type\": \"integer\" }\n  },\n  \"required\": [\"foo\"]\n}\n```\n\nYou can also import the types for a specific draft to use, like so:\n\n```typescript\nimport { s, Schema, IntSchema, StringSchema, StringFormat } from \"json-schema-fns\";\n\nfunction buildIntSchema(maximum: number, minimum: number): IntSchema {\n  return s.int({ minimum, maximum });\n}\n\nfunction buildStringFormat(format: JSONStriStringFormatgFormat): StringSchema {\n  return s.string({ format });\n}\n```\n\n`json-schema-fns` support all the features of JSON schema:\n\n```typescript\nimport { s } from \"json-schema-fns\";\n\nconst phoneNumber = s.def(\"phoneNumber\", s.string({ pattern: \"^[0-9]{3}-[0-9]{3}-[0-9]{4}$\" }));\nconst usAddress = s.def(\n  \"usAddress\",\n  s.object({\n    properties: [s.requiredProperty(\"zipCode\", s.string())],\n  }),\n);\n\nconst ukAddress = s.def(\n  \"ukAddress\",\n  s.object({\n    properties: [s.requiredProperty(\"postCode\", s.string())],\n  }),\n);\n\ns.object({\n  $id: \"/schemas/person\",\n  title: \"Person Profile\",\n  description: \"Attributes of a person object\",\n  examples: [\n    {\n      name: \"Eric\",\n      email: \"eric@stackhero.dev\",\n    },\n  ],\n  $comment: \"This is just a preview\",\n  default: {},\n  properties: [\n    s.requiredProperty(\"name\", s.string()),\n    s.property(\"email\", s.string({ format: \"email\" })),\n    s.property(\"phoneNumber\", s.ref(\"phoneNumber\")),\n    s.property(\"billingAddress\", s.oneOf(s.ref(\"ukAddress\"), s.ref(\"usAddress\"))),\n    s.patternProperty(\"^[A-Za-z]$\", s.string()),\n  ],\n  additionalProperties: s.array({\n    items: s.number({ minimum: 0, maximum: 5000 }),\n  }),\n  propertyNames: \"^[A-Za-z_][A-Za-z0-9_]*$\",\n  minProperties: 3,\n  maxProperties: 20,\n  unevaluatedProperties: false,\n  defs: [phoneNumber, usAddress, ukAddress],\n}).toSchemaDocument();\n```\n\nWill result in\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"type\": \"object\",\n  \"$id\": \"/schemas/person\",\n  \"title\": \"Person Profile\",\n  \"description\": \"Attributes of a person object\",\n  \"examples\": [\n    {\n      \"name\": \"Eric\",\n      \"email\": \"eric@stackhero.dev\"\n    }\n  ],\n  \"$comment\": \"This is just a preview\",\n  \"default\": {},\n  \"minProperties\": 3,\n  \"maxProperties\": 20,\n  \"unevaluatedProperties\": false,\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    },\n    \"email\": {\n      \"type\": \"string\",\n      \"format\": \"email\"\n    },\n    \"phoneNumber\": {\n      \"$ref\": \"#/$defs/phoneNumber\"\n    },\n    \"billingAddress\": {\n      \"oneOf\": [\n        {\n          \"$ref\": \"#/$defs/ukAddress\"\n        },\n        {\n          \"$ref\": \"#/$defs/usAddress\"\n        }\n      ]\n    }\n  },\n  \"required\": [\"name\"],\n  \"patternProperties\": {\n    \"^[A-Za-z]$\": {\n      \"type\": \"string\"\n    }\n  },\n  \"propertyNames\": {\n    \"pattern\": \"^[A-Za-z_][A-Za-z0-9_]*$\"\n  },\n  \"additionalProperties\": {\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"number\",\n      \"minimum\": 0,\n      \"maximum\": 5000\n    }\n  },\n  \"$defs\": {\n    \"phoneNumber\": {\n      \"type\": \"string\",\n      \"pattern\": \"^[0-9]{3}-[0-9]{3}-[0-9]{4}$\"\n    },\n    \"usAddress\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"zipCode\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\"zipCode\"]\n    },\n    \"ukAddress\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"postCode\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\"postCode\"]\n    }\n  }\n}\n```\n\n# API\n\n## `s`\n\nAll the builder methods for creating subschemas are available on the `s` object\n\n```typescript\nimport { s } from \"json-schema-fns\";\n```\n\nOr if you want to import a specific dialect:\n\n```typescript\nimport { s } from \"json-schema-fns/2020\";\n```\n\nAll builder methods return a `SchemaBuilder`, and you can generate the JSON schema created by the builder using `toSchemaDocument` like so\n\n```typescript\ns.object().toSchemaDocument();\n```\n\nWhich will result in the following document\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"type\": \"object\"\n}\n```\n\nIf you don't want the `$schema` property, use `toSchema` instead:\n\n```typescript\ns.object().toSchema(); // { \"type\": \"object\" }\n```\n\nAll builder methods also support the options in `AnnotationSchema`:\n\n```typescript\ns.object({\n  $id: \"#/foobar\",\n  $comment: \"This is a comment\",\n  default: {},\n  title: \"FooBar Object Schema\",\n  description: \"This is the FooBar schema description\",\n  examples: [{ foo: \"bar\" }],\n  deprecated: true,\n  readOnly: true,\n  writeOnly: false,\n}).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"$id\": \"#/foobar\",\n  \"$comment\": \"This is a comment\",\n  \"default\": {},\n  \"title\": \"FooBar Object Schema\",\n  \"description\": \"This is the FooBar schema description\",\n  \"examples\": [{ \"foo\": \"bar\" }],\n  \"deprecated\": true,\n  \"readOnly\": true,\n  \"writeOnly\": false\n}\n```\n\n### `s.object(options: ObjectOptions)`\n\nBuilds a schema of type `object`, accepting a single argument of type `ObjectOptions`\n\n#### `ObjectOptions.properties`\n\nAn array of optional and required properties\n\n```typescript\ns.object({\n  properties: [\n    s.property(\"name\", s.string()),\n    s.requiredProperty(\"email\", s.string({ format: \"email\" })),\n  ],\n}).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"email\": { \"type\": \"string\", \"format\": \"email\" }\n  },\n  \"required\": [\"email\"]\n}\n```\n\nYou can also add [patternProperties](https://json-schema.org/understanding-json-schema/reference/object.html#pattern-properties)\n\n```typescript\ns.object({ properties: [s.patternProperty(\"^S_\", s.string())] }).toSchema();\n```\n\nwhich produces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"patternProperties\": {\n    \"^S_\": { \"type\": \"string\" }\n  }\n}\n```\n\n#### `ObjectOptions.additonalProperties`\n\nAdd an [additonalProperties](https://json-schema.org/understanding-json-schema/reference/object.html#additional-properties) schema:\n\n```typescript\ns.object({ additionalProperties: s.number() }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"additionalProperties\": {\n    \"type\": \"number\"\n  }\n}\n```\n\n#### `ObjectOptions.propertyNames`\n\nAdd a [propertyNames](https://json-schema.org/understanding-json-schema/reference/object.html#property-names) pattern:\n\n```typescript\ns.object({ propertyNames: \"^[A-Za-z_][A-Za-z0-9_]*$\" }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"propertyNames\": {\n    \"pattern\": \"^[A-Za-z_][A-Za-z0-9_]*$\"\n  }\n}\n```\n\n#### `ObjectOptions.minProperties` and `ObjectOptions.maxProperties`\n\nValidate the number of properties in an object using [min/maxProperties](https://json-schema.org/understanding-json-schema/reference/object.html#size)\n\n```typescript\ns.object({ minProperties: 4, maxProperties: 10 }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"minProperties\": 4,\n  \"maxProperties\": 10\n}\n```\n\n#### `ObjectOptions.unevaluatedProperties`\n\nSpecify the handling of [unevaluatedProperties](https://json-schema.org/understanding-json-schema/reference/object.html#unevaluated-properties)\n\n```typescript\ns.object({ unevaluatedProperties: false }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"object\",\n  \"unevaluatedProperties\": false\n}\n```\n\n### `s.array(options: ArrayOptions)`\n\nBuilds a schema of type `array`, accepting a single argument of type `ArrayOptions`\n\n#### `ArrayOptions.items`\n\nDefine the [items](https://json-schema.org/understanding-json-schema/reference/array.html#items) schema for an array:\n\n```typescript\ns.array({ items: s.string() }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"array\",\n  \"items\": { \"type\": \"string\" }\n}\n```\n\n#### `ArrayOptions.minItems` and `ArrayOptions.maxItems`\n\nDefine the array [length](https://json-schema.org/understanding-json-schema/reference/array.html#length)\n\n```typescript\ns.array({ contains: { schema: s.number(), min: 1, max: 3 }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"array\",\n  \"contains\": { \"type\": \"number\" },\n  \"minContains\": 1,\n  \"maxContains\": 3\n}\n```\n\n#### `ArrayOptions.prefixItems`\n\nAllows you to perform [tuple validation](https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation):\n\n```typescript\ns.array({ prefixItems: [s.string(), s.number()] }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"array\",\n  \"prefixItems\": [{ \"type\": \"string\" }, { \"type\": \"number\" }]\n}\n```\n\n#### `ArrayOptions.unevaluatedItems`\n\nDefine the schema for [unevaluatedItems](https://json-schema.org/understanding-json-schema/reference/array.html#unevaluated-items)\n\n```typescript\ns.array({ unevaluatedItems: s.object() }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"array\",\n  \"unevaluatedItems\": { \"type\": \"object\" }\n}\n```\n\n#### `ArrayOptions.contains`\n\nDefine the schema [contains](https://json-schema.org/understanding-json-schema/reference/array.html#contains)\n\n```typescript\ns.array({ contains: { schema: s.number(), min: 1, max: 3 }).toSchema();\n```\n\nProduces the schema\n\n```json\n{\n  \"type\": \"array\",\n  \"contains\": { \"type\": \"number\" },\n  \"minContains\": 1,\n  \"maxContains\": 3\n}\n```\n\n### `string`\n\n### `integer` and `number`\n\n### `boolean`\n\n### `nil`\n\n### `nullable`\n\n### `anyOf` | `allOf` | `oneOf`\n\n### `ifThenElse` and `ifThen`\n\n### `not`\n\n### `def` and `ref`\n\n### `$const`\n\n### `$enumerator`\n\n### `$true` and `$false`\n\n## Roadmap\n\n- Support draft-04\n- Support draft-06\n- Support draft-07\n- Support draft/2019-09\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-schema-fns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriggerdotdev%2Fjson-schema-fns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-schema-fns/lists"}