{"id":23009920,"url":"https://github.com/openactive/models-ts","last_synced_at":"2025-04-02T16:14:49.922Z","repository":{"id":49653354,"uuid":"361278232","full_name":"openactive/models-ts","owner":"openactive","description":"TypeScript implementation of OpenActive's data model","archived":false,"fork":false,"pushed_at":"2023-04-03T16:20:08.000Z","size":4651,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-23T20:41:25.197Z","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/openactive.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":"2021-04-24T22:17:28.000Z","updated_at":"2023-04-03T16:20:32.000Z","dependencies_parsed_at":"2024-12-15T09:26:58.400Z","dependency_job_id":null,"html_url":"https://github.com/openactive/models-ts","commit_stats":{"total_commits":18,"total_committers":3,"mean_commits":6.0,"dds":0.2777777777777778,"last_synced_commit":"4d601e922e37c02d02bd59ea588565f7fc73e497"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive%2Fmodels-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive%2Fmodels-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive%2Fmodels-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive%2Fmodels-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openactive","download_url":"https://codeload.github.com/openactive/models-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246847137,"owners_count":20843444,"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-12-15T09:16:32.243Z","updated_at":"2025-04-02T16:14:49.896Z","avatar_url":"https://github.com/openactive.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# models-ts [![npm version](https://img.shields.io/npm/v/@openactive/models-ts)](https://www.npmjs.com/package/@openactive/models-ts) [![Tests](https://github.com/openactive/models-ts/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/openactive/models-ts/actions/workflows/tests.yaml)\n\nModel validation and TypeScript types for OpenActive's data model\n\nThis library works for both JavaScript and TypeScript developers, making it easier to conform to the OpenActive specifications.\n\nExample:\n\n```ts\nimport Joi from 'joi';\nimport {\n  OaValidationError,\n  Course,\n  Event_,\n  RequiredStatusType,\n  Event_OrSubClass,\n  validateRequiredStatusType,\n  RequiredStatusTypeJoiSchema,\n  Event_OrSubClassJoiSchema,\n  schema,\n} from '@openactive/models-ts';\n\n// TypeScript types (for OpenActive models) are found with the model/enum name\nconst myRequiredStatusType: RequiredStatusType = 'https://openactive.io/Required';\nconst myNotRequiredStatusType: RequiredStatusType = 'somethingelse.com'; // this will raise a TS error\nconst maybeCourse: Course = { '@type': 'Course', /* ... */ };\n// Event is an exception - it's labelled `Event_` because `Event` is not a permissable type name in TypeScript.\nconst myEvent: Event_ = { '@type': 'Event', /* ... */ };\n// TypeScript types for Schema.org models are in the schema namespace\nconst dayOfWeek: schema.DayOfWeek = 'https://schema.org/Sunday';\n\n// Each model has an additional type which can also accept an object which conforms to a sub-class of the model\n// e.g. `EventOrSubClass` can be used to annotate Events or ScheduledSessions (which sub-class Event)\n// Access these types at `{ model/enum name }OrSubClass`.\nconst scheduledSession: Event_OrSubClass = { '@type': 'ScheduledSession', /* ... */ };\n\n// Validator lives at `validate{ model/enum name}` e.g. `validateRequiredStatusType`\nconst maybeRequiredStatusType = validateRequiredStatusType(/* some data */);\nif (maybeRequiredStatusType instanceof OaValidationError) {\n  // The data did not conform to the RequiredStatusType type.\n  // From this point on, `maybeRequiredStatusType` will have type `OaValidationError`\n  const error = maybeRequiredStatusType;\n  // Do something with the error. Maybe ignore it? Or log it? Or throw? Up to you.\n} else {\n  // The data _did_ conform to the RequiredStatusType type.\n  // From this point on, `maybeRequiredStatusType` will have type `RequiredStatusType.Type`\n  const requiredStatusType = maybeRequiredStatusType;\n}\n// Again, validators for Schema.org models are in the schema namespace\nconst maybeImageObject = schema.validateImageObject(/* some data */);\n\n// JOI Schema lives at `{ model/enum name }JoiSchema`, for OpenActive models, and `schema.{ model/enum name }JoiSchema` for Schema.org models.\nconst compositeJoiSchema = Joi.object({\n  somethingElse: Joi.string(),\n  requiredStatusType: RequiredStatusTypeJoiSchema,\n});\n\n// Each model has an additional JOI schema which can also validate an object which conforms to a sub-class of the model\n// e.g. `Event_OrSubClassJoiSchema` can be used to annotate Events or SessionSeries (which sub-classes Event)\n// Access these JOI schemas at `{ model/enum name}OrSubClassJoiSchema`.\nconst sessionSeries = Event_OrSubClassJoiSchema.validate({ '@type': 'SessionSeries', /* ... */ });\n```\n\nFind some more extensive example usage in `src/test/data-model-examples`.\n\n## Using Types in a JavaScript Project\n\nIt is recommended to use TypeScript, which allows for more seamless use of the types in this library. However, it is\nabsolutely possible to use them in JavaScript by using JSDoc.\n\nHere's how:\n\n1. Ensure you're using a TypeScript-aware editor like VSCode.\n2. Install TypeScript in your project\n\n    ```sh\n    npm install --save-dev typescript\n    ```\n3. Create a `tsconfig.json` file at the root of your project with the following contents:\n\n    ```json\n    {\n      \"compilerOptions\": {\n        \"noEmit\": true,\n        \"allowJs\": true,\n        \"checkJs\": true,\n      },\n      \"include\": [\n        \"src/**/*.js\" // replace with the path to all of your JS files.\n      ]\n    }\n    ```\n\n    The top 3 options mean that 1). TypeScript will not produce any output - it will just check files 2). It will\n    check .js files.\n\n    More info on options you can put in tsconfig.json [here](https://www.typescriptlang.org/tsconfig).\n\n    It is highly recommended that you use `\"strict\": true` in your `compilerOptions`, which improves TypeScript's\n    ability to catch issues before they happen live. However, if you do this, you will have to make sure to annotate\n    every function in your project.\n4. Annotate your functions and variables with type signatures using JSDoc.\n\n    e.g.\n\n    ```js\n    /**\n     * @param {number} x\n     * @param {number} y\n     * @returns {number}\n     */\n    function add(x, y) { return x + y; }\n\n    /**\n     * @template T\n     * @param {T} val\n     * @returns {{ val: T }}\n     */\n    function wrap(val) { return { val }; }\n    ```\n\n    (Note: you will often not need to annotate return values, which TypeScript can infer. You can see what TypeScript\n    has inferred by hovering over the function in VSCode).\n5. Run `npx tsc` to check your files. Ensure this happens frequently by including it in your CI scripts.\n\nSome examples of using `@openactive/models-ts` with JSDoc:\n\n```js\n/** @type {import('@openactive/models-ts').RequiredStatusType} */\nconst myRequiredStatusType = 'https://openactive.io/Required';\n/** @type {import('@openactive/models-ts').schema.ImageObject} */\nconst myImageObject = { '@type': 'ImageObject', /* ... */ };\n\n// You can use `@typedef` aliases in order to not have to type the whole `import('@openactive/models-ts')...` bit each time:\n/**\n * @typedef {import('@openactive/models-ts').Course} Course\n */\n\n// And here the `@typedef` alias is being used:\n/**\n * @param {Course}\n */\nfunction doSomethingToCourse(course) {\n  // ..\n}\n```\n\n## Contributing\n\n- `lib/*` files are generated by TypeScript, which are rebuilt with `npm build`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenactive%2Fmodels-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenactive%2Fmodels-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenactive%2Fmodels-ts/lists"}