@lincs.project/webannotation-schema 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# 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)
+
+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.
+
+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.
+
+- [LINCS Web Annotation Schema](#lincs-web-annotation-schema)
+  - [Install](#install)
+  - [Use](#use)
+    - [Types](#types)
+      - [Parameters](#parameters)
+      - [ValidateResult](#validateresult)
+      - [ValidationError](#validationerror)
+  - [Assets](#assets)
+    - [Ajv Schema Object](#ajv-schema-object)
+  - [Typings](#typings)
+    - [import types](#import-types)
+  - [Development](#development)
+    - [Testing](#testing)
+    - [Versioning](#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](#validateresult) object with one or two properties: `valid` is a boolean and `errors` lists where the errors occurred if the annotation is not valid.
+
+```ts
+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: true,
+  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](#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 |
+| 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)).
+
+### Ajv Schema Object
+
+It can be used to combine a custom validator.
+
+- JSONSchemaType
+  
+```ts
+import {definitionSchema, webAnnotationSchema } from '@lincs.project/webannotation-schema';
+```
+
+- Schema Ids (string)
+
+```ts
+import { defsId, schemaId } from '@lincs.project/webannotation-schema';
+```
+
+- Schema Context (JSON)
+
+```ts
+import {schemaContext} from '@lincs.project/webannotation-schema';
+```
+
+## Typings
+
+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';
+```
+
+It is also possible to import Zod Schema.
+
+```ts
+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`
+
+### Testing
+
+We use jest for testing.
+
+`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.

package/dist/context.jsonld

@@ -0,0 +1,24 @@
+{
+  "bf": "http://www.openlinksw.com/schemas/bif#",
+  "cito": "https://sparontologies.github.io/cito/current/cito.html#",
+  "cwrc": "http://id.lincsproject.ca/cwrc#",
+  "edit": "http://id.lincsproject.ca/edit/#",
+  "fabio": "https://purl.org/spar/fabio#",
+  "frbroo": "https://www.iflastandards.info/fr/frbr/frbroo#",
+  "wikidata": "https://www.wikidata.org/wiki/",
+  "crm": "http://www.cidoc-crm.org/cidoc-crm/",
+  "crmdig": "http://www.ics.forth.gr/isl/CRMdig/",
+  "certainty": "crm:P2_has_type",
+  "contributor": "dcterms:contributor",
+  "description": "rdfs:comment",
+  "precision": "crm:P2_has_type",
+  "softwareVersion": "schema:softwareVersion",
+  "status": "crm:P2_has_type",
+  "entityType": "crm:P2_has_type",
+  "addicionalType": "crm:P2_has_type",
+  "approved": "edit:statusApproved",
+  "citing": "edit:citing",
+  "correcting": "edit:correcting",
+  "draft": "edit:statusDraft",
+  "published": "edit:statusPublished"
+}