{"id":32195095,"url":"https://github.com/fluree/json-ld","last_synced_at":"2026-02-21T12:01:40.539Z","repository":{"id":44160091,"uuid":"289076255","full_name":"fluree/json-ld","owner":"fluree","description":"Clojure JSON-LD library","archived":false,"fork":false,"pushed_at":"2025-08-14T18:24:06.000Z","size":843,"stargazers_count":21,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-12-25T15:25:38.318Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluree.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-20T18:09:50.000Z","updated_at":"2025-10-24T23:44:26.000Z","dependencies_parsed_at":"2025-07-03T04:23:07.559Z","dependency_job_id":"84baba7b-0b49-48be-87a1-2a1c619cd3c3","html_url":"https://github.com/fluree/json-ld","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fluree/json-ld","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluree%2Fjson-ld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluree%2Fjson-ld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluree%2Fjson-ld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluree%2Fjson-ld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluree","download_url":"https://codeload.github.com/fluree/json-ld/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluree%2Fjson-ld/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29680147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T11:29:27.227Z","status":"ssl_error","status_checked_at":"2026-02-21T11:29:20.292Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2025-10-22T02:02:16.182Z","updated_at":"2026-02-21T12:01:40.533Z","avatar_url":"https://github.com/fluree.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fluree/json-ld\n\nA JSON-LD processing library for Clojure and ClojureScript that provides core JSON-LD operations including expansion, compaction, normalization, and RDF conversion.\n\n## Features\n\n- **JSON-LD Processing**: Expand, compact, flatten*, and normalize JSON-LD documents (*flatten has limited ClojureScript support)\n- **Cross-platform**: Works in both Clojure (JVM) and ClojureScript (JS) environments\n- **External Context Support**: Pre-loaded contexts for common vocabularies (Schema.org, W3C, Fluree, etc.)\n- **RDF Conversion**: Convert between JSON-LD and RDF formats (N-Quads)\n- **Context Parsing**: Parse and manipulate JSON-LD contexts\n\n## Installation\n\nAdd the following dependency to your `deps.edn`:\n\n```clojure\ncom.fluree/json-ld {:mvn/version \"0.1.0\"}\n```\n\n## API Overview\n\nThe library provides the `fluree.json-ld` namespace with JSON-LD operations including:\n\n- Context parsing and manipulation\n- IRI expansion and compaction\n- Document expansion\n- Data normalization\n- External context and vocabulary support\n\n## Basic Usage\n\n**Note:** Most operations in this library require a parsed context. Parsing contexts once and reusing them makes expansion and compaction operations more efficient, especially when processing multiple documents with the same context.\n\n**JSON-LD Standard Output:** The expansion operation produces valid JSON-LD output that conforms to the JSON-LD 1.1 specification, using standard JSON-LD keywords (`@id`, `@type`, `@graph`, `@list`, `@value`, etc.) in the resulting data structure.\n\n### Context Parsing\n\nParse and work with JSON-LD contexts:\n\n```clojure\n(require '[fluree.json-ld :as json-ld])\n\n;; Parse a simple context\n(def ctx (json-ld/parse-context \n  {\"@context\" {\"name\" \"http://schema.org/name\"\n               \"age\"  {\"@id\" \"http://schema.org/age\" \n                       \"@type\" \"http://www.w3.org/2001/XMLSchema#integer\"}}}))\n\n;; Parse with external contexts\n(def ctx (json-ld/parse-context\n  {\"@context\" [\"https://schema.org\" \n               {\"myapp\" \"https://myapp.com/ns#\"}]}))\n```\n\n### Expansion\n\nExpand JSON-LD to its full form:\n\n```clojure\n;; Expand a JSON-LD document\n(json-ld/expand\n  {\"@context\" {\"name\" \"http://schema.org/name\"}\n   \"@id\" \"http://example.org/person/1\"\n   \"name\" \"John Doe\"})\n;; =\u003e {\"@id\" \"http://example.org/person/1\"\n;;     \"http://schema.org/name\" [{\"@value\" \"John Doe\"}]}\n\n;; Nested structures are expanded recursively:\n(json-ld/expand\n  {\"@context\" {\"knows\" \"http://schema.org/knows\"}\n   \"@id\" \"http://example.org/person/1\"\n   \"knows\" {\"@id\" \"http://example.org/person/2\"\n            \"knows\" {\"@id\" \"http://example.org/person/3\"}}})\n;; =\u003e {\"@id\" \"http://example.org/person/1\"\n;;     \"http://schema.org/knows\" [{\"@id\" \"http://example.org/person/2\"\n;;                                 \"http://schema.org/knows\" [{\"@id\" \"http://example.org/person/3\"}]}]}\n\n;; JSON-LD lists are handled with @list containers:\n(json-ld/expand\n  {\"@context\" {\"nick\" {\"@id\" \"http://xmlns.com/foaf/0.1/nick\"\n                       \"@container\" \"@list\"}}\n   \"@id\" \"http://example.org/people#joebob\"\n   \"nick\" [\"joe\" \"bob\" \"jaybee\"]})\n;; =\u003e {\"@id\" \"http://example.org/people#joebob\"\n;;     \"http://xmlns.com/foaf/0.1/nick\" \n;;     [{\"@list\" [{\"@value\" \"joe\"}\n;;                {\"@value\" \"bob\"}\n;;                {\"@value\" \"jaybee\"}]}]}\n\n;; @graph returns standard JSON-LD graph structures:\n(json-ld/expand {\"@graph\" [{\"@id\" \"http://example.org/1\" \n                            \"@context\" {\"name\" \"http://schema.org/name\"}\n                            \"name\" \"John\"}]})\n;; =\u003e [{\"@id\" \"http://example.org/1\" \n;;      \"http://schema.org/name\" [{\"@value\" \"John\"}]}]\n\n;; Expand a single IRI\n(json-ld/expand-iri \"schema:name\" parsed-context)\n;; =\u003e \"http://schema.org/name\"\n```\n\n### Compaction\n\nCompact expanded JSON-LD using a context:\n\n```clojure\n;; Create a compacting function\n(def compact-fn (json-ld/compact-fn parsed-context))\n\n(compact-fn \"http://schema.org/name\")\n;; =\u003e \"schema:name\"\n\n;; Track which context terms were used\n(def used (atom #{}))\n(def compact-fn (json-ld/compact-fn parsed-context used))\n(compact-fn \"http://schema.org/name\")\n@used ;; =\u003e #{\"schema\"}\n```\n\n### Normalization\n\nNormalize JSON-LD for consistent comparison and hashing:\n\n```clojure\n(json-ld/normalize-data\n  {\"@context\" {\"name\" \"http://schema.org/name\"}\n   \"name\" \"John Doe\"\n   \"@id\" \"http://example.org/person/1\"})\n;; =\u003e Returns normalized JSON string\n```\n\n#### Details Function\n\nGet expanded IRI with context settings:\n\n```clojure\n;; Get expansion details including context settings\n(json-ld/details \"schema:name\" parsed-context)\n;; =\u003e [\"http://schema.org/name\" {:id \"schema:name\", ...}]\n\n;; Control vocabulary expansion\n(json-ld/details \"myapp:userId\" parsed-context false)\n;; =\u003e Expands as @id rather than vocabulary term\n```\n\n#### JSON-LD Detection\n\n```clojure\n;; Check if a document appears to be JSON-LD\n(json-ld/json-ld? {\"@context\" {...} \"@id\" \"...\"}) \n;; =\u003e true\n\n(json-ld/json-ld? {\"name\" \"John\"}) \n;; =\u003e false\n```\n\n#### External IRI and Vocabulary Functions\n\n```clojure\n;; Load external IRIs with additional vocabulary information\n(json-ld/external-iri \"http://schema.org/Person\")\n;; =\u003e Returns IRI information\n\n(json-ld/external-vocab \"http://schema.org/name\") \n;; =\u003e Returns vocabulary details including rdfs:subClassOf relationships\n```\n\n## ClojureScript Support\n\nThe library works identically in ClojureScript:\n\n```clojure\n(ns my-app.core\n  (:require [fluree.json-ld :as json-ld]))\n\n;; All the same functions work in ClojureScript\n(def ctx (json-ld/parse-context {\"@context\" {...}}))\n(def expanded (json-ld/expand my-json-ld-doc ctx))\n(def compacted-iri (json-ld/compact \"http://schema.org/name\" ctx))\n```\n\n## JavaScript/ESM Support\n\nThe library provides a JavaScript-friendly ESM (ES Module) API that works in both Node.js and browser environments. The JavaScript API automatically handles data conversion between JavaScript objects and ClojureScript data structures.\n\n### Installation (JavaScript/NPM)\n\n```bash\nnpm install @fluree/json-ld\n```\n\n### JavaScript API Usage\n\n```javascript\n// Node.js\nimport { expand, compact, normalizeData, parseContext, jsonLd } from '@fluree/json-ld';\n\n// Browser\nimport { expand, compact, normalizeData, parseContext, jsonLd } from './dist/browser/fluree-json-ld.js';\n\n// Works with plain JavaScript objects\nconst doc = {\n  \"@context\": { \"name\": \"http://schema.org/name\" },\n  \"@type\": \"Person\",\n  \"name\": \"John Doe\"\n};\n\n// JSON-LD detection\nconst isJsonLd = jsonLd(doc); // true\n\n// Parse context (returns internal format for other functions)\nconst context = parseContext(doc[\"@context\"]);\n\n// Expand document\nconst expanded = expand(doc);\n\n// Normalize for hashing/comparison\nconst normalized = normalizeData(doc); // Returns string\n\n// Full workflow\nconst parsedContext = parseContext({ \"name\": \"http://schema.org/name\" });\nconst expandedDoc = expand(doc);\nconst compactedIri = compact(expandedDoc, parsedContext);\n```\n\n### JavaScript API Functions\n\n- `expand(document, [context])` - Expands JSON-LD documents\n- `compact(iri, context)` - Compacts expanded IRIs \n- `normalizeData(document, [options])` - Normalizes for hashing/comparison\n- `parseContext(context, [baseContext], [externals])` - Parses JSON-LD contexts\n- `expandIri(compactIri, context, [vocab])` - Expands compact IRIs\n- `compactFn(context, [usedAtom])` - Returns compaction function\n- `jsonLd(document)` - Detects if document is JSON-LD\n\n### Building JavaScript Modules\n\n```bash\n$ make js-package     # Build both Node.js and browser ESM modules\n$ make node          # Build Node.js ESM module only  \n$ make browser       # Build browser ESM module only\n```\n\n## Pre-loaded External Contexts\n\nThe library includes pre-parsed contexts for common vocabularies:\n\n- Schema.org: `https://schema.org`\n- W3C Credentials: `https://www.w3.org/2018/credentials/v1`\n- W3C DID: `https://www.w3.org/ns/did/v1`\n- W3C SHACL: `http://www.w3.org/ns/shacl`\n- Fluree Ledger: `https://ns.flur.ee/ledger#`\n- And more...\n\nAccess them directly:\n\n```clojure\n;; Load a pre-fetched external context\n(json-ld/external-context \"https://schema.org\")\n\n;; Load vocabulary information for an IRI\n(json-ld/external-vocab \"http://schema.org/Person\")\n```\n\n## Development\n\n### Prerequisites\n\nClojureScript tests require Node.js and npm. The Makefile will automatically install npm dependencies when running tests.\n\n### Testing\n\nRun the project's tests:\n\n```bash\n$ make test                # Run all tests (Clojure + JavaScript ESM)\n$ make cljtest             # Run Clojure tests only\n$ make cljstest            # Run ClojureScript tests only (auto-installs npm deps)\n$ make esm-test            # Run JavaScript ESM tests only\n$ make esm-test-node       # Run Node.js ESM tests only\n$ make esm-test-conversion # Run JS\u003c-\u003eCLJ data conversion tests\n$ make test-ci             # Run all tests for CI/CD\n$ make test-ci-workflow    # Test complete CI workflow locally\n```\n\n#### JavaScript ESM Testing\n\nThe JavaScript tests verify:\n- ESM module loading in Node.js and browsers\n- All API functions work with JavaScript objects\n- Automatic data conversion between JavaScript and ClojureScript\n- Complex nested data structures and edge cases\n\n### Code Quality\n\nLint and format code:\n\n```bash\n$ make lint        # Run clj-kondo linter\n$ make lint-ci     # Run stricter CI linting  \n$ make fmt         # Auto-format code\n$ make fmt-check   # Check formatting without changing files\n```\n\n### Building\n\nBuild a deployable jar:\n\n```bash\n$ make jar\n```\n\nBuild JavaScript ESM modules:\n\n```bash\n$ make js-package        # Build both Node.js and browser modules\n$ make all              # Build both JAR and JavaScript modules\n```\n\nInstall locally:\n\n```bash\n$ make install\n```\n\nDeploy to Clojars (requires `CLOJARS_USERNAME` and `CLOJARS_PASSWORD` environment variables):\n\n```bash\n$ make deploy\n```\n\n### CI/CD Integration\n\nThe project includes comprehensive CI/CD testing via GitHub Actions:\n\n- **Clojure Tests**: Unit tests for core functionality\n- **JavaScript ESM Tests**: Functionality and data conversion tests for both Node.js and browser environments\n- **Code Quality**: Linting with clj-kondo and code formatting checks\n- **Cross-platform**: Tests run on Ubuntu with Java 17 and Node.js 18\n\n**Local CI Testing:**\n```bash\n$ ./test-ci-workflow.sh  # Simulate complete CI pipeline locally\n```\n\nThe CI workflow automatically:\n1. Installs dependencies (npm, Maven)\n2. Builds JAR and JavaScript ESM modules\n3. Runs all test suites\n4. Validates code quality and formatting\n\n### Development Tools\n\nRe-parse all external contexts:\n\n```bash\n$ make parse-all-contexts\n```\n\n\n## License\n\nCopyright © 2021-2025 Fluree PBC\n\nDistributed under the Eclipse Public License either version 1.0 or (at your option) any later version.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluree%2Fjson-ld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluree%2Fjson-ld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluree%2Fjson-ld/lists"}