{"id":"efreeti/json-schema-types","name":"json-schema-types","scope":"efreeti","platform":"roblox","description":"Typed Luau JSON Schema 2020-12 models","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{},"integrity":"6f6375eb79ae6199e357865cf7228cf897f632027879a4fbf1148dabdc984307","likes":0,"downloads":0,"install":"forest install efreeti/json-schema-types","url":"https://forest.dev/p/roblox/efreeti/json-schema-types","files":"https://api.forest.dev/ai/package/roblox/efreeti/json-schema-types/files","readme":"# Luau JSON Schema Types\n\nStrict Luau type declarations for JSON Schema draft 2020-12, translated from\n[ya-json-schema-types](https://github.com/nfroidure/ya-json-schema-types).\nSchemas use ordinary Luau tables and values suitable for Roblox's `HttpService:JSONEncode`.\nThe package contains type declarations only. Requiring it returns an empty table;\nits exported type aliases provide static checks when constructing schemas.\n\nWally package: **efreeti/json-schema-types**. Versions are maintained in\n`wally.toml` and `package.json`.\n\n## Install with Wally\n\nAdd this dependency to your game's `wally.toml` using a published version:\n\n```toml\n[dependencies]\nJsonSchemaTypes = \"efreeti/json-schema-types@1.0.0\"\n```\n\nRun `wally install`. Mount `Packages/` in your Rojo project as usual. Wally's\nwrapper modules do not automatically forward exported type aliases; after installing,\nrun [wally-package-types](https://github.com/JohnnyMorganz/wally-package-types):\n\n```sh\nrojo sourcemap default.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages/\n```\n\n## Use in Roblox\n\n```luau\n--!strict\nlocal HttpService = game:GetService(\"HttpService\")\nlocal Schema = require(game.ReplicatedStorage.Packages.JsonSchemaTypes)\n\nlocal schema: Schema.JSONSchema = {\n    type = \"object\",\n    properties = {\n        label = { type = { \"string\", \"null\" } },\n        settings = {\n            type = \"object\",\n            default = { enabled = true, retries = 3 },\n        },\n        tags = { type = \"array\", default = { \"one\", \"two\" } },\n    },\n    required = { \"label\" },\n    additionalProperties = false,\n}\n\nlocal json = HttpService:JSONEncode(schema)\n```\n\n`const`, `default`, `enum`, and `examples` accept native JSON-compatible values:\nstrings, numbers, booleans, arrays, and objects. No wrappers, tags, or conversion\nfunctions are required. A schema allowing null uses `type = \"null\"` or a type list\nsuch as `{ \"string\", \"null\" }`.\n\nExtension keywords belong directly on the schema table. Use an intersection to\ncheck their shape:\n\n```luau\ntype ProviderSchema = Schema.SchemaKeywords & { read [\"x-provider\"]: string }\nlocal schema: ProviderSchema = {\n    type = \"object\",\n    [\"x-provider\"] = \"efreeti\",\n}\nlocal json = HttpService:JSONEncode(schema)\n```\n\n## Types and representation limits\n\n- All 57 upstream keywords have typed recursive mappings.\n- Primitive-specific and expressive aliases provide narrower static checks.\n- `JsonArray` and `JsonObject` are native table types; `JsonNull` is `nil`.\n- Public types expose read-only views so narrower variants compose safely. This\n  does not freeze your schema tables at runtime.\n- `src/types.luau` holds the declarations; `src/init.luau` forwards the public aliases.\n\nLuau has no TypeScript conditional types, bounded generics or nonempty tuple types:\n`NestedJSONSchema`, `ComposedJSONSchema` and `TypedJSONSchema` use the complete keyword\nmodel. `TextJSONSchema<F>` supports custom format literals. TypeScript's primitive\nrestriction and recursively propagated extension generics are not reproduced;\nlocal intersections allow native extension fields.\n\nNative Luau tables cannot store an explicit nil-valued field or preserve nil array\nentries. For example, `const = nil` omits `const`; it does not express JSON Schema's\n`\"const\": null`. Similarly, `{}` does not distinguish an empty JSON array from an\nempty JSON object. These are native representation limits, not handled by this\nlibrary. See [HttpService's JSON behavior](https://create.roblox.com/docs/reference/engine/classes/HttpService#JSONEncode).\nLuau numbers use double precision.\n\nThere is no JSON parser, serializer, schema document validator, or validator for\ninstances described by a schema. Use HttpService for JSON handling. Types check\nschema construction statically; an annotation or cast on `JSONDecode`'s result\nprovides no runtime validation.\n\n## Develop\n\nRequires Python 3.11+ and Luau **0.741 or newer**, including its read-only type syntax.\nInstall the pinned tools (curl/unzip, and CMake on Intel Macs):\n\n```sh\nbash scripts/install-tools.sh\npython3 scripts/check.py --luau .tools/luau --analyzer .tools/luau-analyze\npython3 scripts/check-package.py .tools/wally\n```\n\nTests statically check all 19 synthetic schemas in\n`tests/fixtures/cases/`, translated into native Luau values, plus construction examples\nand six deliberately invalid declarations. Boolean schemas are included. JSON null\nvalues become `nil` in these construction fixtures; nil fields and array entries\ncannot preserve the source JSON. Empty objects and arrays both become `{}`. These\ncases check type compatibility, not lossless serialization.\nStandalone runtime checks confirm the native table representation and empty module\nexports. They do not simulate HttpService or claim Roblox JSON round-trip testing.\nPrivate landscape schemas may be kept locally in the ignored\n`tests/fixtures/landscape/` directory. Add `--include-landscape` to the check command\nto include them in a local run. Public CI uses only the synthetic cases.\nThe check script generates `tests/FixtureData.luau` automatically before checking\nthe types. That generated module is ignored by Git and does not need to be committed.\n\nSee [publishing instructions](docs/publishing.md) for Wally and optional npm distribution.\nApache-2.0 licensed; upstream MIT attribution is retained in [NOTICE](NOTICE).\n","readmeTruncated":false}