@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/internal/entities/entity.ts

@@ -9,33 +9,42 @@ import type * as Types from 'effect/Types';
 import { type ToMutable } from '@dxos/util';
 
 import { type TypeMeta } from '../annotations';
-import { type HasId } from '../types';
+import { type AnyEntity, type EntityKind, SchemaKindId } from '../types';
 
 // TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
 
 // type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
-export type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<HasId & ToMutable<T> & ExtraFields>;
+export type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<AnyEntity & ToMutable<T> & ExtraFields>;
 
 // TODO(burdon): Rename EchoEntitySchema.
-export interface EchoTypeSchema<Self extends Schema.Schema.Any, ExtraFields = {}>
-  extends TypeMeta,
+export interface EchoTypeSchema<
+  Self extends Schema.Schema.Any,
+  ExtraFields = {},
+  K extends EntityKind = EntityKind,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> extends TypeMeta,
     Schema.AnnotableClass<
-      EchoTypeSchema<Self, ExtraFields>,
+      EchoTypeSchema<Self, ExtraFields, K, Fields>,
       EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
       EchoTypeSchemaProps<Schema.Schema.Encoded<Self>, ExtraFields>,
       Schema.Schema.Context<Self>
     > {
-  // make(
-  //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
-  //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
-  //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-  //   options?: MakeOptions,
-  // ): Simplify<Schema.TypeLiteral.Type<Fields, []>>;
+  /**
+   * Schema kind key that marks this as an ECHO schema and indicates its kind.
+   * Makes EchoTypeSchema satisfy the Type.Obj.Any or Type.Relation.Any type.
+   */
+  readonly [SchemaKindId]: K;
+
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
 
   instanceOf(value: unknown): boolean;
 }
 
-// type MakeOptions =
+// type MakeProps =
 //   | boolean
 //   | {
 //       readonly disableValidation?: boolean;
@@ -63,18 +72,24 @@ export interface EchoTypeSchema<Self extends Schema.Schema.Any, ExtraFields = {}
 //   return out;
 // };
 
-// const _getDisableValidationMakeOption = (options: MakeOptions | undefined): boolean =>
+// const _getDisableValidationMakeOption = (options: MakeProps | undefined): boolean =>
 //   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
 
 /**
  * @internal
  */
-export const makeEchoTypeSchema = <Self extends Schema.Schema.Any>(
-  // fields: Fields,
+export const makeEchoTypeSchema = <
+  Self extends Schema.Schema.Any,
+  K extends EntityKind = EntityKind,
+  // TODO(wittjosiah): Can this be inferred from the schema?
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+>(
+  fields: Fields,
   ast: SchemaAST.AST,
   typename: string,
   version: string,
-): EchoTypeSchema<Self> => {
+  kind: K,
+): EchoTypeSchema<Self, {}, K, Fields> => {
   return class EchoObjectSchemaClass extends Schema.make<
     EchoTypeSchemaProps<Schema.Schema.Type<Self>>,
     EchoTypeSchemaProps<Schema.Schema.Encoded<Self>>,
@@ -82,19 +97,21 @@ export const makeEchoTypeSchema = <Self extends Schema.Schema.Any>(
   >(ast) {
     static readonly typename = typename;
     static readonly version = version;
+    static readonly [SchemaKindId] = kind;
+    static readonly fields = fields;
 
     static override annotations(
       annotations: Schema.Annotations.GenericSchema<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>,
-    ): EchoTypeSchema<Self> {
+    ): EchoTypeSchema<Self, {}, K, Fields> {
       const schema = Schema.make<EchoTypeSchemaProps<Schema.Schema.Type<Self>>>(ast).annotations(annotations);
-      return makeEchoTypeSchema<Self>(/* fields, */ schema.ast, typename, version);
+      return makeEchoTypeSchema<Self, K, Fields>(fields, schema.ast, typename, version, kind);
     }
 
     // static make(
     //   props: RequiredKeys<Schema.TypeLiteral.Constructor<Fields, []>> extends never
     //     ? void | Simplify<Schema.TypeLiteral.Constructor<Fields, []>>
     //     : Simplify<Schema.TypeLiteral.Constructor<Fields, []>>,
-    //   options?: MakeOptions,
+    //   options?: MakeProps,
     // ): Simplify<Schema.TypeLiteral.Type<Fields, []>> {
     //   const propsWithDefaults: any = _lazilyMergeDefaults(fields, { ...(props as any) });
     //   return _getDisableValidationMakeOption(options)

package/src/internal/entities/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './expando';
+export * from './entity';
 export * from './model'; // TODO(burdon): Rename.
 export * from './object';
 export * from './relation';

package/src/internal/entities/model.ts

@@ -9,6 +9,7 @@ import { invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
+import type * as Database from '../../Database';
 import {
   type ATTR_META,
   type ATTR_TYPE,
@@ -59,25 +60,24 @@ export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
  */
 export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
 
+/**
+ * Object database accessor symbol.
+ */
+export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+
 /**
  * Internal runtime representation of an object.
  * The fields are accessed through getter functions.
  */
+// NOTE: Each symbol has a jsdoc describing its purpose.
 export interface InternalObjectProps {
-  id: ObjectId;
-
-  // Echo supports untyped objects O_O.
-  readonly [TypeId]?: DXN;
-
-  //
-  readonly [SelfDXNId]?: DXN;
-
-  /**
-   * Returns the schema for the object.
-   */
-  readonly [SchemaId]?: Schema.Schema.AnyNoContext;
+  readonly id: ObjectId;
+  readonly [SelfDXNId]: DXN;
   readonly [KindId]: EntityKind;
+  readonly [SchemaId]: Schema.Schema.AnyNoContext;
+  readonly [TypeId]: DXN;
   readonly [MetaId]?: ObjectMeta;
+  readonly [ObjectDatabaseId]?: Database.Database;
   readonly [ObjectDeletedId]?: boolean;
   readonly [ObjectVersionId]?: Version;
   readonly [RelationSourceDXNId]?: DXN;
@@ -105,6 +105,11 @@ export interface ObjectJSON {
   [ATTR_META]?: ObjectMetaJSON;
   [ATTR_RELATION_SOURCE]?: DXN.String;
   [ATTR_RELATION_TARGET]?: DXN.String;
+
+  /**
+   * Application-specific properties.
+   */
+  [key: string]: unknown;
 }
 
 /**

package/src/internal/entities/object.ts

@@ -12,19 +12,34 @@ import { EntityKind } from '../types';
 
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
+/**
+ * Object schema type with kind marker.
+ */
+export type EchoObjectSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Object, Fields>;
+
 /**
  * Schema for Obj entity types.
  * Pipeable function to add ECHO object annotations to a schema.
  */
 export const EchoObjectSchema: {
-  // TODO(burdon): Tighten Self type to Schema.TypeLiteral or Schema.Struct to facilitate definition of `make` method.
-  // (meta: TypeMeta): <Self extends Schema.Struct<Fields>, Fields extends Schema.Struct.Fields>(self: Self) => EchoObjectSchema<Self, Fields>;
-  (meta: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => EchoTypeSchema<Self>;
+  (
+    meta: TypeMeta,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoObjectSchema<Self, Fields>;
 } = ({ typename, version }) => {
-  return <Self extends Schema.Schema.Any>(self: Self): EchoTypeSchema<Self> => {
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoObjectSchema<Self, Fields> => {
     invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
     invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
 
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
     // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
     // TODO(dmaretskyi): Do not do mutable here.
     const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
@@ -40,6 +55,6 @@ export const EchoObjectSchema: {
       }),
     });
 
-    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(fields, ast, typename, version, EntityKind.Object);
   };
 };

package/src/internal/entities/relation.ts

@@ -83,6 +83,21 @@ export type EchoRelationSchemaOptions<
   target: TTarget;
 };
 
+/**
+ * Relation schema type with kind marker.
+ */
+export type EchoRelationSchema<
+  Self extends Schema.Schema.Any,
+  Source extends Schema.Schema.AnyNoContext,
+  Target extends Schema.Schema.AnyNoContext,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<
+  Self,
+  RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>,
+  EntityKind.Relation,
+  Fields
+>;
+
 /**
  * Schema for Relation entity types.
  */
@@ -106,11 +121,14 @@ export const EchoRelationSchema = <
     raise(new Error('Target schema must be an echo object schema.'));
   }
 
-  return <Self extends Schema.Schema.Any>(
-    self: Self,
-  ): EchoTypeSchema<Self, RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>> => {
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoRelationSchema<Self, Source, Target, Fields> => {
     invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
 
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
     // TODO(dmaretskyi): Does `Schema.mutable` work for deep mutability here?
     // TODO(dmaretskyi): Do not do mutable here.
     const schemaWithId = Schema.extend(Schema.mutable(self), Schema.Struct({ id: Schema.String }));
@@ -135,7 +153,7 @@ export const EchoRelationSchema = <
       }),
     });
 
-    return makeEchoTypeSchema<Self>(/* self.fields, */ ast, typename, version);
+    return makeEchoTypeSchema<Self, EntityKind.Relation, Fields>(fields, ast, typename, version, EntityKind.Relation);
   };
 };
 

package/src/internal/formats/format.ts

@@ -10,11 +10,10 @@ import * as DateUtil from './date';
 import * as NumberUtil from './number';
 import * as ObjectUtil from './object';
 import * as StringUtil from './string';
-import { TypeFormat as TypeFormatEnum } from './types';
+import { TypeFormat as TypeFormat$ } from './types';
 
-// TODO(burdon): Consider factoring out to separate `@dxos/json-schema`
 // TODO(burdon): Media encoding.
-//  - https://json-schema.org/understanding-json-schema/reference/non_json_data
+// - https://json-schema.org/understanding-json-schema/reference/non_json_data
 
 /**
  * Formats.
@@ -23,9 +22,9 @@ import { TypeFormat as TypeFormatEnum } from './types';
  */
 // TODO(burdon): Add fields for `examples`, `message`, etc.
 export namespace Format {
-  export import TypeFormat = TypeFormatEnum;
+  export import TypeFormat = TypeFormat$;
 
-  // Strings
+  // String
   export const DXN = Keys.DXN.Schema;
   export const Email = StringUtil.Email;
   export const Formula = StringUtil.Formula;
@@ -44,12 +43,12 @@ export namespace Format {
   export const Timestamp = NumberUtil.Timestamp;
 
   // Dates and times
-  export const DateTime = DateUtil.DateTime;
   export const Date = DateUtil.DateOnly;
-  export const Time = DateUtil.TimeOnly;
+  export const DateTime = DateUtil.DateTime;
   export const Duration = DateUtil.Duration;
+  export const Time = DateUtil.TimeOnly;
 
   // Objects
   export const GeoPoint = ObjectUtil.GeoPoint;
-  export type GeoPoint = ObjectUtil.GeoPoint;
+  export type GeoPoint = ObjectUtil.GeoPoint; // TODO(burdon): Export types.
 }

package/src/internal/formats/object.ts

@@ -21,8 +21,8 @@ import { FormatAnnotation, TypeFormat } from './types';
  * Note: optional third element for altitude.
  */
 export const GeoPoint = Schema.Tuple(
-  Schema.Number.pipe(Schema.annotations({ title: 'Longitude' }), Schema.clamp(-180, 180), Schema.multipleOf(0.00001)),
-  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.00001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Longitude' }), Schema.clamp(-180, 180), Schema.multipleOf(0.000001)),
+  Schema.Number.pipe(Schema.annotations({ title: 'Latitude' }), Schema.clamp(-90, 90), Schema.multipleOf(0.000001)),
   Schema.optionalElement(Schema.Number).annotations({
     title: 'Height ASL (m)',
   }),

package/src/internal/formats/select.ts

@@ -4,8 +4,10 @@
 
 import * as Schema from 'effect/Schema';
 
-/** Schema for a single select option. Used to define choices in a {single|multi}-select field. */
-export const SelectOptionSchema = Schema.Struct({
+/**
+ * Schema for a single select option. Used to define choices in a {single|multi}-select field.
+ */
+export const SelectOption = Schema.Struct({
   /** Stable identifier for the option. */
   id: Schema.NonEmptyString,
   title: Schema.String,
@@ -13,4 +15,4 @@ export const SelectOptionSchema = Schema.Struct({
   color: Schema.String,
 }).pipe(Schema.mutable);
 
-export type SelectOption = Schema.Schema.Type<typeof SelectOptionSchema>;
+export type SelectOption = Schema.Schema.Type<typeof SelectOption>;

package/src/internal/formats/string.ts

@@ -52,6 +52,11 @@ export const Markdown = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Markd
 // TODO(burdon): Implement.
 export const Regex = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Regex));
 
+/**
+ * Multi-line text.
+ */
+export const Text = Schema.String.pipe(FormatAnnotation.set(TypeFormat.Text));
+
 /**
  * https://datatracker.ietf.org/doc/html/rfc3986#section-1.1.3
  */

package/src/internal/formats/types.ts

@@ -55,6 +55,7 @@ export const FormatAnnotationId = Symbol.for('@dxos/schema/annotation/Format');
 
 export const FormatAnnotation = createAnnotationHelper<TypeFormat>(FormatAnnotationId);
 
+/** @deprecated */
 export const getFormatAnnotation = (node: SchemaAST.AST): TypeFormat | undefined =>
   Function.pipe(SchemaAST.getAnnotation<TypeFormat>(FormatAnnotationId)(node), Option.getOrUndefined);
 
@@ -84,6 +85,7 @@ export enum TypeFormat {
   Markdown = 'markdown',
   Regex = 'regex',
   SingleSelect = 'single-select',
+  Text = 'text',
   MultiSelect = 'multi-select',
   URL = 'url',
   UUID = 'uuid',
@@ -151,6 +153,7 @@ export const formatToType: Record<TypeFormat, TypeEnum> = {
   [TypeFormat.URL]: TypeEnum.String,
   [TypeFormat.UUID]: TypeEnum.String,
   [TypeFormat.SingleSelect]: TypeEnum.String,
+  [TypeFormat.Text]: TypeEnum.String,
   [TypeFormat.MultiSelect]: TypeEnum.Object,
 
   // Dates
@@ -174,7 +177,10 @@ export const formatToType: Record<TypeFormat, TypeEnum> = {
  */
 export const OptionsAnnotationId = Symbol.for('@dxos/schema/annotation/Options');
 
-export const getOptionsAnnotation = (node: SchemaAST.AST): OptionsAnnotationType[] | undefined =>
-  Function.pipe(SchemaAST.getAnnotation<OptionsAnnotationType[]>(OptionsAnnotationId)(node), Option.getOrUndefined);
+// TODO(wittjosiah): Reconcile with `SelectOption`.
+export type Options = string | number;
+export const OptionsAnnotation = createAnnotationHelper<Options[]>(OptionsAnnotationId);
 
-export type OptionsAnnotationType = string | number;
+/** @deprecated */
+export const getOptionsAnnotation = (node: SchemaAST.AST): Options[] | undefined =>
+  Function.pipe(SchemaAST.getAnnotation<Options[]>(OptionsAnnotationId)(node), Option.getOrUndefined);

package/src/internal/index.ts

@@ -3,9 +3,10 @@
 //
 
 // TODO(burdon): Import directly (not part of ECHO API).
-export { JsonPath, JsonProp, getValue, setValue, splitJsonPath } from '@dxos/effect';
+export { JsonPath, JsonProp, getValue, splitJsonPath } from '@dxos/effect';
 
 export * from './annotations';
+export * from './api';
 export * from './entities';
 export * from './formats';
 export * from './json-schema';

package/src/internal/json-schema/json-schema-type.ts

@@ -54,7 +54,7 @@ export const JsonSchemaEchoAnnotations = Schema.Struct({
   /**
    * @deprecated
    */
-  // TODO(dmaretskyi): We risk old schema not passing validation due to the extra fields. Remove when we are sure this is safe
+  // TODO(dmaretskyi): We risk old schema not passing validation due to the extra fields. Remove when we are sure this is safe.
   type: Schema.optional(
     Schema.Struct({
       typename: Schema.String,

package/src/internal/json-schema/json-schema.test.ts

@@ -35,7 +35,7 @@ const EXAMPLE_NAMESPACE = '@example';
 describe('effect-to-json', () => {
   test('type annotation', () => {
     const Test = Schema.Struct({ name: Schema.String }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -50,7 +50,7 @@ describe('effect-to-json', () => {
     const Test = Schema.Struct({
       name: Schema.String.pipe(PropertyMeta(EXAMPLE_NAMESPACE, meta)),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -63,7 +63,7 @@ describe('effect-to-json', () => {
     const Nested = Schema.Struct({
       name: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/TestNested',
         version: '0.1.0',
       }),
@@ -71,7 +71,7 @@ describe('effect-to-json', () => {
     const Test = Schema.Struct({
       name: Ref(Nested),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -88,7 +88,7 @@ describe('effect-to-json', () => {
     const Nested = Schema.Struct({
       name: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/TestNested',
         version: '0.1.0',
       }),
@@ -96,7 +96,7 @@ describe('effect-to-json', () => {
     const Test = Schema.Struct({
       name: Ref(Nested).annotations({ [FieldLookupAnnotationId]: 'name' }),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -112,7 +112,7 @@ describe('effect-to-json', () => {
     const Nested = Schema.Struct({
       name: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/TestNested',
         version: '0.1.0',
       }),
@@ -120,7 +120,7 @@ describe('effect-to-json', () => {
     const Test = Schema.Struct({
       name: Schema.Array(Ref(Nested)),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -134,7 +134,7 @@ describe('effect-to-json', () => {
     const Nested = Schema.Struct({
       name: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/TestNested',
         version: '0.1.0',
       }),
@@ -142,7 +142,7 @@ describe('effect-to-json', () => {
     const Test = Schema.Struct({
       name: Schema.optional(Ref(Nested)),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Test',
         version: '0.1.0',
       }),
@@ -165,7 +165,7 @@ describe('effect-to-json', () => {
         description: 'Email address',
       }),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Person',
         version: '0.1.0',
       }),
@@ -204,9 +204,11 @@ describe('effect-to-json', () => {
       'name',
       'username',
       'email',
+      'age',
       'tasks',
       'employer',
       'address',
+      'fields',
     ]);
   });
 
@@ -214,7 +216,7 @@ describe('effect-to-json', () => {
     const Organization = Schema.Struct({
       field: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Organization',
         version: '0.1.0',
       }),
@@ -224,7 +226,7 @@ describe('effect-to-json', () => {
       name: Schema.String,
       organization: Ref(Organization).annotations({ description: 'Contact organization' }),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Person',
         version: '0.1.0',
       }),
@@ -276,7 +278,7 @@ describe('effect-to-json', () => {
     const Organization = Schema.Struct({
       field: Schema.String,
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Organization',
         version: '0.1.0',
       }),
@@ -286,7 +288,7 @@ describe('effect-to-json', () => {
       name: Schema.String,
       organization: Ref(Organization).annotations({ description: 'Contact organization' }),
     }).pipe(
-      Type.Obj({
+      Type.object({
         typename: 'example.com/type/Person',
         version: '0.1.0',
       }),
@@ -494,7 +496,7 @@ describe('json-to-effect', () => {
       const Organization = Schema.Struct({
         field: Schema.String,
       }).pipe(
-        Type.Obj({
+        Type.object({
           typename: 'example.com/type/Organization',
           version: '0.1.0',
         }),
@@ -515,7 +517,7 @@ describe('json-to-effect', () => {
       } as const;
 
       const Test = (partial ? Schema.partial(Schema.Struct(fields)) : Schema.Struct(fields)).pipe(
-        Type.Obj({
+        Type.object({
           typename: 'example.com/type/Test',
           version: '0.1.0',
         }),

package/src/internal/json-schema/json-schema.ts

@@ -23,9 +23,8 @@ import {
   TypeIdentifierAnnotationId,
   makeTypeJsonSchemaAnnotation,
 } from '../annotations';
-import { Expando } from '../entities';
-import { type JsonSchemaReferenceInfo, Ref, createEchoReferenceSchema } from '../ref';
-import { EntityKind, EntityKindSchema } from '../types';
+import { type JsonSchemaReferenceInfo, createEchoReferenceSchema } from '../ref';
+import { ANY_OBJECT_TYPENAME, ANY_OBJECT_VERSION, EntityKind, EntityKindSchema } from '../types';
 
 import { CustomAnnotations, DecodedAnnotations, EchoAnnotations } from './annotations';
 import {
@@ -352,7 +351,8 @@ const anyToEffectSchema = (root: JSONSchema.JsonSchema7Any): Schema.Schema.AnyNo
 // TODO(dmaretskyi): Types.
 const refToEffectSchema = (root: any): Schema.Schema.AnyNoContext => {
   if (!('reference' in root)) {
-    return Ref(Expando);
+    // Fallback to generic object ref when no reference info is provided.
+    return createEchoReferenceSchema(undefined, ANY_OBJECT_TYPENAME, ANY_OBJECT_VERSION);
   }
 
   const reference: JsonSchemaReferenceInfo = root.reference;

package/src/internal/object/clone.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { deepMapValues } from '@dxos/util';
+
+import type * as Obj from '../../Obj';
+import { makeObject } from '../proxy';
+import { Ref } from '../ref';
+import { getMeta, getSchema } from '../types';
+
+/**
+ * Clones an object or relation.
+ * This does not clone referenced objects, only the properties in the object.
+ * @returns A new object with the same schema and properties.
+ */
+export const clone = <T extends Obj.Any>(obj: T, opts?: Obj.CloneOptions): T => {
+  const { id, ...data } = obj;
+  const schema = getSchema(obj);
+  invariant(schema != null, 'Object should have a schema');
+  const props: any = deepMapValues(data, (value, recurse) => {
+    if (Ref.isRef(value)) {
+      if (opts?.deep) {
+        // TODO(dmaretskyi): Will break on circular references.
+        return Ref.make(clone(value.target!, opts));
+      }
+      return value;
+    }
+    return recurse(value);
+  });
+
+  if (opts?.retainId) {
+    props.id = id;
+  }
+  const meta = deepMapValues(getMeta(obj), (value, recurse) => {
+    if (Ref.isRef(value)) {
+      if (opts?.deep) {
+        // TODO(dmaretskyi): Will break on circular references.
+        return Ref.make(clone(value.target!, opts));
+      }
+      return value;
+    }
+    return recurse(value);
+  });
+
+  return makeObject(schema, props, meta);
+};