jskos-tools

    1.0.26 • Public • Published

    JSKOS Tools

    Test GitHub package version NPM package name standard-readme compliant

    Tools for working with the JSKOS data format.

    This repository contains tools for working with the JSKOS data format for knowledge organization systems.

    Table of Contents

    Install

    npm i jskos-tools

    We are also providing browser bundles:

    Usage

    If you installed jskos-tools via npm, use it like this:

    const jskos = require("jskos-tools")

    Using the browser bundles will provide you with the jskos global variable.

    See https://gbv.github.io/jskos-tools/ for full API documentation of module jskos-tools.

    Mapping Identifiers

    let mapping = {
      ...
    }

    mappingContentIdentifier

    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.

    let contentIdentifier = jskos.mappingContentIdentifier(mapping)

    mappingMembersIdentifier

    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.

    let membersIdentifier = jskos.mappingMembersIdentifier(mapping)

    addMappingIdentifiers

    addMappingIdentifiers creates a new mapping with property "identifiers", containing mappingContentIdentifier and mappingMembersIdentifier.

    let mappingWithIdentifiers = jskos.addMappingIdentifiers(mapping)

    compareMappings

    compareMappings compares two mappings based on their mappingContentIdentifier.

    if (jskos.compareMappings(mapping1, mapping2)) { ... }

    Aliases: compareMappingContent

    compareMappingMembers

    compareMappingMembers compares two mappings based on their mappingMembersIdentifier.

    if (jskos.compareMappingMembers(mapping1, mapping2)) { ... }

    ConceptScheme

    See class ConceptScheme.

    languagePreference

    Used to provide access to a preference list of language tags.

    How to Configure

    If 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:

    1. Provide a reference to the Vuex store and path where the language preference list of the application resides:
    const store = require("./store") // import the Vuex store
    jskos.languagePreference.store = store
    jskos.languagePreference.path = "state.languages" // or wherever your languages array resides

    Note: 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)

    1. 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.)
    const languages = ["en", "de"]
    jskos.languagePreference.defaults = languages
    languages.move(1, 0) // moves "de" to the front of the preference list

    getLanguages

    Returns the current preference list of language tags (either from store or defaults).

    selectLanguage

    Selects a language tag from a language map according to the current preference list or null if no language was found.

    Tools

    addContext

    Add @context URI to a JSKOS object or to an array of JSKOS objects.

    jskos.addContext(object)

    clean

    Removes properties starting with _ or containing only uppercase letters from a JSKOS object.

    jskos.clean(object)

    Aliases: cleanJSKOS

    copyDeep

    Creates 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).

    jskos.copyDeep(object)
    jskos.copyDeep(object, ["someCircularProperty"])
    jskos.copyDeep(object, null, false)

    Aliases: deepCopy

    getAllUris

    Returns 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.

    jskos.getAllUris(object)

    compare

    Compares two objects based on their URIs, using getAllUris. Returns true if both objects are null.

    jskos.compare(object1, object2)

    Aliases: compareObjects, compareSchemes, compareConcepts

    isConcept

    Checks whether JSKOS object is a concept based on type property.

    jskos.isConcept(object)

    isScheme

    Checks whether JSKOS object is a concept scheme based on type property.

    jskos.isScheme(object)

    isContainedIn

    // Checks whether an object is contained in a list of objects using compare.

    jskos.isContainedIn(object, listOfObjects)

    Aliases: isSchemeInList

    sortConcepts

    Sorts 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.

    jskos.sortConcepts(concepts)

    sortSchemes

    Sorts a list of schemes by their prefLabel (de or en), then notation, then URI. Returns a copy of the list.

    jskos.sortSchemes(schemes)

    minifyMapping

    Removes 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.

    let newMapping = jskos.minifyMapping(mapping)

    mappingTypes

    An array of mapping types in form of objects. Objects can have the following properties:

    • notation - an array of notations (in this case symbols)
    • uri - the URI of the mapping type
    • prefLabel - a language maps of labels
    • broader - array of broader mapping types for this type
    • related - array of related mapping types
    • RELEVANCE - relevance label for GND terms (low, medium, high, very high)
    • SHORT - a short name for the type, used for CSV import/export

    The labels are taken from Wikidata (see script bin/localize-mapping-types).

    Example object:

    {
      "notation": [""],
      "uri": "http://www.w3.org/2004/02/skos/core#closeMatch",
      "prefLabel": { "en": "close match" },
      "broader": [ { "uri": "http://www.w3.org/2004/02/skos/core#mappingRelation" } ],
      "RELEVANCE": "high",
      "SHORT": "close"
    }

    mappingTypeByUri

    Returns a mapping type object for an URI.

    jskos.mappingTypeByUri("http://www.w3.org/2004/02/skos/core#closeMatch")

    mappingTypeByType

    Returns 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.

    jskos.mappingTypeByType(mapping.type)

    defaultMappingType

    The default mapping type (currently mapping relation).

    flattenMapping

    Converts 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.

    mappingCSV

    Returns an object of preconfigured conversion functions to convert mappings into CSV. Supports 1-to-1, 1-to-n, and n-to-n mappings.

    // Initialize converter with default options
    const csv = jskos.mappingCSV({
      delimiter: ",",
      quoteChar: "\"",
      lineTerminator: "\n",
      type: true,
      schemes: false,
      labels: false,
      creator: false,
      language: "en",
    })
    // Header line for an array of mappings (assuming 1-to-1 mappings if no array is given)
    csv.header(mappings)
    // Single CSV line for a mapping (uses fromCount and toCount from the mapping by default)
    csv.fromMapping(mapping, { fromCount: null, toCount: null })
    // Multiline CSV from array of mappings (includes header by default)
    csv.fromMappings(mappings, { header: true })

    The order of the CSV fields is fromScheme, fromNotation, (fromLabel,) (fromNotation2, fromLabel2, ...) toNotation, (toLabel,) (toNotation2, toLabel2, ...) type, creator.

    serializeCSV

    Returns a function to serialize an array as CSV row as configured with CSV Dialect.

    conceptsOfMapping

    Returns 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.

    jskos.conceptsOfMapping(mapping)

    compareMappingsDeep

    compareMappingsDeep compares two mappings based on their properties. Concept sets and schemes are compared by URI.

    if (jskos.compareMappingsDeep(mapping1, mapping2)) { ... }

    matchObjectTypes

    Compares two JSKOS objects based on their types. Returns false only if both types could be guessed using guessObjectType and they did not match, otherwise it will assume that the types match.

    mergeUris

    Merge URIs of two objects a and b into a by adding/removing URIs from identifier property.

    merge

    Merges two JSKOS objects. See documentation for more information.

    normalize

    Applies recursive unicode normalization to data.

    isValidUri

    Checks whether a string is a valid URI.

    objectTypes

    An object that maps JSKOS object type names to their description.

    guessObjectType

    Guess the JSKOS object type of an object, URI or name and return its canonical name.

    type = guessObjectType(objectOrString)        // get full name such as `ConceptScheme`
    type = guessObjectType(objectOrString, true)  // get short name such as `scheme`

    compareFunctions

    An object containing compare functions that can be used with array.sort() etc.

    Available functions:

    • compareFunctions.mappingsByConcepts - compares mappings by the notations of their first concepts

    userOwnsMapping

    Determines whether a (login-server-compatible) user owns a mapping (i.e. is the first creator) or not.

    notation

    Returns the primary notation for a JSKOS Item. If there is no notation, it will return an empty string. Scheme notations will be uppercased.

    languageMapContent

    Returns the content of a language map for a JSKOS Item.

    prefLabel

    Returns 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.

    definition

    Returns the definition of a JSKOS Item as an array. If there is no definition, an empty array will be returned.

    mappingRegistryIsStored

    Returns whether a mapping registry has stored mappings (true = database) or not (false = recommendations).

    annotationCreatorUri

    Returns the creator URI for an annotation.

    annotationCreatorName

    Returns the craetor name for an annotation.

    annotationCreatorMatches

    Matches an annotation's creator URI against a list of URIs (e.g. from a user).

    Build

    git clone --recursive https://github.com/gbv/jskos-tools.git
    cd jskos-tools/
    npm install

    API documentation can be generated in directory jsdoc/build:

    npm run docs

    Test

    npm test

    Maintainers

    Publish

    Please work on the dev branch during development (or better yet, develop in a feature branch and merge into dev when ready).

    When 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):

    npm run release:patch

    This will:

    • Run tests and build to make sure everything works
    • Switch to dev
    • Make sure dev is up-to-date
    • Run npm version patch (or "minor"/"major")
    • Push changes to dev
    • Switch to master
    • Merge changes from dev
    • Push master with tags
    • Switch back to dev

    After 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.

    Contribute

    PRs accepted.

    Small note: If editing the README, please conform to the standard-readme specification.

    License

    MIT © 2018 Verbundzentrale des GBV (VZG)

    Keywords

    none

    Install

    npm i jskos-tools

    DownloadsWeekly Downloads

    139

    Version

    1.0.26

    License

    MIT

    Unpacked Size

    144 kB

    Total Files

    15

    Last publish

    Collaborators

    • nichtich
    • stefandesu