@yanqirenshi/model.tm 0.0.0-stage → 0.1.0

package/src/schema.ts

@@ -0,0 +1,194 @@
+// TM(d3.ter)の入力データの JSON Schema(2020-12)。コレクションごとに 1 つ。
+//
+// iHub の server/schemas/tm/*.schema.json を移したもの。iHub 版と違い additionalProperties を閉じていない
+// (利用側の項目を落とさないため)。検査するのは、図の構造にかかわる項目(id・type・参照・position・size・
+// 関係の端点・subset・mapping)。name は文字列でも { logical, physical } でもよい。
+//
+// x-id-start はスキーマの検証には使わない注釈(コレクションが空のときに最初に振る id)。
+// Ajv で使うときは addKeyword({ keyword: 'x-id-start', schemaType: 'number' }) を足す。
+
+import { CARDINALITIES, ENTITY_TYPES, OPTIONALITIES, SUBSET_KINDS } from './defaults.js';
+
+const ID = { type: ['integer', 'string'] } as const;
+
+const NAME = {
+  description: '文字列、または論理名と物理名の組',
+  oneOf: [
+    { type: 'string' },
+    {
+      type: 'object',
+      properties: {
+        logical: { type: 'string' },
+        physical: { type: 'string' },
+        description: { type: 'string' },
+      },
+      additionalProperties: true,
+    },
+  ],
+} as const;
+
+// マスタ(identifiers / attributes)の共通形
+function masterSchema(title: string, description: string, idStart: number) {
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title,
+    description,
+    'x-id-start': idStart,
+    type: 'array',
+    items: {
+      type: 'object',
+      properties: {
+        id: ID,
+        name: NAME,
+        description: { type: ['string', 'null'] },
+      },
+      required: ['id', 'name'],
+      additionalProperties: true,
+    },
+  } as const;
+}
+
+export const IDENTIFIERS_SCHEMA = masterSchema(
+  'TM の識別子のマスタ',
+  '識別子 (個体指定子) のマスタ。entities[].identifiers[].identifier から id で参照される。',
+  10000,
+);
+
+export const ATTRIBUTES_SCHEMA = masterSchema(
+  'TM の属性のマスタ',
+  '属性のマスタ。entities[].attributes[].attribute から id で参照される。',
+  20000,
+);
+
+// エンティティが持つインスタンス(識別子・属性)の共通形。ref はマスタを指す項目名
+function instanceSchema(ref: 'identifier' | 'attribute') {
+  return {
+    type: 'array',
+    items: {
+      type: 'object',
+      properties: {
+        id: ID,
+        [ref]: ID,
+        name: NAME,
+        description: { type: ['string', 'null'] },
+      },
+      required: ['id', ref],
+      additionalProperties: true,
+    },
+  } as const;
+}
+
+export const ENTITIES_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'TM のエンティティ',
+  description: 'TM (T字形ER) のエンティティ。type は 10 種の種別 (これ以外は d3.ter が描画時に例外にする)。識別子・属性はマスタの id を参照するインスタンスとして持ち、インスタンスの id は全エンティティを通して一意 (関係の details がこれを指す)。name は文字列か論理名・物理名の組。position はドラッグで書き換わる。size の w / h が 0 のときは内容に合わせる。',
+  'x-id-start': 30000,
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      id: ID,
+      type: { enum: [...ENTITY_TYPES] },
+      name: NAME,
+      description: { type: ['string', 'null'] },
+      position: {
+        type: 'object',
+        properties: {
+          x: { type: 'number' },
+          y: { type: 'number' },
+          z: { type: 'number' },
+        },
+        required: ['x', 'y'],
+        additionalProperties: false,
+      },
+      size: {
+        type: 'object',
+        properties: {
+          w: { type: 'number', minimum: 0 },
+          h: { type: 'number', minimum: 0 },
+        },
+        required: ['w', 'h'],
+        additionalProperties: false,
+      },
+      identifiers: instanceSchema('identifier'),
+      attributes: instanceSchema('attribute'),
+    },
+    required: ['id', 'type', 'name'],
+    additionalProperties: true,
+  },
+} as const;
+
+export const RELATIONSHIPS_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'TM のリレーションシップ',
+  description: 'エンティティの間の結線。from.entity / to.entity はエンティティの id (同じエンティティを指すと自己結線 = 再帰のループ)。端点の cardinality (1 / 3) と optionality (0 / 1) は無ければ記号を描かない。position は接続位置の角度 (0=真下・時計回り)。details は線を取り付けるインスタンス (省略すると先頭の識別子)。subset はサブセット結線の区分コード (same は =、different は ×)。mapping は結線の中点から垂下する対応表・対照表・再帰表 (再帰表は自己結線にだけ)。',
+  'x-id-start': 1,
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      id: ID,
+      type: { type: ['string', 'null'] },
+      from: { $ref: '#/$defs/end' },
+      to: { $ref: '#/$defs/end' },
+      details: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            from: { $ref: '#/$defs/detail_end' },
+            to: { $ref: '#/$defs/detail_end' },
+          },
+          required: ['from', 'to'],
+        },
+      },
+      subset: {
+        type: ['object', 'null'],
+        properties: {
+          kind: { enum: [...SUBSET_KINDS] },
+          code: { type: 'string' },
+        },
+        required: ['kind', 'code'],
+      },
+      mapping: {
+        type: ['object', 'null'],
+        properties: { entity: ID },
+        required: ['entity'],
+      },
+      label: { type: ['string', 'null'] },
+      description: { type: ['string', 'null'] },
+    },
+    required: ['id', 'from', 'to'],
+    additionalProperties: true,
+  },
+  $defs: {
+    end: {
+      type: 'object',
+      properties: {
+        entity: ID,
+        cardinality: { enum: [...CARDINALITIES], description: '1 か 多 (3)。無ければ記号を描かない' },
+        optionality: { enum: [...OPTIONALITIES], description: '0 は任意 (○)、1 は必須 (横棒)。無ければ記号を描かない' },
+        position: { type: 'number', description: '接続位置の角度。0=真下・時計回り (90=左 / 180=真上 / 270=右)' },
+        id: { ...ID, description: '旧来の項目。端点の識別子のインスタンスの id (details に置き換わった)' },
+      },
+      required: ['entity'],
+      additionalProperties: true,
+    },
+    detail_end: {
+      type: 'object',
+      properties: {
+        id: ID,
+        description: { type: ['string', 'null'] },
+      },
+      required: ['id'],
+    },
+  },
+} as const;
+
+/** コレクション名 → スキーマ */
+export const SCHEMAS = {
+  identifiers: IDENTIFIERS_SCHEMA,
+  attributes: ATTRIBUTES_SCHEMA,
+  entities: ENTITIES_SCHEMA,
+  relationships: RELATIONSHIPS_SCHEMA,
+} as const;

package/src/types.ts

@@ -0,0 +1,165 @@
+// model.tm の公開型。
+//
+// ここで言う「レコード」は、d3.ter の data() に渡す入力そのものの 1 要素。
+//   { identifiers, attributes, entities, relationships }
+// 形は model.er(ER 図)と同じ階層形式で、TM 固有の項目(エンティティの type、関係の subset / mapping / label)が足されている。
+// d3.ter が正規化したあとの datum(_id / _core を持つ Atman)ではない。
+
+import type { Name, Position, Size } from '@yanqirenshi/types';
+
+/** レコードの id(コレクションの中で一意。インスタンス(identifiers / attributes の行)の id は全エンティティを通して一意) */
+export type TmId = number | string;
+
+/** 論理名・物理名の組(共有型 Name) */
+export type TmName = Name;
+
+/**
+ * TM(T字形ER)のエンティティ種別(10 種)。これ以外は d3.ter が描画時に例外にする。
+ * CLASS は「クラスで整える」の箱で、種別バッジを持たず、切り出し元(親)としか結線できない。
+ */
+export type TmEntityType =
+  | 'RESOURCE' | 'RESOURCE-SUBSET'
+  | 'EVENT' | 'EVENT-SUBSET'
+  | 'COMPARATIVE' | 'CORRESPONDENCE' | 'RECURSION'
+  | 'MANY-VALUED-OR' | 'MANY-VALUED-AND'
+  | 'CLASS';
+
+/** マスタ(identifiers / attributes)のレコード。name は文字列でも Name でもよい */
+export interface TmMasterRecord {
+  id: TmId;
+  name?: string | TmName | null;
+  description?: string | null;
+  [key: string]: unknown;
+}
+
+/** エンティティが持つ識別子のインスタンス(identifier は identifiers[].id)。name は表示名の上書き(TM の (R) 表記など) */
+export interface TmIdentifierRef {
+  id: TmId;
+  identifier: TmId;
+  name?: string | TmName | null;
+  description?: string | null;
+  [key: string]: unknown;
+}
+
+/** エンティティが持つ属性のインスタンス(attribute は attributes[].id) */
+export interface TmAttributeRef {
+  id: TmId;
+  attribute: TmId;
+  name?: string | TmName | null;
+  description?: string | null;
+  [key: string]: unknown;
+}
+
+/** エンティティのレコード */
+export interface TmEntityRecord {
+  id: TmId;
+  type?: TmEntityType | string;
+  name?: string | TmName | null;
+  description?: string | null;
+  position?: Position;
+  /** w / h が 0 のときは view が内容に合わせて決める */
+  size?: Size;
+  identifiers?: TmIdentifierRef[];
+  attributes?: TmAttributeRef[];
+  [key: string]: unknown;
+}
+
+/** 1 か 多(3) */
+export type TmCardinality = 1 | 3;
+
+/** 0 は任意(○)、1 は必須(横棒) */
+export type TmOptionality = 0 | 1;
+
+/**
+ * 関係の端点。position はエンティティの中心から見た角度(0=真下・時計回り。90=左 / 180=真上 / 270=右)。
+ * cardinality / optionality が無いときは記号を描かない。
+ * id は旧来の項目(端点の識別子のインスタンス。details に置き換わった)で、あれば検査だけする。
+ */
+export interface TmRelationshipEnd {
+  entity: TmId;
+  cardinality?: TmCardinality;
+  optionality?: TmOptionality;
+  position?: number;
+  id?: TmId;
+  [key: string]: unknown;
+}
+
+/** 関係の線を取り付けるインスタンス(from.id / to.id はそれぞれの端のエンティティの識別子・属性のインスタンス) */
+export interface TmRelationshipDetail {
+  from: { id: TmId; description?: string | null };
+  to: { id: TmId; description?: string | null };
+}
+
+/** サブセットへの結線に添える区分コード。same は「=区分コード」、different は「×区分コード」 */
+export interface TmSubset {
+  kind: 'same' | 'different';
+  code: string;
+}
+
+/** 関係(リレーションシップ)のレコード */
+export interface TmRelationshipRecord {
+  id: TmId;
+  type?: string | null;
+  from: TmRelationshipEnd;
+  to: TmRelationshipEnd;
+  details?: TmRelationshipDetail[];
+  subset?: TmSubset | null;
+  /** 結線の中点から垂下する対応表・対照表・再帰表(エンティティの id) */
+  mapping?: { entity: TmId } | null;
+  label?: string | null;
+  description?: string | null;
+  [key: string]: unknown;
+}
+
+export type TmRecord = TmMasterRecord | TmEntityRecord | TmRelationshipRecord;
+
+/** 図全体(d3.ter の data() に渡すもの) */
+export interface TmGraph {
+  identifiers?: TmMasterRecord[];
+  attributes?: TmMasterRecord[];
+  entities?: TmEntityRecord[];
+  relationships?: TmRelationshipRecord[];
+}
+
+/** マスタのコレクション */
+export type TmMasterCollection = 'identifiers' | 'attributes';
+
+/** レコードを置くコレクション */
+export type TmCollection = TmMasterCollection | 'entities' | 'relationships';
+
+/** レコードの種類(どの形か) */
+export type TmKind = 'master' | 'entity' | 'relationship';
+
+/** JSON Merge Patch(RFC 7386)。null は「その項目を除く」 */
+export type MergePatch = { [key: string]: unknown };
+
+/** 保存する変更。利用側は図の種類を知らずにこれを保存すればよい */
+export interface TmChange {
+  collection: TmCollection;
+  id: TmId;
+  patch: MergePatch;
+}
+
+/** ドラッグの移動量(世界座標) */
+export interface TmMove {
+  dx: number;
+  dy: number;
+}
+
+/**
+ * 編集できる項目。colonoscope の ColonoscopeField(path / label / type)と同じ形で、
+ * 取りうる値の一覧 options だけ足している(型は構造的に互換。colonoscope には依存しない)。
+ */
+export type TmFieldType = 'text' | 'textarea' | 'number' | 'readonly';
+
+export interface TmField {
+  /** レコードの項目のパス(ドット区切り。例: 'from.position')。写し先ではなく実際の項目を指す */
+  path: string;
+  label: string;
+  type: TmFieldType;
+  /** 取りうる値の一覧(種別・カーディナリティなど。文字列で持つ) */
+  options?: readonly string[];
+}
+
+/** インスペクタの「適用」が渡す値(path → 入力した文字列) */
+export type TmValues = Record<string, string>;