models-ts

Model validation and TypeScript types for OpenActive's data model
This library works for both JavaScript and TypeScript developers, making it easier to conform to the OpenActive specifications.
Example:
import Joi from 'joi';
import {
OaValidationError,
Course,
Event_,
RequiredStatusType,
Event_OrSubClass,
validateRequiredStatusType,
RequiredStatusTypeJoiSchema,
Event_OrSubClassJoiSchema,
schema,
} from '@openactive/models-ts';
const myRequiredStatusType: RequiredStatusType = 'https://openactive.io/Required';
const myNotRequiredStatusType: RequiredStatusType = 'somethingelse.com';
const maybeCourse: Course = { '@type': 'Course', };
const myEvent: Event_ = { '@type': 'Event', };
const dayOfWeek: schema.DayOfWeek = 'https://schema.org/Sunday';
const scheduledSession: Event_OrSubClass = { '@type': 'ScheduledSession', };
const maybeRequiredStatusType = validateRequiredStatusType();
if (maybeRequiredStatusType instanceof OaValidationError) {
const error = maybeRequiredStatusType;
} else {
const requiredStatusType = maybeRequiredStatusType;
}
const maybeImageObject = schema.validateImageObject();
const compositeJoiSchema = Joi.object({
somethingElse: Joi.string(),
requiredStatusType: RequiredStatusTypeJoiSchema,
});
const sessionSeries = Event_OrSubClassJoiSchema.validate({ '@type': 'SessionSeries', });
Find some more extensive example usage in src/test/data-model-examples
.
Using Types in a JavaScript Project
It is recommended to use TypeScript, which allows for more seamless use of the types in this library. However, it is
absolutely possible to use them in JavaScript by using JSDoc.
Here's how:
-
Ensure you're using a TypeScript-aware editor like VSCode.
-
Install TypeScript in your project
npm install --save-dev typescript
-
Create a tsconfig.json
file at the root of your project with the following contents:
{
"compilerOptions": {
"noEmit": true,
"allowJs": true,
"checkJs": true,
},
"include": [
"src/**/*.js"
]
}
The top 3 options mean that 1). TypeScript will not produce any output - it will just check files 2). It will
check .js files.
More info on options you can put in tsconfig.json here.
It is highly recommended that you use "strict": true
in your compilerOptions
, which improves TypeScript's
ability to catch issues before they happen live. However, if you do this, you will have to make sure to annotate
every function in your project.
-
Annotate your functions and variables with type signatures using JSDoc.
e.g.
function add(x, y) { return x + y; }
function wrap(val) { return { val }; }
(Note: you will often not need to annotate return values, which TypeScript can infer. You can see what TypeScript
has inferred by hovering over the function in VSCode).
-
Run npx tsc
to check your files. Ensure this happens frequently by including it in your CI scripts.
Some examples of using @openactive/models-ts
with JSDoc:
const myRequiredStatusType = 'https://openactive.io/Required';
const myImageObject = { '@type': 'ImageObject', };
function doSomethingToCourse(course) {
}
Contributing
lib/*
files are generated by TypeScript, which are rebuilt with npm build