{"id":23250625,"url":"https://github.com/inrupt/solid-common-vocab-js","last_synced_at":"2025-08-20T09:30:55.471Z","repository":{"id":37074496,"uuid":"193413607","full_name":"inrupt/solid-common-vocab-js","owner":"inrupt","description":"A library providing JavaScript objects to represent the individual terms (i.e. the classes and properties) defined in RDF vocabularies.","archived":false,"fork":false,"pushed_at":"2024-12-10T13:16:19.000Z","size":3432,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-12-14T02:29:35.441Z","etag":null,"topics":["javascript","ontology","rdf","terms","vocabulary"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inrupt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-24T01:27:10.000Z","updated_at":"2024-12-10T13:16:22.000Z","dependencies_parsed_at":"2024-01-04T14:30:21.689Z","dependency_job_id":"0afc7fc1-5f2c-478f-8f96-974557a94143","html_url":"https://github.com/inrupt/solid-common-vocab-js","commit_stats":{"total_commits":745,"total_committers":12,"mean_commits":"62.083333333333336","dds":0.4845637583892617,"last_synced_commit":"756bdb94b05a1817cb0e254b72a85690b2e33c83"},"previous_names":["inrupt/lit-term-js","inrupt/lit-vocab-term-js"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inrupt%2Fsolid-common-vocab-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inrupt%2Fsolid-common-vocab-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inrupt%2Fsolid-common-vocab-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inrupt%2Fsolid-common-vocab-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inrupt","download_url":"https://codeload.github.com/inrupt/solid-common-vocab-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230408186,"owners_count":18220975,"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":["javascript","ontology","rdf","terms","vocabulary"],"created_at":"2024-12-19T09:14:18.783Z","updated_at":"2024-12-19T09:14:19.324Z","avatar_url":"https://github.com/inrupt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Solid Common Vocab library for JavaScript\n\nA library providing JavaScript objects to represent the individual terms\n(i.e., the classes and properties) defined in RDF vocabularies, both existing\nvocabularies (like http://schema.org, FOAF, vCard, LDP, ActivityStreams, etc.),\nand your own custom RDF vocabularies.\n\nA major feature of this library is that it provides easy access to any\n`rdfs:label` and `rdfs:comment` values provided for these vocabulary terms, and\nprovides very easy-to-use support for multilingual values for these labels and\ncomments. We also support other term metadata (such as `rdfs:seeAlso` and\n`rdfs:isDefinedBy`), and also generic message strings (using\n[SKOS-XL](https://www.w3.org/TR/skos-reference/skos-xl.html)) that can be used\nfor error message strings, or labels, or tooltip text for user interfaces, etc.\n\n### Setup\n\nThe `demo` directory provides a working example that you can run with the\nfollowing commands (starting from the root of this project, which we need to\nbuild first):\n\n```\nnpm ci\nnpm run build\n\ncd demo\nnpm ci\nnode index.js\n```\n\nThe `solid-common-vocab` library is distributed as a GitHub `npm` package:\n`@inrupt/solid-common-vocab`.\nFor more information about GitHub npm packages, please visit\n[the dedicated documentation](https://help.github.com/en/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages).\n\n\n**Note:** This library is used extensively by the Artifact Generator project\nthat can automatically generate source-code (in multiple programming\nlanguages, including JavaScript and TypeScript) that can provide Vocab Term\ninstances for every term defined within any RDF vocabulary. Due to the ease of\nsimply pointing the Artifact Generator at any RDF vocabulary and having it\nautomatically generate all the Vocab Term instances for you, we don't expect\nmanual instantiation of Vocab Terms to be very common. However, this\ndocumentation describes the Vocab library without any dependency or requirement\nto use the Artifact Generator at all.\n\n\n## Advanced usage by demonstration\n\nFor more detailed examples that go beyond the common uses featured here, please\nsee the [demonstration test suite](./demo/demonstrateByUsage.test.js).\n\nThat test code can be run using the following (assuming the base project has\nbeen built first!):\n\n```\njest demonstrateByUsage.test.js\n```\n\n## RDF library support\n\nThe Vocab Term object from this library is intended to be a simple wrapper\naround the 'NamedNode' object conforming to the\n[RDF/JS interface](http://rdf.js.org/data-model-spec/).\n\nThis means that Vocab Term instances can be used natively with libraries that\nare RDF/JS-compliant, such as `rdf-ext`, `rdflib.js`, `rdf-data-factory`,\n`graphy`, etc. An instance of a `VocabTerm` may be built by passing an RDF/JS\n`DataFactory` implemented by any library, but it also includes its own very\nbasic `DataFactory` implementation, just for convenience if you don't wish to\ninclude an existing implementation.\n\n### Introductory example\n\nFor example, if we have the following simple RDF vocabulary defining a single\n`Person` term (in this case an RDF Class):\n\n```\nprefix rdfs: \u003chttp://www.w3.org/2000/01/rdf-schema#\u003e\nprefix ex:   \u003chttps://example.com#\u003e\n\nex:Person a rdfs:Class ;\n  rdfs:label \"My Person class\"@en ;\n  rdfs:comment \"Full description of my Person class...\"@en .\n```\n\nWe could represent this as a Vocab Term in JavaScript like so:\n\n```javascript\nconst {VocabTerm, buildStore} = require('@inrupt/solid-common-vocab')\n// Any other implementation of the RDF/JS interfaces would also be appropriate.\nconst rdf = require('rdfFactory-ext')\n\n// The third argument provides as a context - it will commonly store things like\n// the current language preference of the user, which can be used to lookup term\n// labels or comments in that language. It's always there for browsers, but in\n// NodeJS we expose a local implementation accessible through the method\n// `buildStore`, which returns either said local implementation or the browser\n// store depending on the environment.\n// The last parameter indicates whether we want a 'strict' behaviour or not\n// (see below for an explanation).  \nconst person = new VocabTerm('https://example.com#Person', rdf, buildStore(), true)\n  .addLabel('My Person class','en')\n  .addComment('Full description of my Person class...','en')\n```\n\nWe can use this Vocab Term in various ways:\n\n```javascript\n// To access the term's full IRI value:\nconst personIri = person.value\n\n// The label and the comment are available as RDF/JS RDFLiteral instances:\n// - get the RDFLiteral object (which contains not just the text value, but also\n// the language tag of that text (e.g. 'en' for English, or 'es' for Spanish).\n// Solid Common can potentially offer further meta-data - such as a description\n// of how the text was determined. For example if a user's current language\n// preference (as stored in localStorage) was 'French', but our original RDF\n// vocabulary didn't provide a French label (in which case the vocab term will\n// fallback to using an English label by default), then we can describe that\n// behaviour in another field saying: \"Current language is French, but only\n// German, Spanish and English labels are available: using English\", which can\n// be extremely useful in a User Interface tooltip, for instance):\nconst personLabel = person.label\nconst personComment = person.comment\n\n// Get the term's label or comment as a simple string value:\nconst personLabelAsString = person.label.value\nconst personCommentAsString = person.comment.value\n```\n\nTo use the included `DataFactory` implementation to build a VocabTerm, the\nprevious example would become:\n\n```javascript\nconst {buildBasicTerm, buildStore} = require('@inrupt/solid-common-vocab')\n\nconst person = buildBasicTerm('https://example.com#Person', buildStore(), true)\n  .addLabel('My Person class','en')\n  .addComment('Full description of my Person class...','en')\n```\n\n**Note**: The `solid-common-vocab` library is implemented in TypeScript, and\nembeds its types. The following code snippet demonstrates basic TypeScript\nusage:\n\n```typescript\nimport {buildBasicTerm, buildStore, VocabTerm} from '@inrupt/solid-common-vocab'\n\nconst person: VocabTerm = buildBasicTerm(\n  'https://example.com#Person',\n  buildStore(),\n  true\n).addLabel('My Person class','en')\n.addComment('Full description of my Person class...','en')\n```\n\n### Messages\n\nAn important feature of `solid-common-vocab` is support for parameterized\nmessages. This can be extremely useful when creating your own RDF vocabularies\nand including message strings (thereby providing those messages with globally\nunique IRI identifiers, and allowing for easy translations of those message\nstrings). For instance, to report errors to the user with contextual information\n(and in multiple languages):\n\n```javascript\nconst term = new VocabTerm(\"https://test.com/vocab#Unauthorized\", rdf, buildStore(), true)\n    .addMessage('Your account ({{0}}), does not have sufficient credentials for this operation', 'en')\n    .addMessage('Votre compte ({{0}}) ne dispose pas des informations d'identification suffisantes pour cette opération', 'fr')\n    \nterm.messageParams('Current Account').value // Evaluates to \"Your account (Current Account)...\"\n```\n\n### Multilingual support\n\nUnless we explicitly mandate a specific language, English will be used by\ndefault. Best practice for RDF vocabularies in general is to provide labels\n(short human-readable descriptions) and comments (longer, more detailed\ndescriptions), and to also provide these descriptions in multiple languages if\nappropriate and possible.\n\n(**Technical note**: the language tag defaults to an empty string in the case of\nfalling back to the local part of the term's IRI (see the next section about\n`strictness`)).\n\n```javascript\nconst storage = buildStore()\nconst person = new VocabTerm('https://example.com#Person', rdf, storage, true)\n  .addLabel('Person','en')\n  .addLabel('Personne', 'fr')\n  .addLabel('Persona', 'es')\n\n// Default to the English label (if there is one).\nvar personLabel = person.label\n\n// Request an explicit language for the label - but if there isn't one, we'll \n// fallback to the English one, if there is one).\npersonLabel = person.asLanguage('fr').label\n\n// Change the default language in our context (i.e. localStorage).\nstorage.setItem(VocabContext.CONTEXT_KEY_LOCALE, 'es')\n\npersonLabel = person.label // personLabel now contains the Spanish literal.\n```\n\n### Strictness\n\nThe last parameter to the Vocab Term constructor indicates if the behaviour of\nthe term should be strict or loose. In the case of 'loose' behaviour, in the\nabsence of any label, `term.label` will default to the local part of the term's\nIRI (i.e., the last segment of the full path component). With 'strict' behaviour\nit will return `undefined`. When the local part of the IRI is returned as a\nlabel, the language tag will be empty (i.e., \"\").\n\n```javascript\n// Here we specify 'loose' behaviour(i.e. 'false' parameter to constructor)...\nvar person = new VocabTerm('https://example.com#Person', rdf, buildStore(), false)\n\n// 'personLabel' will default to an RDF literal with the value \"Person\", and an\n// empty language tag (i.e. \"\").\nvar personLabel = person.labelLiteral \n \n// Now strict behaviour...\nperson = new VocabTerm('https://example.com#Person', rdf, buildStore(), true)\n// personLabel will default to 'undefined'.\npersonLabel = person.labelLiteral\n```\n\nThis behaviour (i.e. returning the local part of the IRI, or `undefined`) may be\noverridden to instead throw an error when no label is found by using the\n`.mandatory` accessor.\n\n```javascript\n// Here 'strictness' has no impact...\nconst person = new VocabTerm('https://example.com#Person', rdf, buildStore(), true)\n\n// An exception will be thrown here, because our term has no label.\nconst personLabel = person.mandatory.label \n```\n    ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finrupt%2Fsolid-common-vocab-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finrupt%2Fsolid-common-vocab-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finrupt%2Fsolid-common-vocab-js/lists"}