@twin.org/data-json-ld 0.0.3-next.2 → 0.0.3-next.20

package/docs/changelog.md

@@ -1,4 +1,276 @@
-# @twin.org/data-json-ld - Changelog
+# Changelog
+
+## [0.0.3-next.20](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.19...data-json-ld-v0.0.3-next.20) (2026-03-24)
+
+
+### Features
+
+* discover JSON-LD context via HTTP Link ([#62](https://github.com/twinfoundation/data/issues/62)) ([5545864](https://github.com/twinfoundation/data/commit/5545864c08e8c42fb93844f552907648a1130b64))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.19 to 0.0.3-next.20
+
+## [0.0.3-next.20](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.19...data-json-ld-v0.0.3-next.20) (2026-03-23)
+
+
+### Features
+
+* **JsonLdProcessor:** discover JSON-LD context URLs via HTTP `Link` (`rel="alternate"`, `type="application/ld+json"`) after `GET` Accept fallbacks fail to return JSON; `HEAD` with `GET` fallback on 405/501; at most one discovery hop; resolve `Link` targets with a safe base when `response.url` is empty (e.g. synthetic responses). Registered redirects still take precedence over discovery.
+
+
+### Documentation
+
+* Document remote context resolution order (`docs/examples.md`).
+* Document when vocabulary `registerRedirects()` helpers are optional versus HTTP `Link` discovery (`docs/examples.md`).
+* Expand `JsonLdProcessor` redirect JSDoc (`setRedirects` / `addRedirect`).
+
+
+### Tests
+
+* Share schema.org fixture document-cache seeding via `tests/helpers/schemaOrgDocumentCache.ts` (`jsonLdProcessor` / `jsonLdHelper` specs).
+
+
+## [0.0.3-next.19](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.18...data-json-ld-v0.0.3-next.19) (2026-03-20)
+
+
+### Features
+
+* use local LD context fixture in tests instead of remotes ([#60](https://github.com/twinfoundation/data/issues/60)) ([df18303](https://github.com/twinfoundation/data/commit/df18303301f031a5032850c900eea24b094a99a5))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.18 to 0.0.3-next.19
+
+## [0.0.3-next.18](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.17...data-json-ld-v0.0.3-next.18) (2026-03-16)
+
+
+### Miscellaneous Chores
+
+* **data-json-ld:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.17 to 0.0.3-next.18
+
+## [0.0.3-next.17](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.16...data-json-ld-v0.0.3-next.17) (2026-03-12)
+
+
+### Miscellaneous Chores
+
+* **data-json-ld:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.16 to 0.0.3-next.17
+
+## [0.0.3-next.16](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.15...data-json-ld-v0.0.3-next.16) (2026-03-06)
+
+
+### Features
+
+* additional JSON-LD helper types ([575627c](https://github.com/twinfoundation/data/commit/575627c707e691086e07163dac44ba1396ac322e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.15 to 0.0.3-next.16
+
+## [0.0.3-next.15](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.14...data-json-ld-v0.0.3-next.15) (2026-02-27)
+
+
+### Features
+
+* additional json-ld helpers ([c74cbd6](https://github.com/twinfoundation/data/commit/c74cbd60e423c5f780243da9868723e9d54d068a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.14 to 0.0.3-next.15
+
+## [0.0.3-next.14](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.13...data-json-ld-v0.0.3-next.14) (2026-02-25)
+
+
+### Features
+
+* update schemas ([c30159c](https://github.com/twinfoundation/data/commit/c30159cd24e5f60f9124752738dd1c0312ee17dd))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.13 to 0.0.3-next.14
+
+## [0.0.3-next.13](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.12...data-json-ld-v0.0.3-next.13) (2026-02-25)
+
+
+### Features
+
+* publish npm await ([7bdf0cd](https://github.com/twinfoundation/data/commit/7bdf0cd5d9417e7f8811f295ccf3ab3403ae3753))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.12 to 0.0.3-next.13
+
+## [0.0.3-next.12](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.11...data-json-ld-v0.0.3-next.12) (2026-02-25)
+
+
+### Features
+
+* add toStructuredObject ([58354e0](https://github.com/twinfoundation/data/commit/58354e0096c917f2e2e64214107d68326c79260d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.11 to 0.0.3-next.12
+
+## [0.0.3-next.11](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.10...data-json-ld-v0.0.3-next.11) (2026-02-25)
+
+
+### Features
+
+* expand JsonLdHelper.getId with custom properties names ([8ec4dcf](https://github.com/twinfoundation/data/commit/8ec4dcf807a6dc416b2df2a77749f841a60be05f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.10 to 0.0.3-next.11
+
+## [0.0.3-next.10](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.9...data-json-ld-v0.0.3-next.10) (2026-02-24)
+
+
+### Features
+
+* add json ld helper types ([#46](https://github.com/twinfoundation/data/issues/46)) ([22e998e](https://github.com/twinfoundation/data/commit/22e998e29e7eadc9202026ee9743d64ed98035df))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.9 to 0.0.3-next.10
+
+## [0.0.3-next.9](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.8...data-json-ld-v0.0.3-next.9) (2026-02-23)
+
+
+### Features
+
+* additional JsonLdHelper methods ([#44](https://github.com/twinfoundation/data/issues/44)) ([ebe2cf5](https://github.com/twinfoundation/data/commit/ebe2cf50d1a7fbe0474f0a556d49f43eb7767a2f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.8 to 0.0.3-next.9
+
+## [0.0.3-next.8](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.7...data-json-ld-v0.0.3-next.8) (2026-02-02)
+
+
+### Miscellaneous Chores
+
+* **data-json-ld:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.7 to 0.0.3-next.8
+
+## [0.0.3-next.7](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.6...data-json-ld-v0.0.3-next.7) (2026-01-21)
+
+
+### Features
+
+* update context naming ([#37](https://github.com/twinfoundation/data/issues/37)) ([9d99360](https://github.com/twinfoundation/data/commit/9d993605aa51f27a09722729057c6ee921617c2d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.6 to 0.0.3-next.7
+
+## [0.0.3-next.6](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.5...data-json-ld-v0.0.3-next.6) (2026-01-14)
+
+
+### Miscellaneous Chores
+
+* **data-json-ld:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.5 to 0.0.3-next.6
+
+## [0.0.3-next.5](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.4...data-json-ld-v0.0.3-next.5) (2026-01-14)
+
+
+### Features
+
+* improve data type registration ([#34](https://github.com/twinfoundation/data/issues/34)) ([855d110](https://github.com/twinfoundation/data/commit/855d11046a4d85317b77a5c4e0f4a7b1b6d1a767))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.4 to 0.0.3-next.5
+
+## [0.0.3-next.4](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.3...data-json-ld-v0.0.3-next.4) (2026-01-06)
+
+
+### Miscellaneous Chores
+
+* **data-json-ld:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.3 to 0.0.3-next.4
+
+## [0.0.3-next.3](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.2...data-json-ld-v0.0.3-next.3) (2026-01-05)
+
+
+### Features
+
+* add JsonLdHelper.toNodeObject method ([93f2add](https://github.com/twinfoundation/data/commit/93f2add1948f168d7a21223929cf6c65a8115f6f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/data-core bumped from 0.0.3-next.2 to 0.0.3-next.3
 
 ## [0.0.3-next.2](https://github.com/twinfoundation/data/compare/data-json-ld-v0.0.3-next.1...data-json-ld-v0.0.3-next.2) (2025-11-24)
 

package/docs/examples.md

@@ -1 +1,214 @@
-# @twin.org/data-json-ld - Examples
+# Data Json Ld Examples
+
+These examples walk through context management, document processing, validation, and property access patterns for JSON-LD documents.
+
+## JsonLdProcessor
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+JsonLdProcessor.setCacheLimit(900000);
+console.log('Cache limit:', JsonLdProcessor.getCacheLimit());
+
+JsonLdProcessor.setRedirects([
+  {
+    from: /^https:\/\/raw\.githubusercontent\.com\//,
+    to: 'https://cdn.example.org/github-content'
+  }
+]);
+
+JsonLdProcessor.addRedirect(/^https:\/\/schema\.org\//, 'https://schema.org/');
+console.log('Has redirects:', JsonLdProcessor.getRedirects().length > 0);
+
+const loader = JsonLdProcessor.getDocumentLoader();
+console.log('Loader type:', typeof loader);
+```
+
+```typescript
+import { JsonLdProcessor, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const compactedDoc = {
+  '@context': {
+    ex: 'https://example.org/vocab/',
+    name: 'ex:name'
+  },
+  '@id': 'urn:example:person:1',
+  name: 'Ada'
+};
+
+const expanded = await JsonLdProcessor.expand(compactedDoc);
+const compactedAgain = await JsonLdProcessor.compact(expanded[0], compactedDoc['@context']);
+
+console.log('Compacted id:', compactedAgain['@id']);
+
+const canonical = await JsonLdProcessor.canonize(expanded[0] as IJsonLdNodeObject);
+console.log('Canonical includes id:', canonical.includes('urn:example:person:1'));
+```
+
+```typescript
+import { JsonLdProcessor, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const contextA = 'https://example.org/context/base';
+const contextB = {
+  ex: 'https://example.org/vocab/',
+  name: 'ex:name'
+};
+
+const combined = JsonLdProcessor.combineContexts(contextA, contextB);
+
+const documentWithNestedContexts: IJsonLdNodeObject = {
+  '@context': contextA,
+  '@graph': [
+    {
+      '@context': contextB,
+      '@id': 'urn:example:item:1',
+      '@type': 'ex:Person',
+      'ex:name': 'Ada'
+    }
+  ]
+};
+
+const gathered = JsonLdProcessor.gatherContexts(documentWithNestedContexts);
+const filtered = JsonLdProcessor.removeContexts(gathered, [contextB]);
+
+console.log('Combined is array:', Array.isArray(combined));
+console.log('Filtered context equals contextA:', filtered === contextA);
+```
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+await JsonLdProcessor.documentCacheAdd('https://example.org/context', {
+  '@context': {
+    ex: 'https://example.org/vocab/'
+  }
+});
+
+await JsonLdProcessor.documentCacheRemove('https://example.org/context');
+```
+
+### Remote `@context` URLs: redirects and HTTP `Link` discovery
+
+When a remote `@context` URL is a string, the default document loader resolves it in this order:
+
+1. **Registered redirects** — `setRedirects` / `addRedirect` run first. If a pattern matches, the request uses the replacement URL only (no `HEAD` or discovery against the original namespace URL).
+2. **GET with `Accept: application/ld+json`**. If the response is an **HTTP error** (for example **404**), the load fails and discovery does not run. If the response is **OK** but the body is **not valid JSON** (for example HTML), retry **GET** with **`Accept: application/json`**.
+3. **HTTP `Link` discovery** — only if **both** `GET`s in step 2 failed with a **JSON decode** error: `HEAD` on the current URL (or `GET` if the server returns **405** / **501** for `HEAD`), then inspect `Link` for `rel="alternate"` and `type="application/ld+json"`, resolve the target URL, and **fetch that context document once** (at most **one** discovery hop per load chain).
+
+Use **manual redirects** for stable overrides, offline tests, or hosts that do not expose a suitable `Link` header. Rely on **discovery** when the namespace URL serves HTML but advertises a JSON-LD context via `Link`.
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+// Optional: force a namespace URL to a known context document (runs before discovery).
+JsonLdProcessor.addRedirect(
+  /^https:\/\/example\.org\/vocab\/?$/,
+  'https://example.org/context/doc.jsonld'
+);
+```
+
+### Standards packages and `registerRedirects()`
+
+Vocabulary packages (for example `@twin.org/standards-schema-org`) often expose `SchemaOrgDataTypes.registerRedirects()`, which forwards to `JsonLdProcessor.addRedirect` for a known namespace URL. That call is **optional** in many deployments: the default loader can reach the same JSON-LD context via **HTTP `Link` discovery** when the namespace URL returns HTML and advertises `rel="alternate"` with `type="application/ld+json"`. Prefer **explicit redirects** when you want predictable URLs without an extra `HEAD`/`GET` for discovery, **fully offline** or hermetic tests, or when the host does not send a usable `Link` header.
+
+## JsonLdHelper
+
+```typescript
+import { type IValidationFailure } from '@twin.org/core';
+import { ValidationMode } from '@twin.org/data-core';
+import { JsonLdHelper, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const compactedDocument = {
+  '@context': {
+    ex: 'https://example.org/vocab/',
+    id: '@id',
+    type: '@type',
+    name: 'ex:name'
+  },
+  id: 'urn:example:person:1',
+  type: 'ex:Person',
+  name: 'Ada'
+};
+
+const failures: IValidationFailure[] = [];
+await JsonLdHelper.validate(compactedDocument, failures, {
+  validationMode: ValidationMode.Either,
+  failOnMissingType: false
+});
+
+const expanded = await JsonLdHelper.expand(compactedDocument);
+const hasPersonType = await JsonLdHelper.isType(expanded, ['https://example.org/vocab/Person']);
+const types = await JsonLdHelper.getType(expanded);
+const id = await JsonLdHelper.getId(expanded);
+
+console.log('Failure count:', failures.length);
+console.log('Has person type:', hasPersonType);
+console.log('Type list includes person:', types.includes('https://example.org/vocab/Person'));
+console.log('Document id:', id);
+
+const nodeObject = JsonLdHelper.toNodeObject(compactedDocument);
+const structuredObject = JsonLdHelper.toStructuredObject<{ name: string }>(
+  nodeObject as IJsonLdNodeObject
+);
+
+console.log('Structured name:', structuredObject.name);
+```
+
+```typescript
+import { JsonLdHelper } from '@twin.org/data-json-ld';
+
+const expandedDocument = [
+  {
+    '@id': 'urn:example:article:1',
+    'https://schema.org/name': [
+      { '@value': 'Hello', '@language': 'en' },
+      { '@value': 'Hallo', '@language': 'de' }
+    ],
+    'https://schema.org/wordCount': [{ '@value': 240 }]
+  }
+];
+
+const title = await JsonLdHelper.getPropertyValue(
+  expandedDocument,
+  'https://schema.org/name',
+  'en'
+);
+const [nameValues, wordCountValues] = await JsonLdHelper.getPropertyValues(expandedDocument, [
+  'https://schema.org/name',
+  'https://schema.org/wordCount'
+]);
+
+console.log('English title:', title?.[0]);
+console.log('Name value count:', nameValues?.length);
+console.log('Word count value:', wordCountValues?.[0]);
+```
+
+```typescript
+import { JsonLdHelper } from '@twin.org/data-json-ld';
+
+const node = {
+  '@id': 'urn:example:item:1',
+  name: 'Ada',
+  role: 'Engineer'
+};
+
+const prefixed = JsonLdHelper.prefixProperties(node, 'ex', ['name', 'role']);
+const stripped = JsonLdHelper.stripPrefixProperties(prefixed, 'ex');
+
+console.log('Prefixed name:', prefixed['ex:name']);
+console.log('Stripped name:', stripped.name);
+```
+
+## JsonLdDataTypes
+
+```typescript
+import { DataTypeHelper } from '@twin.org/data-core';
+import { JsonLdContexts, JsonLdDataTypes, JsonLdTypes } from '@twin.org/data-json-ld';
+
+JsonLdDataTypes.registerTypes();
+
+const schema = await DataTypeHelper.getSchemaForType(
+  `${JsonLdContexts.Namespace}${JsonLdTypes.Document}`
+);
+console.log('Registered schema type:', schema?.type);
+```

package/docs/reference/classes/JsonLdDataTypes.md

@@ -14,7 +14,7 @@ Handle all the data types for JSON-LD.
 
 ## Methods
 
-### registerTypes()
+### registerTypes() {#registertypes}
 
 > `static` **registerTypes**(): `void`