One common question I see with a lot of new TypeScript developers is how to handle runtime validation of data, using the types they have built.
The issue is that the web platform, as yet, does not support types. Typescript itself is a higher-level language built on top of JavaScript and uses a compiler to create compatible code for the web, node or other JS platforms - this means that types are only available at design time.
Most developers have a method or form in their code where they want to validate that the data being passed in is correct before sending it to another API. This works for hard coded data in Typescript, but not dynamic data from sources such as a form or API source
The good news is that the problem itself has been solved and there are several solutions for TypeScript such as
io-ts or joi but I find these solutions to encourage
duplication of types across different domains to maintain both your types and validation objects.
Introducing JSON Schema
A much simpler way to maintain both types and validation within a project is to use a single source of truth.
The main option for this is JSON Schema.
A JSON Schema file allows you to define the a type using a JSON file, using a specification defined by the selected
draft (at the time of writing it's number 7).
This file can be used to generate types for design time coding using CLI tools, and can be used for data validation at runtime using another library that can consume a schema to generate a validation method.
Schema Example
For this demo I've created a simple schema object defining a customer within a system. The customers properties are:
IDfirstNamelastNamedateOfBirthemail
In this example we set "additionalProperties": false to keep the example simple, but it's a very flexible option!
If set to true or not included, the outputted types will include an indexable type with a [key: string]: any at the end of the type properties.
You can also pass it properties such as "additionalProperties": { "type": "string" } which will allow only string additional properties to be added.
By setting to false - only the properties defined will be available on the type, which I'll do for this example:
{
"$id": "https://tane.dev/customer.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Customer Record",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The Customers ID in our system"
},
"firstName": {
"type": "string",
"description": "The customer's first name."
},
"lastName": {
"type": "string",
"description": "The customer's last name."
},
"email": {
"type": "string",
"format": "email",
"description": "The customers email address"
},
"dateOfBirth": {
"type": "string",
"format": "date",
"description": "The customer's date of birth."
}
},
"additionalProperties": false,
"required": [
"id",
"firstName",
"lastName",
"dateOfBirth",
"email"
]
}
The first tool we will run this through is the imaginatively titled json-schema-to-typescript!
This project will take valid schema file and generate a file containing the types. From the example above the output is:
json2ts -i customer.json -o customer.d.ts --style.singleQuote
/* tslint:disable */
/**
* This file was automatically generated by json-schema-to-typescript.
* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
* and run json-schema-to-typescript to regenerate this file.
*/
export interface CustomerRecord {
/**
* The Customers ID in our system
*/
id: string;
/**
* The customer's first name.
*/
firstName: string;
/**
* The customer's last name.
*/
lastName: string;
/**
* The customers email address
*/
email: string;
/**
* The customer's date of birth.
*/
dateOfBirth: string;
}
One thing to note is that email and dateOfBirth are string in our type, the format is only used with validation. If is possible to create types for these fields and reference them using a more
complex schema.
This type can now be imported into other types, and the json-schema-to-typescript will do this when you use complex references. For example if we define an entire customer order type it might look like this:
import { CustomerRecord } from './customer';
import { OrderItem, Checkout, Address } from './shop-front'
export interface CustomerOrder {
customer: CustomerRecord;
deliveryAddress: Address;
billingAddress: Address;
items: OrderItem[]
checkout: Checkout
}
Also all the properties have been added to the required array. When creating a new customer, if the data does not contain an ID, you can use the Partial type to accept an incomplete object - if you expect your API to give back a full object you can return a CustomerRecord. You can also used Required where you need ensure all fields are passed.
import { CustomerRecord } from './customer';
class CustomerClass {
// Return a API request with a customers object
async addCustomer(customer: Partial<CustomerRecord>): Promise<CustomerRecord> {
return this.api.save(customer);
}
// Return a API request with a customers object
async updateCustomer(customer: Required<CustomerRecord>): Promise<CustomerRecord> {
return this.api.update(customer);
}
}
Validating with the Schema
Now you have types, it makes development of your application easier - but we still need to validate that the data entered is correct.
One way is to use the same schema on the server side, using your languages JSON Schema validator, but in this example I'll use ajv - a javascript library that allows a schema to be loaded and data validated against it. The documentation is quite complete on using it in a JavaScript environment so I won't repeat it too much here, but instead I'll build an Angular module that can be provided as a schema validation service.
First we'll create the Angular module, in to which we inject the AJV class and allow the user to provide a configuration, the service is provided below. This allows the module to be imported with a configuration, and a service that is injectable through your application.
import { NgModule, InjectionToken } from '@angular/core';
import { HttpClientModule } from '@angular/common/http'
import { JSONSchemaService, AJV_INSTANCE } from './json-schema.service';
import ajv, { Ajv, Options } from 'ajv';
export const AJV_CLASS = new InjectionToken<Ajv>('The AJV Class Instance');
export const AJV_CONFIG = new InjectionToken<Ajv>('The AJV Class config');
export function createAjvInstance(AjvClass: any, config: Options) {
return new AjvClass(config);
}
@NgModule({
import: [HttpClientModule],
provides: [
JSONSchemaService,
{ provide: AJV_CLASS, useValue: ajv },
{ provide: AJV_CONFIG, useValue: {} },
{
provide: AJV_INSTANCE,
useFactory: createAjvInstance,
deps: [AJV_CLASS, AJV_CONFIG]
}
]
})
export class JSONSchemaModule {}
Now we create a service - within this service it will access to the Ajv class that allows the service to be provided with schemas via an Angular HTTP call. The parsed schema is assigned a name and can be used through the app using dependency injection - this service is a good use case of a root service too, which create a Singleton of the service shared within the same application.
import { Injectable, Inject, InjectionToken } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Ajv } from 'ajv';
export const AJV_INSTANCE = new InjectionToken<Ajv>('The AJV Class Instance');
/**
* The response of a validation result
*/
export interface ValidateResult {
/**
* If the result is valid or not
*/
isValid: boolean;
/**
* Error text from the validator
*/
errorsText: string;
}
@Injectable({
provideIn: 'root'
})
export class JSONSchemaService {
constructor(private readonly http: HttpClient, @Inject(AJV_INSTANCE) private readonly ajv: Ajv) {}
/**
* Fetches the Schema and adds it to the validator schema set
* @param name The name of the schema, this will be used as the key to store it
* @param urlPath The URL path of the schema to load
*/
public loadSchema(name: string, urlPath: string): void {
this.http.get(urlPath).subscribe(result => this.ajv.addSchema(result, name));
}
/**
* Validate data against a schema
* @param name The name of the schema to validate
* @param data The data to validate
*/
public validateData<T>(name: string, data: T): ValidateResult {
const isValid = this.ajv.validate(name, data) as boolean;
return { isValid, errorsText: this.ajv.errorsText() };
}
}
Now we can use our service to load a JSON schemas into an internal Ajv map, and using the key load the schema to validate a data object against it. The service could be used alongside a form, any methods on a service or checking the result of one API before passing to another API.
A simple example of how it could be used in a form components (the example is shortened, most likely you would load your schemas from another service) or how you could validate the parameters passed to a method:
@Component({
selector: 'my-form-component',
template: `
<errors-component *ngIf="let errors; errors$ | async"></errors-component>
<form [formGroup]="customerForm" (ngSubmit)="submit()">
<!-- Customer form in here --->
</form>
`
})
export class FormComponent {
error$ = new BehaviorSubject<string>('');
customerForm = this.fb.group({
id: [''],
firstName: [''],
lastName: [''],
email: [''],
dateOfBirth: ['']
});
constructor(private readonly fb: FormBuilder, private readonly schema: JSONSchemaService, private readonly app: AppService) {
this.schema.loadSchema('customer', 'https://tane.dev/customer.json')
}
/**
* In the submit method, we validate the input of a form - this can be on top of, or instead
* of Angular form validation
*/
submit() {
const result = this.schema.validateData('customer', this.customerForm.value);
if (result.isValid) {
this.app.updateCustomer(this.customerForm.value);
} else {
this.error$.next(result.errorsText);
}
}
/**
* This custom method can take a type of T (which in this case is an `any`) and validate
* that the data is valid
*/
customMethod<T = any>(data: T) {
const result = this.schema.validateData('customer', data);
if (result.isValid) {
// Do custom logic
} else {
this.error$.next(result.errorsText);
}
}
}
Conclusion
I hope you've found this article useful in helping understand how and where Typescript can be used to validate data within an application, and JSON Schema to validate dynamic data.
Please feel free to leave feedback on any issues or improvements, but hopefully, these examples give a clearer understanding.
For full documentation of JSON Schema, check out the Understanding JSON Schema
pages to get examples of using allOf, anyOf, oneOf and using definitions
Top comments (0)