@dxos/echo 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/Type.test.ts

@@ -11,42 +11,42 @@ import { TestSchema } from './testing';
 import * as Type from './Type';
 
 describe('Type', () => {
-  describe('Type.Obj', () => {
+  describe('Obj.Unknown schema', () => {
     test('has SchemaKindId for schema type checking', ({ expect }) => {
       // Type.isObjectSchema uses SchemaKindId to check if a schema is an object schema.
-      expect(Type.isObjectSchema(Type.Obj)).toBe(true);
+      expect(Type.isObjectSchema(Obj.Unknown)).toBe(true);
       expect(Type.isObjectSchema(TestSchema.Person)).toBe(true);
-      expect(Type.isObjectSchema(Type.Relation)).toBe(false);
+      expect(Type.isObjectSchema(Relation.Unknown)).toBe(false);
     });
 
     test('Schema.is validates structural compatibility only', ({ expect }) => {
       // Schema.is does structural validation (has id field).
       // It accepts both ECHO objects and plain objects with compatible structure.
-      expect(Schema.is(Type.Obj)({ id: 'plain-object' })).toBe(true);
+      expect(Schema.is(Obj.Unknown)({ id: 'plain-object' })).toBe(true);
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-      expect(Schema.is(Type.Obj)(obj)).toBe(true);
+      expect(Schema.is(Obj.Unknown)(obj)).toBe(true);
     });
   });
 
-  describe('Type.Relation', () => {
+  describe('Relation.Unknown schema', () => {
     test('has SchemaKindId for schema type checking', ({ expect }) => {
       // Type.isRelationSchema uses SchemaKindId to check if a schema is a relation schema.
-      expect(Type.isRelationSchema(Type.Relation)).toBe(true);
+      expect(Type.isRelationSchema(Relation.Unknown)).toBe(true);
       expect(Type.isRelationSchema(TestSchema.HasManager)).toBe(true);
-      expect(Type.isRelationSchema(Type.Obj)).toBe(false);
+      expect(Type.isRelationSchema(Obj.Unknown)).toBe(false);
     });
 
     test('Schema.is validates structural compatibility only', ({ expect }) => {
       // Schema.is does structural validation (has id field).
       // It accepts both ECHO relations and plain objects with compatible structure.
-      expect(Schema.is(Type.Relation)({ id: 'plain-object' })).toBe(true);
+      expect(Schema.is(Relation.Unknown)({ id: 'plain-object' })).toBe(true);
       const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
       const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
       const rel = Relation.make(TestSchema.HasManager, {
         [Relation.Source]: obj1,
         [Relation.Target]: obj2,
       });
-      expect(Schema.is(Type.Relation)(rel)).toBe(true);
+      expect(Schema.is(Relation.Unknown)(rel)).toBe(true);
     });
   });
 });

package/src/Type.ts

@@ -2,50 +2,30 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
+// @import-as-namespace
+
+import type * as Schema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
-import { type DXN, type ObjectId } from '@dxos/keys';
+import { type DXN } from '@dxos/keys';
 import { type ToMutable } from '@dxos/util';
 
-import type * as Entity$ from './Entity';
-import {
-  ANY_OBJECT_TYPENAME,
-  ANY_OBJECT_VERSION,
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
-  type AnyEntity,
-  type AnyProperties,
-  EchoObjectSchema,
-  EchoRelationSchema,
-  type EchoRelationSchemaOptions,
-  EchoSchema,
-  EntityKind,
-  PersistentSchema,
-  Ref as Ref$,
-  type RefFn,
-  type RefSchema,
-  SchemaKindId,
-  type TypeAnnotation,
-  type TypeMeta,
-  getSchemaDXN,
-  getSchemaTypename,
-  getSchemaVersion,
-  getTypeAnnotation,
-  isMutable as isMutable$,
-  toEffectSchema,
-  toJsonSchema,
-} from './internal';
-import type * as Relation$ from './Relation';
+import type * as Entity from './Entity';
+import * as typeInternal from './internal/Type';
+import * as internal from './internal';
+import type * as ObjModule from './Obj';
+import type * as RelationModule from './Relation';
 
-// TODO(burdon): Remove toEffectSchema, toJsonSchema (moved to JsonSchema export).
-export { toEffectSchema, toJsonSchema };
+/**
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
+ */
+export const RuntimeType = typeInternal.EchoSchema;
 
 /**
- * Returns all properties of an object or relation except for the id and kind.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;
+export type RuntimeType = typeInternal.EchoSchema;
 
 //
 // Internal types (not exported)
@@ -55,83 +35,14 @@ export type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Sour
  * Type that marks a schema as an ECHO schema.
  * The value indicates the entity kind (Object or Relation).
  */
-type EchoSchemaKind<K extends EntityKind = EntityKind> = {
-  readonly [SchemaKindId]: K;
+type EchoSchemaKind<K extends internal.EntityKind = internal.EntityKind> = {
+  readonly [internal.SchemaKindId]: K;
 };
 
-/**
- * JSON-encoded properties for objects.
- */
-interface ObjJsonProps {
-  id: string;
-}
-
-/**
- * JSON-encoded properties for relations.
- */
-interface RelationJsonProps {
-  id: string;
-  [ATTR_RELATION_SOURCE]: string;
-  [ATTR_RELATION_TARGET]: string;
-}
-
 //
 // Obj - Runtime schema for any ECHO object
 //
 
-// Internal type for the Obj schema constant.
-// NOTE: The `any` in the type intersection is intentional - it makes this type bidirectionally
-//   assignable with specific object types (e.g., Type.Obj can be assigned to/from Meeting.Meeting).
-//   This is needed because operation schemas erase type information.
-// TODO(wittjosiah): Consider alternatives to the `any` intersection hack:
-//   - Generic operation schemas that preserve input type in output
-//   - Branded types that specific schemas also carry
-//   - Accept the limitation and require explicit type narrowing at call sites
-type ObjSchemaType = Schema.Schema<
-  any & AnyEntity & Entity$.OfKind<typeof Entity$.Kind.Object> & AnyProperties,
-  { id: string } & AnyProperties
-> &
-  EchoSchemaKind<EntityKind.Object> &
-  TypeMeta;
-
-// Internal schema definition.
-// NOTE: The EchoObjectSchema annotation is required for Type.Ref(Type.Obj) to work.
-//   The typename/version only satisfy ECHO schema machinery for reference targets.
-const ObjSchema = Schema.Struct({
-  id: Schema.String,
-}).pipe(
-  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
-  EchoObjectSchema({ typename: ANY_OBJECT_TYPENAME, version: ANY_OBJECT_VERSION }),
-);
-
-/**
- * Runtime Effect schema for any ECHO object.
- * Use for validation, parsing, or as a reference target for collections.
- *
- * NOTE: `Schema.is(Type.Obj)` does STRUCTURAL validation only (checks for `id` field).
- * Use `Obj.isObject()` for proper ECHO instance type guards that check the KindId brand.
- *
- * @example
- * ```ts
- * // Structural type guard (accepts any object with id field)
- * if (Schema.is(Type.Obj)(unknownValue)) { ... }
- *
- * // ECHO instance type guard (checks KindId brand)
- * if (Obj.isObject(unknownValue)) { ... }
- *
- * // Reference to any object type
- * const Collection = Schema.Struct({
- *   objects: Schema.Array(Type.Ref(Type.Obj)),
- * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));
- * ```
- */
-// TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.
-//   Effect Schema normalizes proxy objects to plain objects before calling filter predicates.
-//   Possible approaches: custom Schema.declare, AST manipulation, or upstream contribution.
-export const Obj: ObjSchemaType = Object.assign(ObjSchema, {
-  [SchemaKindId]: (ObjSchema as any)[SchemaKindId],
-}) as unknown as ObjSchemaType;
-
 /**
  * TypeScript type for an ECHO object schema.
  * `T` is the instance type produced by the schema.
@@ -147,13 +58,14 @@ export const Obj: ObjSchemaType = Object.assign(ObjSchema, {
  * Object.keys(PersonSchema.fields); // ['name']
  * ```
  */
-export interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
-  extends TypeMeta,
-    EchoSchemaKind<EntityKind.Object>,
+export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Object>,
     Schema.AnnotableClass<
       Obj<T, Fields>,
-      Entity$.OfKind<typeof Entity$.Kind.Object> & T,
-      Schema.Simplify<ObjJsonProps & ToMutable<T>>,
+      Entity.OfKind<typeof Entity.Kind.Object> & T,
+      Schema.Simplify<ObjModule.BaseObjJson & ToMutable<T>>,
       never
     > {
   /**
@@ -174,13 +86,11 @@ type ObjectSchemaBase = Schema.Schema.AnyNoContext & {
   readonly version: string;
 };
 
-export namespace Obj {
-  /**
-   * Type that represents any ECHO object schema.
-   * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
-   */
-  export type Any = ObjectSchemaBase;
-}
+/**
+ * Type that represents any ECHO object schema.
+ * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
+ */
+export type AnyObj = ObjectSchemaBase;
 
 /**
  * Factory function to create an ECHO object schema.
@@ -190,88 +100,35 @@ export namespace Obj {
  * ```ts
  * const Person = Schema.Struct({
  *   name: Schema.String,
- * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));
+ * }).pipe(Type.object({ typename: 'com.example.type.person', version: '0.1.0' }));
  * ```
  */
 export const object: {
-  (opts: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
-} = EchoObjectSchema as any;
+  (opts: internal.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
+} = internal.EchoObjectSchema as any;
 
 //
 // PersistentType (Schema stored in database)
 //
 
-export const PersistentType: Obj<PersistentSchema> = PersistentSchema as any;
+export const PersistentType: Obj<typeInternal.PersistentSchema> = typeInternal.PersistentSchema as any;
 
 export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
-export { EchoSchema as RuntimeType };
-
-//
-// Relation - Runtime schema for any ECHO relation
-//
-
-// Internal type for the Relation schema constant.
-type RelationSchemaType = Schema.Schema<
-  { id: ObjectId } & Record<string, unknown>,
-  { id: string } & Record<string, unknown>
-> &
-  EchoSchemaKind<EntityKind.Relation> &
-  TypeMeta;
-
-// Internal schema definition.
-// NOTE: The EchoRelationSchema annotation is required for Type.Ref(Type.Relation) to work.
-//   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.
-const RelationSchema = Schema.Struct({
-  id: Schema.String,
-}).pipe(
-  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
-  EchoRelationSchema({
-    typename: 'dxos.org/schema/AnyRelation',
-    version: '0.0.0',
-    source: ObjSchema,
-    target: ObjSchema,
-  }),
-);
-
-/**
- * Runtime Effect schema for any ECHO relation.
- * Use for validation, parsing, or as a reference target for collections.
- * A relation has `id`, source, and target fields plus any additional properties.
- *
- * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).
- * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.
- *
- * @example
- * ```ts
- * // Structural type guard (accepts any object with id field)
- * if (Schema.is(Type.Relation)(unknownValue)) { ... }
- *
- * // ECHO instance type guard (checks KindId brand)
- * if (Relation.isRelation(unknownValue)) { ... }
- * ```
- */
-export const Relation: RelationSchemaType = Object.assign(RelationSchema, {
-  [SchemaKindId]: (RelationSchema as any)[SchemaKindId],
-}) as unknown as RelationSchemaType;
-
 /**
  * TypeScript type for an ECHO relation schema.
  * `T` is the instance type produced by the schema (excluding source/target).
  * `Source` and `Target` are the endpoint types.
  * `Fields` is the optional struct fields type for introspection.
  */
-export interface Relation<
-  T = any,
-  Source = any,
-  Target = any,
-  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
-> extends TypeMeta,
-    EchoSchemaKind<EntityKind.Relation>,
+export interface Relation<T, Source, Target, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Relation>,
     Schema.AnnotableClass<
       Relation<T, Source, Target, Fields>,
-      Entity$.OfKind<typeof Entity$.Kind.Relation> & Relation.Endpoints<Source, Target> & T,
-      Schema.Simplify<RelationJsonProps & ToMutable<T>>,
+      Entity.OfKind<typeof Entity.Kind.Relation> & RelationModule.Endpoints<Source, Target> & T,
+      Schema.Simplify<RelationModule.BaseRelationJson & ToMutable<T>>,
       never
     > {
   /**
@@ -292,28 +149,11 @@ type RelationSchemaBase = Schema.Schema.AnyNoContext & {
   readonly version: string;
 };
 
-export namespace Relation {
-  /**
-   * Type that represents any ECHO relation schema.
-   * Accepts static schemas (Type.relation()).
-   */
-  export type Any = RelationSchemaBase;
-
-  /**
-   * Get relation source type.
-   */
-  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;
-
-  /**
-   * Get relation target type.
-   */
-  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;
-
-  export type Endpoints<Source, Target> = {
-    [Relation$.Source]: Source;
-    [Relation$.Target]: Target;
-  };
-}
+/**
+ * Type that represents any ECHO relation schema.
+ * Accepts static schemas (Type.relation()).
+ */
+export type AnyRelation = RelationSchemaBase;
 
 /**
  * Factory function to create an ECHO relation schema.
@@ -324,7 +164,7 @@ export namespace Relation {
  * const WorksFor = Schema.Struct({
  *   role: Schema.String,
  * }).pipe(Type.relation({
- *   typename: 'example.com/type/WorksFor',
+ *   typename: 'com.example.type.works-for',
  *   version: '0.1.0',
  *   source: Person,
  *   target: Company,
@@ -333,112 +173,39 @@ export namespace Relation {
  */
 export const relation: {
   <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(
-    opts: EchoRelationSchemaOptions<SourceSchema, TargetSchema>,
+    opts: internal.EchoRelationSchemaOptions<SourceSchema, TargetSchema>,
   ): <Self extends Schema.Schema.Any>(
     self: Self,
   ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;
-} = EchoRelationSchema as any;
-
-//
-// Entity - Entity schema types (union of Object | Relation)
-//
+} = internal.EchoRelationSchema as any;
 
-export namespace Entity {
-  /**
-   * Runtime Effect schema for any ECHO entity (object or relation).
-   * Use for validation, parsing, or type guards on unknown values.
-   *
-   * @example
-   * ```ts
-   * if (Schema.is(Type.Entity.Any)(unknownValue)) {
-   *   // unknownValue is an ECHO entity
-   * }
-   * ```
-   */
-  export const Any: Schema.Schema<
-    { id: ObjectId } & Record<string, unknown>,
-    { id: string } & Record<string, unknown>
-  > = Schema.Union(Obj, Relation);
-
-  /**
-   * Type alias for any ECHO entity schema (object or relation).
-   * Use this in type annotations for schema parameters.
-   */
-  export type Any = Obj.Any | Relation.Any;
-}
+/**
+ * Type alias for any ECHO entity schema (object or relation).
+ * Use this in type annotations for schema parameters.
+ */
+export type AnyEntity = AnyObj | AnyRelation;
 
 /**
  * Type guard to check if a schema is an object schema.
  * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.
  */
-export const isObjectSchema = (schema: Entity.Any): schema is Obj.Any => {
-  return (schema as any)[SchemaKindId] === EntityKind.Object;
+export const isObjectSchema = (schema: AnyEntity): schema is AnyObj => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Object;
 };
 
 /**
  * Type guard to check if a schema is a relation schema.
  * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.
  */
-export const isRelationSchema = (schema: Entity.Any): schema is Relation.Any => {
-  return (schema as any)[SchemaKindId] === EntityKind.Relation;
+export const isRelationSchema = (schema: AnyEntity): schema is AnyRelation => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Relation;
 };
 
-//
-// Ref
-//
-// NOTE: `Type.Ref` vs `Ref.Ref`:
-// - `Type.Ref<T>` is the SCHEMA type - a schema that produces `Ref.Ref<T>` instances.
-// - `Ref.Ref<T>` is the INSTANCE type - the actual runtime ref object.
-//
-// Example:
-//   const taskRef: Ref.Ref<Task> = Ref.make(task);  // Instance
-//   const schema: Type.Ref<Task> = Type.Ref(Task);  // Schema
-//
-
-/**
- * Return type of the `Ref` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
- */
-export interface ref<TargetSchema extends Schema.Schema.Any> extends RefSchema<Schema.Schema.Type<TargetSchema>> {}
-
-/**
- * Factory function to create a Ref schema for the given target schema.
- * Use this in schema definitions to declare reference fields.
- *
- * @example
- * ```ts
- * const Task = Schema.Struct({
- *   assignee: Type.Ref(Person),  // Creates a Ref schema
- * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));
- * ```
- */
-export const Ref: RefFn = Ref$;
-
 /**
- * TypeScript type for a Ref schema.
- * This is the type of the SCHEMA itself, not the runtime ref instance.
- * For the instance type, use `Ref.Ref<T>` from the Ref module.
- *
- * @example
- * ```ts
- * // Schema type annotation (rarely needed, usually inferred):
- * const refSchema: Type.Ref<Task> = Type.Ref(Task);
- *
- * // Instance type annotation (use Ref.Ref instead):
- * const refInstance: Ref.Ref<Task> = Ref.make(task);
- * ```
+ * Type that represents any Ref schema (with unknown target type).
+ * This is a schema type, not an instance type.
  */
-export interface Ref<T> extends Schema.SchemaClass<Ref$<T>, EncodedReference> {}
-
-export namespace Ref {
-  /**
-   * Type that represents any Ref schema (with unknown target type).
-   * This is a schema type, not an instance type.
-   */
-  export type Any = Schema.Schema<Ref$<any>, EncodedReference>;
-}
+export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
 
 //
 // Schema utility functions
@@ -447,19 +214,19 @@ export namespace Ref {
 /**
  * Gets the full DXN of the schema.
  * Will include the version if it's a `type` DXN.
- * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:com.example.type.person:0.1.0"
  * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
  */
-export const getDXN = (schema: Entity.Any): DXN | undefined => {
-  return getSchemaDXN(schema);
+export const getDXN = (schema: AnyEntity): DXN | undefined => {
+  return internal.getSchemaDXN(schema);
 };
 
 /**
  * @param schema - Schema to get the typename from.
- * @returns The typename of the schema. Example: `example.com/type/Person`.
+ * @returns The typename of the schema. Example: `com.example.type.person`.
  */
-export const getTypename = (schema: Entity.Any): string => {
-  const typename = getSchemaTypename(schema);
+export const getTypename = (schema: AnyEntity): string => {
+  const typename = internal.getSchemaTypename(schema);
   invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');
   return typename;
 };
@@ -468,8 +235,8 @@ export const getTypename = (schema: Entity.Any): string => {
  * Gets the version of the schema.
  * @example 0.1.0
  */
-export const getVersion = (schema: Entity.Any): string => {
-  const version = getSchemaVersion(schema);
+export const getVersion = (schema: AnyEntity): string => {
+  const version = internal.getSchemaVersion(schema);
   invariant(typeof version === 'string' && version.match(/^\d+\.\d+\.\d+$/), 'Invalid version');
   return version;
 };
@@ -477,16 +244,16 @@ export const getVersion = (schema: Entity.Any): string => {
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = isMutable$;
+export const isMutable = typeInternal.isMutable;
 
 /**
  * ECHO type metadata.
  */
-export type Meta = TypeAnnotation;
+export type Meta = internal.TypeAnnotation;
 
 /**
  * Gets the meta data of the schema.
  */
-export const getMeta = (schema: Entity.Any): Meta | undefined => {
-  return getTypeAnnotation(schema);
+export const getMeta = (schema: AnyEntity): Meta | undefined => {
+  return internal.getTypeAnnotation(schema);
 };

package/src/View.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { JsonPath } from '@dxos/effect';
+import { PublicKey } from '@dxos/keys';
+
+import * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Query from './Query';
+import * as Type from './Type';
+import * as Annotation from './Annotation';
+
+/**
+ * Stored field metadata (e.g., for UX).
+ */
+export const FieldSchema = Schema.Struct({
+  id: Schema.String,
+  path: JsonPath,
+  visible: Schema.optional(Schema.Boolean),
+
+  // TODO(wittjosiah): Presentation-specific?
+  referencePath: Schema.optional(JsonPath),
+});
+
+export type FieldType = Schema.Schema.Type<typeof FieldSchema>;
+
+export const KeyValueProps = Schema.Record({ key: Schema.String, value: Schema.Any });
+
+export const createFieldId = () => PublicKey.random().truncate();
+
+export const Projection = Schema.Struct({
+  /**
+   * Optional schema override used to customize the underlying schema.
+   */
+  schema: internal.JsonSchemaType.pipe(Schema.optional),
+
+  /**
+   * UX metadata associated with displayed fields (in table, form, etc.)
+   */
+  // TODO(wittjosiah): Should this just be an array of JsonPath?
+  fields: Schema.Array(FieldSchema),
+
+  /**
+   * The id for the field used to pivot the view.
+   * E.g., the field to use for kanban columns or the field to use for map coordinates.
+   */
+  pivotFieldId: Schema.String.pipe(Schema.optional),
+});
+
+export type Projection = Schema.Schema.Type<typeof Projection>;
+
+/**
+ * Views are generated or user-defined projections of a schema's properties.
+ * They are used to configure the visual representation of the data.
+ */
+const ViewSchema = Schema.Struct({
+  /**
+   * Query used to retrieve data.
+   * Can be a user-provided query grammar string or a query AST.
+   */
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String),
+    ast: QueryAST.Query,
+  }),
+
+  /**
+   * Projection of the data returned from the query.
+   */
+  projection: Projection,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.view',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
+);
+
+export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
+
+/**
+ * View instance type.
+ */
+// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
+//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
+//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
+//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export const View: Type.Obj<View> = ViewSchema as any;
+
+export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {
+  return Obj.make(View, {
+    query: { ast: Query.select(Filter.nothing()).ast },
+    projection: { fields: [] },
+    ...props,
+  });
+};