LINCS Web Annotation Schema

LINCS Web Annotation Schema is a Typescript JSON Schema generator and validator for the browser and NodeJS. It extends the Web Annotation Model and provides the means to validate Web Annotations that follow this schema. The schema is defined by a JSON-LD object constructed using a combination of Typescript objects based on Zod and Ajv.

The first version of the schema follows this Table Alignment. Subsequent versions may introduce changes and improve upon this document.

You can check the modules and type definitions Type Docs. Check also the examples folder to see how to produce valid LINCS Web Annotations.

• LINCS Web Annotation Schema
  • Install
  • Use
    • Types
      • Parameters
      • ValidateResult
      • ValidationError
  • Assets
    • Ajv Schema Object
  • Typing
    • import types
  • Development
    • Linter
    • Tests
    • Versioning

Install

To install it as a dependency, simply type npm install @lincs.project/webannotation-schema

Use

Import the validate function from the module and pass the annotation object. It returns the ValidateResult object with one or two properties: valid is a boolean and errors lists where the errors occurred if the annotation is not valid.

import { validate } from '@lincs.project/webannotation-validator';

const validAnnotation = {...};
const resultValid = validate(validAnnotation);
console.log(resultValid);
/*
{ valid: true }
*/

const invalidAnnotation = {...};
const resultInvalid = validate(invalidAnnotation);
console.log(resultInvalid);
/*
{
  valid: false,
  error: [
    {
      "message": "property 'type' must not have fewer than 2 items",
      "path": "{annotation}.generator.type",
      "context": {
        "errorType": "minItems"
      }
    },
    {
      "message": "'0' property must be equal to the allowed value",
      "path": "{annotation}.generator.type.0",
      "context": {
          "errorType": "const",
          "allowedValue": "Software"
      }
    }
  ]
}
*/

Types

Parameters

| Name | Type | Description | | --------------------- | ------ | ------------------------- | | Web Annotation Object | object | The Web Annotation Object |

ValidateResult

| Name | Type | Description | | ------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | valid* | boolean | If the Annotation is valid or not | | Error | ValidationError[] | Collection of error ValidationError from better-ajv-errors |

ValidationError

| Name | Type | Description | | ---------- | ------ | ------------------------------------ | | message* | string | Information about the error | | path* | string | Error location | | context* | object | Specific information about the error | | suggestion | string | Suggestion of correction |

Assets

Beyond the validate function, this module export multiple assets that can be used to build a custom validator (Ajv Schema Object) or assist the developer in building Web Annotations using Typescript (Typing).

Ajv Schema Object

It can be used to combine a custom validator.

• JSONSchemaType

import { definitionSchema, webAnnotationSchema } from '@lincs.project/webannotation-schema';

• Schema Ids (string)

import { defsId, schemaId } from '@lincs.project/webannotation-schema';

• Schema Context (JSON)

import { schemaContext } from '@lincs.project/webannotation-schema';

Typing

This module exports types. Check the available types in the documentation here.

import types

import type {
  Body,
  Creator,
  Motivation,
  Software,
  Status,
  Target,
  User,
  WebAnnotation,
} from '@lincs.project/webannotation-schema';

It is also possible to import Zod Schema.

import {
  Body,
  Creator,
  Motivation,
  Software,
  Status,
  Target,
  User,
  WebAnnotation,
} from '@lincs.project/webannotation-schema';

Development

Generate a new version of the schema with valid examples.

npm run generate-auxiliar-files

Linter

Attention!

The linter is partily setup ath the monorepo level (check the root of this project). We have configured a tight linter with strict Typescript and format (prettier) rules. Some of these rules can be relaxed if needed. Check eslint config: .eslintrc.js.

The linter always runs before any commit. But you can also run it at any time to check the code.

npm run lint

Tests

This project use jest and mock tests to check the request and response from each endpoint. These tests will run before each commit.

You can also run them manually.

npm test

Versioning

We follow Semantic Versioning. But it is important to note that the context and the schema are made public available on the web. They are also used in our web service for validation . Thus, when introducing changes, especially if there are breaking changes, it is important to update the schema IDs and introduce the new version in the web service.