@kravc/schema 2.7.6 → 2.8.0-alpha.1

package/src/ld/__tests__/getLinkedDataContext.test.ts

@@ -0,0 +1,378 @@
+import getLinkedDataContext, { type PropertySchema } from '../getLinkedDataContext';
+
+describe('getLinkedDataContext(properties, vocabUri)', () => {
+  describe('basic functionality', () => {
+    it('should create context with @vocab, @version, and @protected', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).toHaveProperty('@vocab', 'https://example.com/vocab#');
+      expect(result).toHaveProperty('@version', 1.1);
+      expect(result).toHaveProperty('@protected', true);
+    });
+
+    it('should include properties in context with @id', () => {
+      const properties: Record<string, PropertySchema> = {
+        name: { type: 'string' },
+        active: { type: 'boolean' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.name).toEqual({ '@id': 'name' });
+      expect(result.active).toEqual({ '@id': 'active' });
+    });
+  });
+
+  describe('protected properties', () => {
+    it('should skip id property', () => {
+      const properties: Record<string, PropertySchema> = {
+        id: { type: 'string' },
+        name: { type: 'string' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).not.toHaveProperty('id');
+      expect(result.name).toEqual({ '@id': 'name' });
+    });
+
+    it('should skip type property', () => {
+      const properties: Record<string, PropertySchema> = {
+        type: { type: 'string' },
+        name: { type: 'string' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).not.toHaveProperty('type');
+      expect(result.name).toEqual({ '@id': 'name' });
+    });
+
+    it('should skip schema property', () => {
+      const properties: Record<string, PropertySchema> = {
+        schema: { type: 'string' },
+        name: { type: 'string' },
+      };
+      // Use schema.org vocab so the header doesn't add a 'schema' property
+      const vocabUri = 'https://schema.org/';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      // The input 'schema' property should be skipped (it's protected)
+      expect(result).not.toHaveProperty('schema');
+      expect(result.name).toEqual({ '@id': 'name' });
+    });
+
+    it('should skip properties starting with @', () => {
+      const properties: Record<string, PropertySchema> = {
+        '@context': { type: 'string' },
+        '@type': { type: 'string' },
+        '@id': { type: 'string' },
+        name: { type: 'string' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).not.toHaveProperty('@context');
+      expect(result).not.toHaveProperty('@type');
+      expect(result).not.toHaveProperty('@id');
+      expect(result.name).toEqual({ '@id': 'name' });
+    });
+
+    it('should skip all protected properties together', () => {
+      const properties: Record<string, PropertySchema> = {
+        id: { type: 'string' },
+        type: { type: 'string' },
+        schema: { type: 'string' },
+        '@custom': { type: 'string' },
+        name: { type: 'string' },
+      };
+      // Use schema.org vocab so the header doesn't add a 'schema' property
+      const vocabUri = 'https://schema.org/';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      // All protected properties from input should be skipped
+      expect(result).not.toHaveProperty('id');
+      expect(result).not.toHaveProperty('type');
+      expect(result).not.toHaveProperty('schema');
+      expect(result).not.toHaveProperty('@custom');
+      expect(result.name).toEqual({ '@id': 'name' });
+    });
+  });
+
+  describe('properties with $ref', () => {
+    it('should include property with $ref but without @type', () => {
+      const properties: Record<string, PropertySchema> = {
+        reference: { $ref: '#/definitions/SomeType' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.reference).toEqual({ '@id': 'reference' });
+      expect(result.reference).not.toHaveProperty('@type');
+    });
+
+    it('should not add @type even if property has type and format', () => {
+      const properties: Record<string, PropertySchema> = {
+        reference: {
+          $ref: '#/definitions/SomeType',
+          type: 'integer',
+          format: 'int32',
+        },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.reference).toEqual({ '@id': 'reference' });
+      expect(result.reference).not.toHaveProperty('@type');
+    });
+  });
+
+  describe('properties with linked data types', () => {
+    it('should add @type for integer type', () => {
+      const properties: Record<string, PropertySchema> = {
+        age: { type: 'integer' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.age).toEqual({
+        '@id': 'age',
+        '@type': 'schema:Integer',
+      });
+    });
+
+    it('should add @type for number type', () => {
+      const properties: Record<string, PropertySchema> = {
+        price: { type: 'number' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.price).toEqual({
+        '@id': 'price',
+        '@type': 'schema:Number',
+      });
+    });
+
+    it('should add @type for date format', () => {
+      const properties: Record<string, PropertySchema> = {
+        birthDate: { type: 'string', format: 'date' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.birthDate).toEqual({
+        '@id': 'birthDate',
+        '@type': 'schema:Date',
+      });
+    });
+
+    it('should add @type for date-time format', () => {
+      const properties: Record<string, PropertySchema> = {
+        createdAt: { type: 'string', format: 'date-time' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.createdAt).toEqual({
+        '@id': 'createdAt',
+        '@type': 'schema:DateTime',
+      });
+    });
+
+    it('should add @type when @type is explicitly defined', () => {
+      const properties: Record<string, PropertySchema> = {
+        custom: { '@type': 'schema:CustomType', type: 'string' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.custom).toEqual({
+        '@id': 'custom',
+        '@type': 'schema:CustomType',
+      });
+    });
+
+    it('should not add @type when getLinkedDataType returns undefined', () => {
+      const properties: Record<string, PropertySchema> = {
+        name: { type: 'string' },
+        active: { type: 'boolean' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result.name).toEqual({ '@id': 'name' });
+      expect(result.name).not.toHaveProperty('@type');
+      expect(result.active).toEqual({ '@id': 'active' });
+      expect(result.active).not.toHaveProperty('@type');
+    });
+  });
+
+  describe('vocab URI handling', () => {
+    it('should append # to vocab URI that does not end with / or #', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result['@vocab']).toBe('https://example.com/vocab#');
+    });
+
+    it('should not append # to vocab URI ending with /', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab/';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result['@vocab']).toBe('https://example.com/vocab/');
+    });
+
+    it('should not append # to vocab URI ending with #', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab#';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result['@vocab']).toBe('https://example.com/vocab#');
+    });
+  });
+
+  describe('schema.org domain handling', () => {
+    it('should not add schema property when vocab is schema.org', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://schema.org/';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).not.toHaveProperty('schema');
+      expect(result['@vocab']).toBe('https://schema.org/');
+    });
+
+    it('should add schema property when vocab is schema.org with # (exact match required)', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://schema.org/#';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      // Note: The implementation checks if vocab === 'https://schema.org/' exactly,
+      // so 'https://schema.org/#' will not match and schema will be added
+      // This tests the actual behavior of the implementation
+      expect(result).toHaveProperty('schema', 'https://schema.org/');
+      expect(result['@vocab']).toBe('https://schema.org/#');
+    });
+
+    it('should add schema property when vocab is not schema.org', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).toHaveProperty('schema', 'https://schema.org/');
+    });
+
+    it('should add schema property for custom vocab URI', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://custom-domain.com/ontology';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).toHaveProperty('schema', 'https://schema.org/');
+    });
+  });
+
+  describe('mixed scenarios', () => {
+    it('should handle complex properties object with various types', () => {
+      const properties: Record<string, PropertySchema> = {
+        id: { type: 'string' }, // protected
+        type: { type: 'string' }, // protected
+        name: { type: 'string' }, // no @type
+        age: { type: 'integer' }, // schema:Integer
+        price: { type: 'number' }, // schema:Number
+        birthDate: { type: 'string', format: 'date' }, // schema:Date
+        createdAt: { type: 'string', format: 'date-time' }, // schema:DateTime
+        reference: { $ref: '#/definitions/Person' }, // $ref, no @type
+        custom: { '@type': 'schema:CustomType' }, // explicit @type
+        active: { type: 'boolean' }, // no @type
+        '@context': { type: 'string' }, // protected
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      // Check header
+      expect(result['@vocab']).toBe('https://example.com/vocab#');
+      expect(result['@version']).toBe(1.1);
+      expect(result['@protected']).toBe(true);
+      expect(result.schema).toBe('https://schema.org/');
+
+      // Check protected properties are skipped
+      expect(result).not.toHaveProperty('id');
+      expect(result).not.toHaveProperty('type');
+      expect(result).not.toHaveProperty('@context');
+
+      // Check properties without @type
+      expect(result.name).toEqual({ '@id': 'name' });
+      expect(result.active).toEqual({ '@id': 'active' });
+
+      // Check properties with @type
+      expect(result.age).toEqual({ '@id': 'age', '@type': 'schema:Integer' });
+      expect(result.price).toEqual({ '@id': 'price', '@type': 'schema:Number' });
+      expect(result.birthDate).toEqual({ '@id': 'birthDate', '@type': 'schema:Date' });
+      expect(result.createdAt).toEqual({ '@id': 'createdAt', '@type': 'schema:DateTime' });
+      expect(result.custom).toEqual({ '@id': 'custom', '@type': 'schema:CustomType' });
+
+      // Check property with $ref
+      expect(result.reference).toEqual({ '@id': 'reference' });
+    });
+
+    it('should handle empty properties object', () => {
+      const properties: Record<string, PropertySchema> = {};
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).toEqual({
+        '@vocab': 'https://example.com/vocab#',
+        '@version': 1.1,
+        '@protected': true,
+        schema: 'https://schema.org/',
+      });
+    });
+
+    it('should handle properties object with only protected properties', () => {
+      const properties: Record<string, PropertySchema> = {
+        id: { type: 'string' },
+        type: { type: 'string' },
+        schema: { type: 'string' },
+        '@context': { type: 'string' },
+      };
+      const vocabUri = 'https://example.com/vocab';
+
+      const result = getLinkedDataContext(properties, vocabUri);
+
+      expect(result).toEqual({
+        '@vocab': 'https://example.com/vocab#',
+        '@version': 1.1,
+        '@protected': true,
+        schema: 'https://schema.org/',
+      });
+    });
+  });
+});

package/src/ld/documentLoader.ts

@@ -0,0 +1,28 @@
+import { contexts as securityContextsMap } from 'security-context';
+import { contexts as credentialsContextsMap } from 'credentials-context';
+
+const CONTEXTS = new Map([
+  ...securityContextsMap,
+  ...credentialsContextsMap
+]);
+
+/** Returns document from the context via url */
+const documentLoader = (documentUrl: string) => {
+  const contextUrl = null;
+
+  const [ url ] = documentUrl.split('#');
+
+  const document = CONTEXTS.get(url);
+
+  if (!document) {
+    throw new Error(`Custom context "${documentUrl}" is not supported`);
+  }
+
+  return {
+    document,
+    contextUrl,
+    documentUrl
+  };
+};
+
+export default documentLoader;

package/src/ld/getLinkedDataAttributeType.ts

@@ -0,0 +1,46 @@
+import { get } from 'lodash';
+
+export type PropertySchema = {
+  '@type'?: string;
+  $ref?: string;
+  type?: string;
+  format?: string;
+};
+
+/** Returns linked data attribute type for a property schema, unless @type is defined */
+const getLinkedDataAttributeType = (propertySchema: PropertySchema): string | undefined => {
+  const isOverriden = !!get(propertySchema, '@type');
+
+  if (isOverriden) {
+    return get(propertySchema, '@type');
+  }
+
+  // TODO: Add support for all types and formats, extend schema library with
+  //       support for additional formats, e.g. URL, Duration etc.
+  const { type, format } = propertySchema;
+
+  const isDate = format === 'date';
+  const isNumber = type === 'number';
+  const isInteger = type === 'integer';
+  const isDateTime = format === 'date-time';
+
+  if (isInteger) {
+    return 'schema:Integer';
+  }
+
+  if (isNumber) {
+    return 'schema:Number';
+  }
+
+  if (isDate) {
+    return 'schema:Date';
+  }
+
+  if (isDateTime) {
+    return 'schema:DateTime';
+  }
+
+  return;
+};
+
+export default getLinkedDataAttributeType;

package/src/ld/getLinkedDataContext.ts

@@ -0,0 +1,80 @@
+import getLinkedDataAttributeType, { type PropertySchema } from './getLinkedDataAttributeType';
+
+export type { PropertySchema };
+
+const SCHEMA_ORG_URI = 'https://schema.org/';
+
+const PROTECTED_PROPERTIES = [
+  'id',
+  'type',
+  'schema'
+];
+
+type ContextProperty = {
+  '@id': string;
+  '@type'?: string;
+};
+
+type ContextHeader = {
+  '@vocab': string;
+  '@version': number;
+  '@protected': boolean;
+  schema?: string;
+};
+
+export type LinkedDataContext = ContextHeader & {
+  [key: string]: ContextProperty | string | number | boolean | undefined;
+};
+
+/** Returns linked data context for a properties object */
+const getLinkedDataContext = (properties: Record<string, PropertySchema>, vocabUri: string): LinkedDataContext => {
+  const context = {} as Record<string, ContextProperty>;
+
+  // TODO: Add support for embedded object, array and enum.
+  for (const key in properties) {
+    const propertySchema = properties[key];
+
+    const isProtected =
+      PROTECTED_PROPERTIES.includes(key) ||
+      key.startsWith('@');
+
+    if (isProtected) {
+      continue;
+    }
+
+    context[key] = { '@id': key };
+
+    const { $ref } = propertySchema;
+
+    if ($ref) {
+      continue;
+    }
+
+    const linkedDataType = getLinkedDataAttributeType(propertySchema);
+
+    if (linkedDataType) {
+      context[key]['@type'] = linkedDataType;
+    }
+  }
+
+  const vocab = vocabUri.endsWith('/') || vocabUri.endsWith('#') ? vocabUri : `${vocabUri}#`;
+
+  const contextHeader = {
+    '@vocab': vocab,
+    '@version': 1.1,
+    '@protected': true
+  } as ContextHeader;
+
+  const isSchemaOrgDomain = vocab === SCHEMA_ORG_URI;
+
+  if (!isSchemaOrgDomain) {
+    contextHeader.schema = SCHEMA_ORG_URI;
+  }
+
+  return {
+    ...contextHeader,
+    ...context
+  };
+};
+
+export default getLinkedDataContext;

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "target": "esnext",
+    "module": "nodenext",
+    "isolatedModules": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src",
+    "types"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts"
+  ]
+}

package/types/credentials-context.d.ts

@@ -0,0 +1,14 @@
+declare module 'credentials-context' {
+  /**
+   * Map of credentials context URLs to their JSON-LD context documents
+   */
+  export const contexts: Map<string, Record<string, unknown>>;
+
+  /**
+   * Constants for credentials context
+   */
+  export const constants: {
+    CREDENTIALS_CONTEXT_V1_URL: string;
+    [key: string]: string;
+  };
+}

package/types/security-context.d.ts

@@ -0,0 +1,6 @@
+declare module 'security-context' {
+  /**
+   * Map of security context URLs to their JSON-LD context documents
+   */
+  export const contexts: Map<string, Record<string, unknown>>;
+}

package/examples/Status.yaml

@@ -1,3 +0,0 @@
-enum:
-  - 'Pending'
-  - 'Active'

package/examples/createAccountCredential.js

@@ -1,27 +0,0 @@
-'use strict'
-
-const { Schema, CredentialFactory } = require('../src')
-
-const accountSchema = new Schema({
-  id:          {},
-  username:    { required: true },
-  createdAt:   { format: 'date-time', required: true },
-  dateOfBirth: { format: 'date' }
-}, 'Account')
-
-const factory = new CredentialFactory('https://example.com/schema/AccountV1', accountSchema)
-
-const createAccountCredential = (holder, username) => {
-  const id = `https://example.com/account/${username}`
-
-  const createdAt = new Date().toISOString()
-  const subject = {
-    id: holder,
-    username,
-    createdAt
-  }
-
-  return factory.createCredential(id, holder, subject)
-}
-
-module.exports = createAccountCredential

package/examples/createMineSweeperScoreCredential.js

@@ -1,63 +0,0 @@
-'use strict'
-
-const { Schema, CredentialFactory } = require('../src')
-
-const GAME_NAME    = 'MineSweeper'
-const GAME_VERSION = '1.0'
-
-const SCHEMA_ORG_URI = 'https://schema.org/'
-
-const playerSchema = new Schema({
-  id:                {},
-  hasVideoGameScore: { $ref: 'VideoGameScore', required: true }
-}, 'Player')
-
-const videoGameSchema = new Schema({
-  id:      {},
-  name:    { type: 'string', required: true },
-  version: { type: 'string', required: true }
-}, 'VideoGame', SCHEMA_ORG_URI)
-
-const videoGameScoreSchema = new Schema({
-  game:          { $ref: 'VideoGame', required: true },
-  wins:          { type: 'integer', required: true },
-  losses:        { type: 'integer', required: true },
-  winRate:       { type: 'number', required: true },
-  bestScore:     { type: 'integer', required: true },
-  // TODO: Add duration as format:
-  endurance:     { type: 'string', required: true, '@type': 'schema:Duration' },
-  dateCreated:   { type: 'string', 'format': 'date-time', required: true },
-  bestRoundTime: { type: 'integer', required: true }
-  // difficultyLevel:
-  //   enum:
-  //     - EASY
-  //     - MEDIUM
-  //     - HARD
-  //   required: true
-}, 'VideoGameScore')
-
-const CREDENTIAL_URI = `https://example.com/schema/${GAME_NAME}ScoreV1`
-const SCHEMAS = [ playerSchema, videoGameSchema, videoGameScoreSchema ]
-const factory = new CredentialFactory(CREDENTIAL_URI, SCHEMAS)
-
-const createMineSweeperScoreCredential = (gameId, playerId, playerScore) => {
-  const credentialId = 'https://example.com/credentials/CREDENTIAL_ID'
-
-  const game = {
-    id:      gameId,
-    name:    GAME_NAME,
-    version: GAME_VERSION
-  }
-
-  const player = {
-    id: playerId,
-    hasVideoGameScore: {
-      ...playerScore,
-      game
-    }
-  }
-
-  return factory.createCredential(credentialId, playerId, player)
-}
-
-module.exports = createMineSweeperScoreCredential

package/examples/index.js

@@ -1,9 +0,0 @@
-'use strict'
-
-const createAccountCredential = require('./createAccountCredential')
-const createMineSweeperScoreCredential = require('./createMineSweeperScoreCredential')
-
-module.exports = {
-  createAccountCredential,
-  createMineSweeperScoreCredential
-}