@lincs.project/webannotation-schema 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,12 @@
 # LINCS Web Annotation Schema
 
-![NPM](https://img.shields.io/npm/l/@cwrc/leafwriter-validator)
-![npm type definitions](https://img.shields.io/npm/types/@cwrc/leafwriter-validator)
+![npm (scoped)](https://img.shields.io/npm/v/%40lincs.project/webannotation-schema)
+![npm(scoped)](https://img.shields.io/npm/l/%40lincs.project/webannotation-schema)
+![npm (scoped) type definitions](https://img.shields.io/npm/types/%40lincs.project/webannotation-schema)
 
 LINCS Web Annotation Schema is a Typescript JSON Schema generator and validator for the browser and NodeJS. It extends the [Web Annotation Model](https://www.w3.org/TR/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](https://zod.dev/) and [Ajv](https://ajv.js.org/).
 
-The first version of the schema follows the discussion in this [document](https://docs.google.com/document/d/1SkrZTbHMDxupDmsmBsjTTdu7Inlny-eecg369zVaJNM/edit#heading=h.4pfo79y7up7t). Subsequent versions may introduce changes and improve upon this document.
+The first version of the schema follows this [Table Alignment](https://gitlab.com/calincs/conversion/lincs-webannotation/-/blob/main/LINCS%20Web%20Annotation%20Schema%20Alignment.md). Subsequent versions may introduce changes and improve upon this document.
 
 You can check the modules and type definitions [Type Docs](https://gitlab.com/calincs/conversion/lincs-webannotation/-/tree/main/packages/schema/docs). Check also the [examples](https://gitlab.com/calincs/conversion/lincs-webannotation/-/tree/main/packages/schema/examples) folder to see how to produce valid LINCS Web Annotations.
 
@@ -18,10 +19,11 @@ You can check the modules and type definitions [Type Docs](https://gitlab.com/ca
       - [ValidationError](#validationerror)
   - [Assets](#assets)
     - [Ajv Schema Object](#ajv-schema-object)
-  - [Typings](#typings)
+  - [Typing](#typing)
     - [import types](#import-types)
   - [Development](#development)
-    - [Testing](#testing)
+    - [Linter](#linter)
+    - [Tests](#tests)
     - [Versioning](#versioning)
 
 ## Install
@@ -40,17 +42,15 @@ const validAnnotation = {...};
 const resultValid = validate(validAnnotation);
 console.log(resultValid);
 /*
-{
-  valid: true
-}
+{ valid: true }
 */
 
 const invalidAnnotation = {...};
 const resultInvalid = validate(invalidAnnotation);
 console.log(resultInvalid);
-/* 
+/*
 {
-  valid: true,
+  valid: false,
   error: [
     {
       "message": "property 'type' must not have fewer than 2 items",
@@ -82,32 +82,32 @@ console.log(resultInvalid);
 
 #### ValidateResult
 
-| Name   | Type                                  | Description                                                                                                          |
-| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| valid* | boolean                               | If the Annotation is valid or not                                                                                    |
-| Error  | [ValidationError](#validationerror)[] | Collection of error ValidationError from [better-ajv-errors](https://github.com/apideck-libraries/better-ajv-errors) |
+| Name    | Type                                  | Description                                                                                                          |
+| ------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| valid\* | boolean                               | If the Annotation is valid or not                                                                                    |
+| Error   | [ValidationError](#validationerror)[] | Collection of error ValidationError from [better-ajv-errors](https://github.com/apideck-libraries/better-ajv-errors) |
 
 #### ValidationError
 
-| Name       | Type   | Description                         |
-| ---------- | ------ | ----------------------------------- |
-| message*   | string | Information about the error         |
-| path*      | string | Error location                      |
-| context*   | object | Specific information about the error |
+| 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](#ajv-schema-object)) or assist the developer in building Web Annotations using Typescript ([Typings](#typings)).
+Beyond the `validate` function, this module export multiple assets that can be used to build a custom validator ([Ajv Schema Object](#ajv-schema-object)) or assist the developer in building Web Annotations using Typescript ([Typing](#typing)).
 
 ### Ajv Schema Object
 
 It can be used to combine a custom validator.
 
 - JSONSchemaType
-  
+
 ```ts
-import {definitionSchema, webAnnotationSchema } from '@lincs.project/webannotation-schema';
+import { definitionSchema, webAnnotationSchema } from '@lincs.project/webannotation-schema';
 ```
 
 - Schema Ids (string)
@@ -119,37 +119,71 @@ import { defsId, schemaId } from '@lincs.project/webannotation-schema';
 - Schema Context (JSON)
 
 ```ts
-import {schemaContext} from '@lincs.project/webannotation-schema';
+import { schemaContext } from '@lincs.project/webannotation-schema';
 ```
 
-## Typings
+## Typing
 
 This module exports types. Check the available types in the documentation [here](?).
 
 ### import types
 
 ```ts
-import type { Body, Creator, Motivation, Software, Status, Target, User, WebAnnotation } from '@lincs.project/webannotation-schema';
+import type {
+  Body,
+  Creator,
+  Motivation,
+  Software,
+  Status,
+  Target,
+  User,
+  WebAnnotation,
+} from '@lincs.project/webannotation-schema';
 ```
 
 It is also possible to import Zod Schema.
 
 ```ts
-import { Body, Creator, Motivation, Software, Status, Target, User, WebAnnotation } from '@lincs.project/webannotation-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`
+`npm run generate-auxiliar-files`
+
+### Linter
+
+**Attention!**
 
-### Testing
+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`.
 
-We use jest for testing.
+The linter always runs before any commit. But you can also run it at any time to check the code.
 
-`npm test`
+```node
+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.
+
+```node
+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 [link](link). 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.
+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](<(https://gitlab.com/calincs/conversion/lincs-webannotation/-/tree/main/apps/api/examples)>) 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.