{"id":19338481,"url":"https://github.com/gbv/jskos-tools","last_synced_at":"2025-04-23T01:31:26.932Z","repository":{"id":32897231,"uuid":"143127556","full_name":"gbv/jskos-tools","owner":"gbv","description":"Tools for working with the JSKOS data format.","archived":false,"fork":false,"pushed_at":"2025-03-17T14:02:11.000Z","size":2495,"stargazers_count":4,"open_issues_count":18,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-19T14:15:47.245Z","etag":null,"topics":["coli-conc","library"],"latest_commit_sha":null,"homepage":"https://gbv.github.io/jskos-tools/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-01T08:33:58.000Z","updated_at":"2025-03-05T08:26:02.000Z","dependencies_parsed_at":"2023-02-17T03:40:21.445Z","dependency_job_id":"2a6312aa-b39c-4dec-b789-c035ac33f202","html_url":"https://github.com/gbv/jskos-tools","commit_stats":null,"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbv%2Fjskos-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbv%2Fjskos-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbv%2Fjskos-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbv%2Fjskos-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbv","download_url":"https://codeload.github.com/gbv/jskos-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250352299,"owners_count":21416465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coli-conc","library"],"created_at":"2024-11-10T03:17:36.690Z","updated_at":"2025-04-23T01:31:26.561Z","avatar_url":"https://github.com/gbv.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSKOS Tools\n\n[![Test](https://github.com/gbv/jskos-tools/actions/workflows/test-and-build.yml/badge.svg)](https://github.com/gbv/jskos-tools/actions/workflows/test-and-build.yml)\n[![GitHub package version](https://img.shields.io/github/package-json/v/gbv/jskos-tools.svg?label=version)](https://github.com/gbv/jskos-tools)\n[![NPM package name](https://img.shields.io/badge/npm-jskos--tools-blue.svg)](https://www.npmjs.com/package/jskos-tools)\n[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme)\n\n\u003e Tools for working with the JSKOS data format.\n\nThis repository contains tools for working with the [JSKOS data format for knowledge organization systems](http://gbv.github.io/jskos/).\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [Mapping Identifiers](#mapping-identifiers)\n    - [mappingContentIdentifier](#mappingcontentidentifier)\n    - [mappingMembersIdentifier](#mappingmembersidentifier)\n    - [addMappingIdentifiers](#addmappingidentifiers)\n    - [compareMappings](#comparemappings)\n    - [compareMappingMembers](#comparemappingmembers)\n  - [ConceptScheme](#conceptscheme)\n  - [languagePreference](#languagepreference)\n    - [How to Configure](#how-to-configure)\n    - [getLanguages](#getlanguages)\n    - [selectLanguage](#selectlanguage)\n  - [Tools](#tools)\n    - [addContext](#addcontext)\n    - [clean](#clean)\n    - [copyDeep](#copydeep)\n    - [getAllUris](#getalluris)\n    - [compare](#compare)\n    - [isConcept](#isconcept)\n    - [isScheme](#isscheme)\n    - [isContainedIn](#iscontainedin)\n    - [sortConcepts](#sortconcepts)\n    - [sortSchemes](#sortschemes)\n    - [minifyMapping](#minifymapping)\n    - [mappingTypes](#mappingtypes)\n    - [mappingTypeByUri](#mappingtypebyuri)\n    - [mappingTypeByType](#mappingtypebytype)\n    - [defaultMappingType](#defaultmappingtype)\n    - [flattenMapping](#flattenmapping)\n    - [mappingCSV](#mappingcsv)\n    - [serializeCSV](#serializecsv)\n    - [conceptsOfMapping](#conceptsofmapping)\n    - [compareMappingsDeep](#comparemappingsdeep)\n    - [matchObjectTypes](#matchobjecttypes)\n    - [mergeUris](#mergeuris)\n    - [merge](#merge)\n    - [normalize](#normalize)\n    - [isValidUri](#isvaliduri)\n    - [objectTypes](#objecttypes)\n    - [guessObjectType](#guessobjecttype)\n    - [guessSchemeFromNotation](#guessschemefromnotation)\n    - [compareFunctions](#comparefunctions)\n    - [userOwnsMapping](#userownsmapping)\n    - [notation](#notation)\n    - [languageMapContent](#languagemapcontent)\n    - [prefLabel](#preflabel)\n    - [definition](#definition)\n    - [mappingRegistryIsStored](#mappingregistryisstored)\n    - [annotationCreatorUri](#annotationcreatoruri)\n    - [annotationCreatorName](#annotationcreatorname)\n    - [annotationCreatorMatches](#annotationcreatormatches)\n- [Build](#build)\n- [Test](#test)\n- [Maintainers](#maintainers)\n- [Publish](#publish)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Install\n\n```bash\nnpm i jskos-tools\n```\n\njskos-tools requires Node.js 18 or later.\n\nWe are also providing browser bundles:\n- Development (not minified, ~19K gzipped, ~68K not gzipped): https://cdn.jsdelivr.net/npm/jskos-tools/dist/jskos-tools.js\n- **Production** (minified, ~10K gzipped, ~26K not gzipped): https://cdn.jsdelivr.net/npm/jskos-tools@1/dist/jskos-tools.min.js\n\n[![](https://data.jsdelivr.com/v1/package/npm/jskos-tools/badge?style=rounded)](https://www.jsdelivr.com/package/npm/jskos-tools)\n\n## Usage\nIf you installed jskos-tools via npm, use it like this:\n\n```js\nconst jskos = require(\"jskos-tools\")\n```\n\nOr as an ES module:\n\n```js\nimport * as jskos from \"jskos-tools\"\n```\n\nUsing the browser bundles will provide you with the `jskos` global variable.\n\nSee \u003chttps://gbv.github.io/jskos-tools/\u003e for full API documentation of\n[module jskos-tools](https://gbv.github.io/jskos-tools/module-jskos-tools.html).\n\n### Mapping Identifiers\n\n```js\nlet mapping = {\n  ...\n}\n```\n\n#### mappingContentIdentifier\n`mappingContentIdentifier` starts with urn:jskos:mapping:content: and takes concepts and type into consideration. It uses the `mappingContent` function to get relevant properties from the mapping.\n\n```js\nlet contentIdentifier = jskos.mappingContentIdentifier(mapping)\n```\n\n#### mappingMembersIdentifier\n`mappingMembersIdentifier` starts with urn:jskos:mapping:members: and only takes concepts into consideration. It uses the `mappingMembers` function to get relevant properties from the mapping.\n\n```js\nlet membersIdentifier = jskos.mappingMembersIdentifier(mapping)\n```\n\n#### addMappingIdentifiers\n`addMappingIdentifiers` creates a new mapping with property \"identifiers\", containing mappingContentIdentifier and mappingMembersIdentifier.\n\n```js\nlet mappingWithIdentifiers = jskos.addMappingIdentifiers(mapping)\n```\n\n#### compareMappings\n`compareMappings` compares two mappings based on their `mappingContentIdentifier`.\n\n```js\nif (jskos.compareMappings(mapping1, mapping2)) { ... }\n```\n\nAliases: `compareMappingContent`\n\n#### compareMappingMembers\n`compareMappingMembers` compares two mappings based on their `mappingMembersIdentifier`.\n\n```js\nif (jskos.compareMappingMembers(mapping1, mapping2)) { ... }\n```\n\n### ConceptScheme\n\nSee [class ConceptScheme](https://gbv.github.io/jskos-tools/module-jskos-tools.ConceptScheme.html).\n\n### languagePreference\n\nUsed to provide access to a preference list of language tags.\n\n#### How to Configure\n\nIf this is used inside a web application that allows multiple interface languages and depends on reactivity, it is necessary to properly configure this at the start of the application. There are two ways to do this:\n\n1. Provide a reference to the Vuex store and path where the language preference list of the application resides:\n```javascript\nconst store = require(\"./store\") // import the Vuex store\njskos.languagePreference.store = store\njskos.languagePreference.path = \"state.languages\" // or wherever your languages array resides\n```\n\nNote: In theory, `store` doesn't HAVE to be a Vuex store. It could be any kind of object which contains the `languages` array somewhere. (See also: [Tests](https://github.com/gbv/jskos-tools/blob/master/test/language-preference.js#L34-L39))\n\n2. Provide a reference to a preference list array of languages tags directly via `defaults`. Note: Make sure that this array only gets modified in-place, otherwise you will override the previous reference to the array. (Example using [array.prototype.move](https://www.npmjs.com/package/array.prototype.move).)\n\n```javascript\nconst languages = [\"en\", \"de\"]\njskos.languagePreference.defaults = languages\nlanguages.move(1, 0) // moves \"de\" to the front of the preference list\n```\n\n#### getLanguages\n\nReturns the current preference list of language tags (either from `store` or `defaults`).\n\n#### selectLanguage\n\nSelects a language tag from a language map according to the current preference list or `null` if no language was found.\n\n### Tools\n\n#### addContext\nAdd `@context` URI to a JSKOS object or to an array of JSKOS objects.\n\n```js\njskos.addContext(object)\n```\n\n#### clean\nRemoves properties starting with `_` or containing only uppercase letters from a JSKOS object.\n\n```js\njskos.clean(object)\n```\n\nAliases: `cleanJSKOS`\n\n#### copyDeep\nCreates a deep copy of a JSKOS object, replacing possibly circular structures with open world `[null]` statements. As the second argument it is possible to add additional properties that should be replaced with open world `[null]` statements. The third argument determines whether all properties starting with `_` should be ignored (`true` by default).\n\n```js\njskos.copyDeep(object)\njskos.copyDeep(object, [\"someCircularProperty\"])\njskos.copyDeep(object, null, false)\n```\n\nAliases: `deepCopy`\n\n#### getAllUris\nReturns all possible URIs for a JSKOS object. Takes into consideration both the uri and identifier properties, as well as different variants of those identifiers. Returns an empty array if object is `null`.\n\n```js\njskos.getAllUris(object)\n```\n\n#### compare\nCompares two objects based on their URIs, using `getAllUris`. Returns `true` if both objects are `null`.\n\n```js\njskos.compare(object1, object2)\n```\n\nAliases: `compareObjects`, `compareSchemes`, `compareConcepts`\n\n#### isConcept\nChecks whether JSKOS object is a concept based on type property.\n\n```js\njskos.isConcept(object)\n```\n\n#### isScheme\nChecks whether JSKOS object is a concept scheme based on type property.\n\n```js\njskos.isScheme(object)\n```\n\n#### isContainedIn\n// Checks whether an object is contained in a list of objects using `compare`.\n\n```js\njskos.isContainedIn(object, listOfObjects)\n```\n\nAliases: `isSchemeInList`\n\n#### sortConcepts\nSorts a list of concepts by their notation, then URI. Returns a copy of the list. If the second parameter is `true`, it will try to sort by numerical notations.\n\n```js\njskos.sortConcepts(concepts)\n```\n\n#### sortSchemes\nSorts a list of schemes by their prefLabel (de or en), then notation, then URI. Returns a copy of the list.\n\n```js\njskos.sortSchemes(schemes)\n```\n\n#### minifyMapping\nRemoves unnecessary properties from mapping before export or saving. In particular, all properties except for `to`, `from`, `toScheme`, `fromScheme`, `type`, `creator`, `contributor`, `created`, `modified`, `note`, and `identifier` on the mapping will be removed, and all properties except for `uri` and `notation` on concepts and schemes will be removed.\n\n```js\nlet newMapping = jskos.minifyMapping(mapping)\n```\n\n#### mappingTypes\nAn array of mapping types in form of objects. Objects can have the following properties:\n\n- `notation` - an array of notations (in this case symbols)\n- `uri` - the URI of the mapping type\n- `prefLabel` - a language maps of labels\n- `broader` - array of broader mapping types for this type\n- `related` - array of related mapping types\n- `RELEVANCE` - relevance label for GND terms (low, medium, high, very high)\n- `SHORT` - a short name for the type, used for CSV import/export\n\nThe labels are taken from Wikidata (see script `bin/localize-mapping-types`).\n\nExample object:\n```json\n{\n  \"notation\": [\"≈\"],\n  \"uri\": \"http://www.w3.org/2004/02/skos/core#closeMatch\",\n  \"prefLabel\": { \"en\": \"close match\" },\n  \"broader\": [ { \"uri\": \"http://www.w3.org/2004/02/skos/core#mappingRelation\" } ],\n  \"RELEVANCE\": \"high\",\n  \"SHORT\": \"close\"\n}\n```\n\n#### mappingTypeByUri\nReturns a mapping type object for an URI.\n\n```js\njskos.mappingTypeByUri(\"http://www.w3.org/2004/02/skos/core#closeMatch\")\n```\n\n#### mappingTypeByType\nReturns a mapping type for a JSKOS type property. This is usually an array where the first type is taken, but a workaround for string types is included as well.\n\n```js\njskos.mappingTypeByType(mapping.type)\n```\n\n#### defaultMappingType\nThe default mapping type (currently `mapping relation`).\n\n#### flattenMapping\nConverts a mapping into a flat object with for serialization as CSV. Returns an object with fields `fromNotation`, `toNotation`, `type`, and (if option `language` has been provided) `fromLabel`, `toLabel`, and `creator`.\n\n#### mappingCSV\nReturns an object of preconfigured conversion functions to convert mappings into CSV. Supports 1-to-1, 1-to-n, and n-to-n mappings.\n\n```js\n// Initialize converter with default options\nconst csv = jskos.mappingCSV({\n  delimiter: \",\",\n  quoteChar: \"\\\"\",\n  lineTerminator: \"\\n\",\n  type: true,\n  schemes: false,\n  labels: false,\n  creator: false,\n  language: \"en\",\n})\n// Header line for an array of mappings (assuming 1-to-1 mappings if no array is given)\ncsv.header(mappings)\n// Single CSV line for a mapping (uses fromCount and toCount from the mapping by default)\ncsv.fromMapping(mapping, { fromCount: null, toCount: null })\n// Multiline CSV from array of mappings (includes header by default)\ncsv.fromMappings(mappings, { header: true })\n```\n\nThe order of the CSV fields is fromScheme, fromNotation, (fromLabel,) (fromNotation2, fromLabel2, ...) toNotation, (toLabel,) (toNotation2, toLabel2, ...) type, creator.\n\n#### serializeCSV\nReturns a function to serialize an array as CSV row as configured with [CSV Dialect](\u003chttps://frictionlessdata.io/specs/csv-dialect/\u003e).\n\n#### conceptsOfMapping\nReturns an array of concepts contained in a mapping. `side` can either be `from` or `to`. If `side` is left out, concepts from both sides will be returned. `null` values will be omitted.\n\n```js\njskos.conceptsOfMapping(mapping)\n```\n\n#### compareMappingsDeep\n`compareMappingsDeep` compares two mappings based on their properties. Concept sets and schemes are compared by URI.\n\n```js\nif (jskos.compareMappingsDeep(mapping1, mapping2)) { ... }\n```\n\n#### matchObjectTypes\nCompares two JSKOS objects based on their types. Returns `false` only if both types could be guessed using [`guessObjectType`](#guessobjecttype) and they did not match, otherwise it will assume that the types match.\n\n#### mergeUris\nMerge URIs of two objects `a` and `b` into `a` by adding/removing URIs from identifier property.\n\n#### merge\nMerges two JSKOS objects. See [documentation](https://gbv.github.io/jskos-tools/module-jskos-tools.html#.merge) for more information.\n\n#### normalize\nApplies recursive unicode normalization to data.\n\n#### isValidUri\nChecks whether a string is a valid URI.\n\n#### objectTypes\n\nAn object that maps JSKOS object type names to their description.\n\n#### guessObjectType\n\nGuess the JSKOS object type of an object, URI or name and return its canonical name.\n\n```js\ntype = guessObjectType(objectOrString)        // get full name such as `ConceptScheme`\ntype = guessObjectType(objectOrString, true)  // get short name such as `scheme`\n```\n\n#### guessSchemeFromNotation\n\nFilter a list of concept schemes with a given notation to guess which scheme(s) the notation origins from. Schemes without `notationPattern` or default pattern `.+` are ignored. Returns a (posssibly empty) array of concept schemes.\n\n```js\nmatchingSchemes = guessSchemeFromNotation(notation, schemes)\n```\n\n#### compareFunctions\n\nAn object containing compare functions that can be used with `array.sort()` etc.\n\nAvailable functions:\n- `compareFunctions.mappingsByConcepts` - compares mappings by the notations of their first concepts\n\n#### userOwnsMapping\n\nDetermines whether a ([login-server](https://github.com/gbv/login-server)-compatible) user owns a mapping (i.e. is the first `creator`) or not.\n\n#### notation\n\nReturns the primary notation for a JSKOS Item. If there is no notation, it will return an empty string. Scheme notations will be uppercased.\n\n#### languageMapContent\n\nReturns the content of a language map for a JSKOS Item.\n\n#### prefLabel\n\nReturns the prefLabel of a JSKOS Item. If there is no label, it will return the URI. If there is no URI, it will return an empty string.\n\n#### definition\n\nReturns the definition of a JSKOS Item as an array. If there is no definition, an empty array will be returned.\n\n#### mappingRegistryIsStored\n\nReturns whether a mapping registry has stored mappings (`true` = database) or not (`false` = recommendations).\n\n#### annotationCreatorUri\n\nReturns the creator URI for an annotation.\n\n#### annotationCreatorName\n\nReturns the craetor name for an annotation.\n\n#### annotationCreatorMatches\n\nMatches an annotation's creator URI against a list of URIs (e.g. from a user).\n\n## Build\n\n```bash\ngit clone --recursive https://github.com/gbv/jskos-tools.git\ncd jskos-tools/\nnpm install\n```\n\nAPI documentation can be generated in directory `jsdoc/build`:\n\n```bash\nnpm run docs\n```\n\n## Test\n\n```bash\nnpm test\n```\n\n## Maintainers\n\n- [@stefandesu](https://github.com/stefandesu)\n- [@nichtich](https://github.com/nichtich)\n\n## Publish\nPlease work on the `dev` branch during development (or better yet, develop in a feature branch and merge into `dev` when ready).\n\nWhen a new release is ready (i.e. the features are finished, merged into `dev`, and all tests succeed), run the included release script (replace \"patch\" with \"minor\" or \"major\" if necessary):\n\n```bash\nnpm run release:patch\n```\n\nThis will:\n- Run tests and build to make sure everything works\n- Switch to `dev`\n- Make sure `dev` is up-to-date\n- Run `npm version patch` (or \"minor\"/\"major\")\n- Push changes to `dev`\n- Switch to `master`\n- Merge changes from `dev`\n- Push `master` with tags\n- Switch back to `dev`\n\nAfter running this, GitHub Actions will automatically publish the new version to npm. It will also create a new GitHub Release draft. Please edit and publish the release manually.\n\n## Contribute\n\nPRs accepted.\n\nSmall note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.\n\n## License\n\nMIT © 2018 Verbundzentrale des GBV (VZG)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbv%2Fjskos-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbv%2Fjskos-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbv%2Fjskos-tools/lists"}