@twin.org/data-json-ld 0.0.3-next.15 → 0.0.3-next.17

package/README.md

@@ -1,6 +1,6 @@
 # TWIN JSON LD Data
 
-Models which define the structure of [JSON LD](https://json-ld.org/).
+This package provides JSON-LD data models and helper utilities for working with linked data documents in a predictable and reusable way. It aligns package-level data structures with the [JSON-LD](https://json-ld.org/) ecosystem, making it easier to represent interoperable semantic data across services.
 
 ## Installation
 

package/dist/es/helpers/jsonLdHelperTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonLdHelperTypes.js","sourceRoot":"","sources":["../../../src/helpers/jsonLdHelperTypes.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IJsonLdContextDefinitionRoot } from \"../models/IJsonLdContextDefinitionRoot.js\";\n\n/**\n * Extract the optional property names from a type.\n */\nexport type JsonLdOptionalKeys<T> = {\n\t[K in keyof T]-?: {} extends Pick<T, K> ? K : never;\n}[keyof T];\n\n/**\n * Extract the required property names from a type.\n */\nexport type JsonLdRequiredKeys<T> = Exclude<keyof T, JsonLdOptionalKeys<T>>;\n\n/**\n * Keep JSON-LD keys as-is and prefix non-JSON-LD keys.\n */\nexport type JsonLdAliasKey<K extends string, Prefix extends string> = K extends `@${string}`\n\t? K\n\t: `${Prefix}:${K}`;\n\n/**\n * Remap an object type so JSON-LD keys (\"@...\") are preserved and\n * non-JSON-LD keys are exposed as `Prefix:key` aliases, while preserving\n * each key's original required/optional status.\n */\nexport type JsonLdWithAliases<T extends object, Prefix extends string> = {\n\t[K in Extract<JsonLdRequiredKeys<T>, string> as JsonLdAliasKey<K, Prefix>]: T[K];\n} & {\n\t[K in Extract<JsonLdOptionalKeys<T>, string> as JsonLdAliasKey<K, Prefix>]?: T[K];\n};\n\n/**\n * Keep only JSON-LD keys (\"@...\") from a type.\n */\nexport type JsonLdKeys<T extends object> = Pick<T, Extract<keyof T, `@${string}`>>;\n\n/**\n * Create a JSON-LD object shape containing only JSON-LD keys plus aliased\n * non-JSON-LD keys.\n */\nexport type JsonLdObjectWithAliases<T extends object, Prefix extends string> = JsonLdKeys<T> &\n\tJsonLdWithAliases<T, Prefix>;\n\n/**\n * Add \"@context\" to a type.\n */\nexport type JsonLdObjectWithContext<T extends object, C = IJsonLdContextDefinitionRoot> = Omit<\n\tT,\n\t\"@context\"\n> & {\n\t\"@context\": C;\n};\n\n/**\n * Infer an existing property's type from a source type, or fall back to a default.\n */\nexport type JsonLdExistingProperty<T extends object, P extends PropertyKey, D> = T extends {\n\t[K in P]?: infer PropertyType;\n}\n\t? Exclude<PropertyType, undefined>\n\t: D;\n\n/**\n * Add optional \"@context\" to a type, inferring an existing context type from\n * the source type when available, otherwise using the provided default.\n */\nexport type JsonLdObjectWithOptionalContext<\n\tT extends object,\n\tC = JsonLdExistingProperty<T, \"@context\", IJsonLdContextDefinitionRoot>\n> = Omit<T, \"@context\"> & {\n\t\"@context\"?: C;\n};\n\n/**\n * Omit optional \"@context\" from a type, inferring an existing context type from\n * the source type when available, otherwise using the provided default.\n */\nexport type JsonLdObjectWithNoContext<T extends object> = Omit<T, \"@context\">;\n\n/**\n * Add \"@type\" to a type.\n */\nexport type JsonLdObjectWithType<\n\tT extends object,\n\tTy = JsonLdExistingProperty<T, \"@type\", string | string[]>\n> = Omit<T, \"@type\"> & {\n\t\"@type\": Ty;\n};\n\n/**\n * Add optional \"@type\" to a type.\n */\nexport type JsonLdObjectWithOptionalType<\n\tT extends object,\n\tTy = JsonLdExistingProperty<T, \"@type\", string | string[]>\n> = Omit<T, \"@type\"> & {\n\t\"@type\"?: Ty;\n};\n\n/**\n * Omit \"@type\" from a type.\n */\nexport type JsonLdObjectWithNoType<T extends object> = Omit<T, \"@type\">;\n\n/**\n * Add \"@id\" to a type.\n */\nexport type JsonLdObjectWithId<\n\tT extends object,\n\tId = JsonLdExistingProperty<T, \"@id\", string>\n> = Omit<T, \"@id\"> & {\n\t\"@id\": Id;\n};\n\n/**\n * Add optional \"@id\" to a type.\n */\nexport type JsonLdObjectWithOptionalId<\n\tT extends object,\n\tId = JsonLdExistingProperty<T, \"@id\", string>\n> = Omit<T, \"@id\"> & {\n\t\"@id\"?: Id;\n};\n\n/**\n * Omit \"@id\" from a type.\n */\nexport type JsonLdObjectWithNoId<T extends object> = Omit<T, \"@id\">;\n"]}
+{"version":3,"file":"jsonLdHelperTypes.js","sourceRoot":"","sources":["../../../src/helpers/jsonLdHelperTypes.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IJsonLdContextDefinitionRoot } from \"../models/IJsonLdContextDefinitionRoot.js\";\n\n/**\n * Extract the optional property names from a type.\n */\nexport type JsonLdOptionalKeys<T> = {\n\t[K in keyof T]-?: {} extends Pick<T, K> ? K : never;\n}[keyof T];\n\n/**\n * Extract the required property names from a type.\n */\nexport type JsonLdRequiredKeys<T> = Exclude<keyof T, JsonLdOptionalKeys<T>>;\n\n/**\n * Keep JSON-LD keys as-is and prefix non-JSON-LD keys.\n */\nexport type JsonLdAliasKey<K extends string, Prefix extends string> = K extends `@${string}`\n\t? K\n\t: `${Prefix}:${K}`;\n\n/**\n * Remap an object type so JSON-LD keys (\"@...\") are preserved and\n * non-JSON-LD keys are exposed as `Prefix:key` aliases, while preserving\n * each key's original required/optional status.\n */\nexport type JsonLdWithAliases<T extends object, Prefix extends string> = {\n\t[K in Extract<JsonLdRequiredKeys<T>, string> as JsonLdAliasKey<K, Prefix>]: T[K];\n} & {\n\t[K in Extract<JsonLdOptionalKeys<T>, string> as JsonLdAliasKey<K, Prefix>]?: T[K];\n};\n\n/**\n * Keep only JSON-LD keys (\"@...\") from a type.\n */\nexport type JsonLdKeys<T extends object> = Pick<T, Extract<keyof T, `@${string}`>>;\n\n/**\n * Create a JSON-LD object shape containing only JSON-LD keys plus aliased\n * non-JSON-LD keys.\n */\nexport type JsonLdObjectWithAliases<T extends object, Prefix extends string> = JsonLdKeys<T> &\n\tJsonLdWithAliases<T, Prefix>;\n\n/**\n * Add \"@context\" to a type.\n */\nexport type JsonLdObjectWithContext<T extends object, C = IJsonLdContextDefinitionRoot> = Omit<\n\tT,\n\t\"@context\"\n> & {\n\t\"@context\": C;\n};\n\n/**\n * Infer an existing property's type from a source type, or fall back to a default.\n */\nexport type JsonLdExistingProperty<T extends object, P extends PropertyKey, D> = T extends {\n\t[K in P]?: infer PropertyType;\n}\n\t? Exclude<PropertyType, undefined>\n\t: D;\n\n/**\n * Infer an existing property's type from either of two source properties,\n * or fall back to a default when neither exists.\n */\nexport type JsonLdExistingPropertyEither<\n\tT extends object,\n\tP1 extends PropertyKey,\n\tP2 extends PropertyKey,\n\tD\n> = [JsonLdExistingProperty<T, P1, never> | JsonLdExistingProperty<T, P2, never>] extends [never]\n\t? D\n\t: JsonLdExistingProperty<T, P1, never> | JsonLdExistingProperty<T, P2, never>;\n\n/**\n * Add optional \"@context\" to a type, inferring an existing context type from\n * the source type when available, otherwise using the provided default.\n */\nexport type JsonLdObjectWithOptionalContext<\n\tT extends object,\n\tC = JsonLdExistingProperty<T, \"@context\", IJsonLdContextDefinitionRoot>\n> = Omit<T, \"@context\"> & {\n\t\"@context\"?: C;\n};\n\n/**\n * Omit optional \"@context\" from a type, inferring an existing context type from\n * the source type when available, otherwise using the provided default.\n */\nexport type JsonLdObjectWithNoContext<T extends object> = Omit<T, \"@context\">;\n\n/**\n * Add \"type\" to a type.\n */\nexport type JsonLdObjectWithType<\n\tT extends object,\n\tTy = JsonLdExistingPropertyEither<T, \"type\", \"@type\", string | string[]>\n> = Omit<T, \"type\" | \"@type\"> & {\n\ttype: Ty;\n};\n\n/**\n * Add optional \"type\" to a type.\n */\nexport type JsonLdObjectWithOptionalType<\n\tT extends object,\n\tTy = JsonLdExistingPropertyEither<T, \"type\", \"@type\", string | string[]>\n> = Omit<T, \"type\" | \"@type\"> & {\n\ttype?: Ty;\n};\n\n/**\n * Omit \"type\" from a type.\n */\nexport type JsonLdObjectWithNoType<T extends object> = Omit<T, \"type\">;\n\n/**\n * Add \"@type\" to a type.\n */\nexport type JsonLdObjectWithAtType<\n\tT extends object,\n\tTy = JsonLdExistingPropertyEither<T, \"@type\", \"type\", string | string[]>\n> = Omit<T, \"@type\" | \"type\"> & {\n\t\"@type\": Ty;\n};\n\n/**\n * Add optional \"@type\" to a type.\n */\nexport type JsonLdObjectWithOptionalAtType<\n\tT extends object,\n\tTy = JsonLdExistingPropertyEither<T, \"@type\", \"type\", string | string[]>\n> = Omit<T, \"@type\" | \"type\"> & {\n\t\"@type\"?: Ty;\n};\n\n/**\n * Omit \"@type\" from a type.\n */\nexport type JsonLdObjectWithNoAtType<T extends object> = Omit<T, \"@type\">;\n\n/**\n * Add \"id\" to a type.\n */\nexport type JsonLdObjectWithId<\n\tT extends object,\n\tId = JsonLdExistingPropertyEither<T, \"id\", \"@id\", string>\n> = Omit<T, \"id\" | \"@id\"> & {\n\tid: Id;\n};\n\n/**\n * Add optional \"id\" to a type.\n */\nexport type JsonLdObjectWithOptionalId<\n\tT extends object,\n\tId = JsonLdExistingPropertyEither<T, \"id\", \"@id\", string>\n> = Omit<T, \"id\" | \"@id\"> & {\n\tid?: Id;\n};\n\n/**\n * Omit \"id\" from a type.\n */\nexport type JsonLdObjectWithNoId<T extends object> = Omit<T, \"id\">;\n\n/**\n * Add \"@id\" to a type.\n */\nexport type JsonLdObjectWithAtId<\n\tT extends object,\n\tId = JsonLdExistingPropertyEither<T, \"@id\", \"id\", string>\n> = Omit<T, \"@id\" | \"id\"> & {\n\t\"@id\": Id;\n};\n\n/**\n * Add optional \"@id\" to a type.\n */\nexport type JsonLdObjectWithOptionalAtId<\n\tT extends object,\n\tId = JsonLdExistingPropertyEither<T, \"@id\", \"id\", string>\n> = Omit<T, \"@id\" | \"id\"> & {\n\t\"@id\"?: Id;\n};\n\n/**\n * Omit \"@id\" from a type.\n */\nexport type JsonLdObjectWithNoAtId<T extends object> = Omit<T, \"@id\">;\n"]}

package/dist/types/helpers/jsonLdHelperTypes.d.ts

@@ -44,6 +44,11 @@ export type JsonLdObjectWithContext<T extends object, C = IJsonLdContextDefiniti
 export type JsonLdExistingProperty<T extends object, P extends PropertyKey, D> = T extends {
     [K in P]?: infer PropertyType;
 } ? Exclude<PropertyType, undefined> : D;
+/**
+ * Infer an existing property's type from either of two source properties,
+ * or fall back to a default when neither exists.
+ */
+export type JsonLdExistingPropertyEither<T extends object, P1 extends PropertyKey, P2 extends PropertyKey, D> = [JsonLdExistingProperty<T, P1, never> | JsonLdExistingProperty<T, P2, never>] extends [never] ? D : JsonLdExistingProperty<T, P1, never> | JsonLdExistingProperty<T, P2, never>;
 /**
  * Add optional "@context" to a type, inferring an existing context type from
  * the source type when available, otherwise using the provided default.
@@ -56,35 +61,67 @@ export type JsonLdObjectWithOptionalContext<T extends object, C = JsonLdExisting
  * the source type when available, otherwise using the provided default.
  */
 export type JsonLdObjectWithNoContext<T extends object> = Omit<T, "@context">;
+/**
+ * Add "type" to a type.
+ */
+export type JsonLdObjectWithType<T extends object, Ty = JsonLdExistingPropertyEither<T, "type", "@type", string | string[]>> = Omit<T, "type" | "@type"> & {
+    type: Ty;
+};
+/**
+ * Add optional "type" to a type.
+ */
+export type JsonLdObjectWithOptionalType<T extends object, Ty = JsonLdExistingPropertyEither<T, "type", "@type", string | string[]>> = Omit<T, "type" | "@type"> & {
+    type?: Ty;
+};
+/**
+ * Omit "type" from a type.
+ */
+export type JsonLdObjectWithNoType<T extends object> = Omit<T, "type">;
 /**
  * Add "@type" to a type.
  */
-export type JsonLdObjectWithType<T extends object, Ty = JsonLdExistingProperty<T, "@type", string | string[]>> = Omit<T, "@type"> & {
+export type JsonLdObjectWithAtType<T extends object, Ty = JsonLdExistingPropertyEither<T, "@type", "type", string | string[]>> = Omit<T, "@type" | "type"> & {
     "@type": Ty;
 };
 /**
  * Add optional "@type" to a type.
  */
-export type JsonLdObjectWithOptionalType<T extends object, Ty = JsonLdExistingProperty<T, "@type", string | string[]>> = Omit<T, "@type"> & {
+export type JsonLdObjectWithOptionalAtType<T extends object, Ty = JsonLdExistingPropertyEither<T, "@type", "type", string | string[]>> = Omit<T, "@type" | "type"> & {
     "@type"?: Ty;
 };
 /**
  * Omit "@type" from a type.
  */
-export type JsonLdObjectWithNoType<T extends object> = Omit<T, "@type">;
+export type JsonLdObjectWithNoAtType<T extends object> = Omit<T, "@type">;
+/**
+ * Add "id" to a type.
+ */
+export type JsonLdObjectWithId<T extends object, Id = JsonLdExistingPropertyEither<T, "id", "@id", string>> = Omit<T, "id" | "@id"> & {
+    id: Id;
+};
+/**
+ * Add optional "id" to a type.
+ */
+export type JsonLdObjectWithOptionalId<T extends object, Id = JsonLdExistingPropertyEither<T, "id", "@id", string>> = Omit<T, "id" | "@id"> & {
+    id?: Id;
+};
+/**
+ * Omit "id" from a type.
+ */
+export type JsonLdObjectWithNoId<T extends object> = Omit<T, "id">;
 /**
  * Add "@id" to a type.
  */
-export type JsonLdObjectWithId<T extends object, Id = JsonLdExistingProperty<T, "@id", string>> = Omit<T, "@id"> & {
+export type JsonLdObjectWithAtId<T extends object, Id = JsonLdExistingPropertyEither<T, "@id", "id", string>> = Omit<T, "@id" | "id"> & {
     "@id": Id;
 };
 /**
  * Add optional "@id" to a type.
  */
-export type JsonLdObjectWithOptionalId<T extends object, Id = JsonLdExistingProperty<T, "@id", string>> = Omit<T, "@id"> & {
+export type JsonLdObjectWithOptionalAtId<T extends object, Id = JsonLdExistingPropertyEither<T, "@id", "id", string>> = Omit<T, "@id" | "id"> & {
     "@id"?: Id;
 };
 /**
  * Omit "@id" from a type.
  */
-export type JsonLdObjectWithNoId<T extends object> = Omit<T, "@id">;
+export type JsonLdObjectWithNoAtId<T extends object> = Omit<T, "@id">;

package/docs/changelog.md

@@ -1,4 +1,32 @@
-# @twin.org/data-json-ld - Changelog
+# Changelog
+
+## [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)
 

package/docs/examples.md

@@ -1 +1,190 @@
-# @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');
+```
+
+## 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/index.md

@@ -30,14 +30,21 @@
 - [JsonLdObjectWithAliases](type-aliases/JsonLdObjectWithAliases.md)
 - [JsonLdObjectWithContext](type-aliases/JsonLdObjectWithContext.md)
 - [JsonLdExistingProperty](type-aliases/JsonLdExistingProperty.md)
+- [JsonLdExistingPropertyEither](type-aliases/JsonLdExistingPropertyEither.md)
 - [JsonLdObjectWithOptionalContext](type-aliases/JsonLdObjectWithOptionalContext.md)
 - [JsonLdObjectWithNoContext](type-aliases/JsonLdObjectWithNoContext.md)
 - [JsonLdObjectWithType](type-aliases/JsonLdObjectWithType.md)
 - [JsonLdObjectWithOptionalType](type-aliases/JsonLdObjectWithOptionalType.md)
 - [JsonLdObjectWithNoType](type-aliases/JsonLdObjectWithNoType.md)
+- [JsonLdObjectWithAtType](type-aliases/JsonLdObjectWithAtType.md)
+- [JsonLdObjectWithOptionalAtType](type-aliases/JsonLdObjectWithOptionalAtType.md)
+- [JsonLdObjectWithNoAtType](type-aliases/JsonLdObjectWithNoAtType.md)
 - [JsonLdObjectWithId](type-aliases/JsonLdObjectWithId.md)
 - [JsonLdObjectWithOptionalId](type-aliases/JsonLdObjectWithOptionalId.md)
 - [JsonLdObjectWithNoId](type-aliases/JsonLdObjectWithNoId.md)
+- [JsonLdObjectWithAtId](type-aliases/JsonLdObjectWithAtId.md)
+- [JsonLdObjectWithOptionalAtId](type-aliases/JsonLdObjectWithOptionalAtId.md)
+- [JsonLdObjectWithNoAtId](type-aliases/JsonLdObjectWithNoAtId.md)
 - [IJsonLdContainerType](type-aliases/IJsonLdContainerType.md)
 - [IJsonLdContainerTypeArray](type-aliases/IJsonLdContainerTypeArray.md)
 - [IJsonLdContextDefinitionElement](type-aliases/IJsonLdContextDefinitionElement.md)

package/docs/reference/type-aliases/JsonLdExistingPropertyEither.md

@@ -0,0 +1,24 @@
+# Type Alias: JsonLdExistingPropertyEither\<T, P1, P2, D\>
+
+> **JsonLdExistingPropertyEither**\<`T`, `P1`, `P2`, `D`\> = \[[`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `P1`, `never`\> \| [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `P2`, `never`\>\] *extends* \[`never`\] ? `D` : [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `P1`, `never`\> \| [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `P2`, `never`\>
+
+Infer an existing property's type from either of two source properties,
+or fall back to a default when neither exists.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+### P1
+
+`P1` *extends* `PropertyKey`
+
+### P2
+
+`P2` *extends* `PropertyKey`
+
+### D
+
+`D`

package/docs/reference/type-aliases/JsonLdObjectWithAtId.md

@@ -0,0 +1,21 @@
+# Type Alias: JsonLdObjectWithAtId\<T, Id\>
+
+> **JsonLdObjectWithAtId**\<`T`, `Id`\> = `Omit`\<`T`, `"@id"` \| `"id"`\> & `object`
+
+Add "@id" to a type.
+
+## Type Declaration
+
+### @id
+
+> **@id**: `Id`
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+### Id
+
+`Id` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"@id"`, `"id"`, `string`\>

package/docs/reference/type-aliases/JsonLdObjectWithAtType.md

@@ -0,0 +1,21 @@
+# Type Alias: JsonLdObjectWithAtType\<T, Ty\>
+
+> **JsonLdObjectWithAtType**\<`T`, `Ty`\> = `Omit`\<`T`, `"@type"` \| `"type"`\> & `object`
+
+Add "@type" to a type.
+
+## Type Declaration
+
+### @type
+
+> **@type**: `Ty`
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+### Ty
+
+`Ty` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"@type"`, `"type"`, `string` \| `string`[]\>

package/docs/reference/type-aliases/JsonLdObjectWithId.md

@@ -1,14 +1,14 @@
 # Type Alias: JsonLdObjectWithId\<T, Id\>
 
-> **JsonLdObjectWithId**\<`T`, `Id`\> = `Omit`\<`T`, `"@id"`\> & `object`
+> **JsonLdObjectWithId**\<`T`, `Id`\> = `Omit`\<`T`, `"id"` \| `"@id"`\> & `object`
 
-Add "@id" to a type.
+Add "id" to a type.
 
 ## Type Declaration
 
-### @id
+### id
 
-> **@id**: `Id`
+> **id**: `Id`
 
 ## Type Parameters
 
@@ -18,4 +18,4 @@ Add "@id" to a type.
 
 ### Id
 
-`Id` = [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `"@id"`, `string`\>
+`Id` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"id"`, `"@id"`, `string`\>

package/docs/reference/type-aliases/JsonLdObjectWithNoAtId.md

@@ -0,0 +1,11 @@
+# Type Alias: JsonLdObjectWithNoAtId\<T\>
+
+> **JsonLdObjectWithNoAtId**\<`T`\> = `Omit`\<`T`, `"@id"`\>
+
+Omit "@id" from a type.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`

package/docs/reference/type-aliases/JsonLdObjectWithNoAtType.md

@@ -0,0 +1,11 @@
+# Type Alias: JsonLdObjectWithNoAtType\<T\>
+
+> **JsonLdObjectWithNoAtType**\<`T`\> = `Omit`\<`T`, `"@type"`\>
+
+Omit "@type" from a type.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`

package/docs/reference/type-aliases/JsonLdObjectWithNoId.md

@@ -1,8 +1,8 @@
 # Type Alias: JsonLdObjectWithNoId\<T\>
 
-> **JsonLdObjectWithNoId**\<`T`\> = `Omit`\<`T`, `"@id"`\>
+> **JsonLdObjectWithNoId**\<`T`\> = `Omit`\<`T`, `"id"`\>
 
-Omit "@id" from a type.
+Omit "id" from a type.
 
 ## Type Parameters
 

package/docs/reference/type-aliases/JsonLdObjectWithNoType.md

@@ -1,8 +1,8 @@
 # Type Alias: JsonLdObjectWithNoType\<T\>
 
-> **JsonLdObjectWithNoType**\<`T`\> = `Omit`\<`T`, `"@type"`\>
+> **JsonLdObjectWithNoType**\<`T`\> = `Omit`\<`T`, `"type"`\>
 
-Omit "@type" from a type.
+Omit "type" from a type.
 
 ## Type Parameters
 

package/docs/reference/type-aliases/JsonLdObjectWithOptionalAtId.md

@@ -0,0 +1,21 @@
+# Type Alias: JsonLdObjectWithOptionalAtId\<T, Id\>
+
+> **JsonLdObjectWithOptionalAtId**\<`T`, `Id`\> = `Omit`\<`T`, `"@id"` \| `"id"`\> & `object`
+
+Add optional "@id" to a type.
+
+## Type Declaration
+
+### @id?
+
+> `optional` **@id**: `Id`
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+### Id
+
+`Id` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"@id"`, `"id"`, `string`\>

package/docs/reference/type-aliases/JsonLdObjectWithOptionalAtType.md

@@ -0,0 +1,21 @@
+# Type Alias: JsonLdObjectWithOptionalAtType\<T, Ty\>
+
+> **JsonLdObjectWithOptionalAtType**\<`T`, `Ty`\> = `Omit`\<`T`, `"@type"` \| `"type"`\> & `object`
+
+Add optional "@type" to a type.
+
+## Type Declaration
+
+### @type?
+
+> `optional` **@type**: `Ty`
+
+## Type Parameters
+
+### T
+
+`T` *extends* `object`
+
+### Ty
+
+`Ty` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"@type"`, `"type"`, `string` \| `string`[]\>

package/docs/reference/type-aliases/JsonLdObjectWithOptionalId.md

@@ -1,14 +1,14 @@
 # Type Alias: JsonLdObjectWithOptionalId\<T, Id\>
 
-> **JsonLdObjectWithOptionalId**\<`T`, `Id`\> = `Omit`\<`T`, `"@id"`\> & `object`
+> **JsonLdObjectWithOptionalId**\<`T`, `Id`\> = `Omit`\<`T`, `"id"` \| `"@id"`\> & `object`
 
-Add optional "@id" to a type.
+Add optional "id" to a type.
 
 ## Type Declaration
 
-### @id?
+### id?
 
-> `optional` **@id**: `Id`
+> `optional` **id**: `Id`
 
 ## Type Parameters
 
@@ -18,4 +18,4 @@ Add optional "@id" to a type.
 
 ### Id
 
-`Id` = [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `"@id"`, `string`\>
+`Id` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"id"`, `"@id"`, `string`\>

package/docs/reference/type-aliases/JsonLdObjectWithOptionalType.md

@@ -1,14 +1,14 @@
 # Type Alias: JsonLdObjectWithOptionalType\<T, Ty\>
 
-> **JsonLdObjectWithOptionalType**\<`T`, `Ty`\> = `Omit`\<`T`, `"@type"`\> & `object`
+> **JsonLdObjectWithOptionalType**\<`T`, `Ty`\> = `Omit`\<`T`, `"type"` \| `"@type"`\> & `object`
 
-Add optional "@type" to a type.
+Add optional "type" to a type.
 
 ## Type Declaration
 
-### @type?
+### type?
 
-> `optional` **@type**: `Ty`
+> `optional` **type**: `Ty`
 
 ## Type Parameters
 
@@ -18,4 +18,4 @@ Add optional "@type" to a type.
 
 ### Ty
 
-`Ty` = [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `"@type"`, `string` \| `string`[]\>
+`Ty` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"type"`, `"@type"`, `string` \| `string`[]\>

package/docs/reference/type-aliases/JsonLdObjectWithType.md

@@ -1,14 +1,14 @@
 # Type Alias: JsonLdObjectWithType\<T, Ty\>
 
-> **JsonLdObjectWithType**\<`T`, `Ty`\> = `Omit`\<`T`, `"@type"`\> & `object`
+> **JsonLdObjectWithType**\<`T`, `Ty`\> = `Omit`\<`T`, `"type"` \| `"@type"`\> & `object`
 
-Add "@type" to a type.
+Add "type" to a type.
 
 ## Type Declaration
 
-### @type
+### type
 
-> **@type**: `Ty`
+> **type**: `Ty`
 
 ## Type Parameters
 
@@ -18,4 +18,4 @@ Add "@type" to a type.
 
 ### Ty
 
-`Ty` = [`JsonLdExistingProperty`](JsonLdExistingProperty.md)\<`T`, `"@type"`, `string` \| `string`[]\>
+`Ty` = [`JsonLdExistingPropertyEither`](JsonLdExistingPropertyEither.md)\<`T`, `"type"`, `"@type"`, `string` \| `string`[]\>

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/data-json-ld",
-	"version": "0.0.3-next.15",
-	"description": "Models which define the structure of JSON LD",
+	"version": "0.0.3-next.17",
+	"description": "JSON-LD data models and helpers for working with linked data documents.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/data.git",
@@ -15,12 +15,12 @@
 	},
 	"dependencies": {
 		"@twin.org/core": "next",
-		"@twin.org/data-core": "0.0.3-next.15",
+		"@twin.org/data-core": "0.0.3-next.17",
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next",
 		"@types/jsonld": "1.5.15",
-		"jsonld": "8.3.3"
+		"jsonld": "9.0.0"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",