diff --git a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/ObjectTypeWithAllPropertyTypes.ts b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/ObjectTypeWithAllPropertyTypes.ts
index 1339c73bd..3ab39e9be 100644
--- a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/ObjectTypeWithAllPropertyTypes.ts
+++ b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/ObjectTypeWithAllPropertyTypes.ts
@@ -13,8 +13,12 @@ import type {
  * A type with all property types
  */
 export interface ObjectTypeWithAllPropertyTypes extends OntologyObject {
+  /** @deprecated please migrate to $apiName instead */
   readonly __apiName: 'ObjectTypeWithAllPropertyTypes';
+  /** @deprecated please migrate to $primaryKey instead */
   readonly __primaryKey: number;
+  readonly $apiName: 'ObjectTypeWithAllPropertyTypes';
+  readonly $primaryKey: number;
   readonly attachment: Attachment | undefined;
   readonly attachmentArray: Attachment[] | undefined;
   readonly boolean: boolean | undefined;
diff --git a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Person.ts b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Person.ts
index ff06ba6b6..c64fa04e9 100644
--- a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Person.ts
+++ b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Person.ts
@@ -6,8 +6,12 @@ import type { Todo } from './Todo';
  * A person
  */
 export interface Person extends OntologyObject {
+  /** @deprecated please migrate to $apiName instead */
   readonly __apiName: 'Person';
+  /** @deprecated please migrate to $primaryKey instead */
   readonly __primaryKey: string;
+  readonly $apiName: 'Person';
+  readonly $primaryKey: string;
   readonly email: string | undefined;
   readonly Todos: MultiLink<Todo>;
   readonly Friends: MultiLink<Person>;
diff --git a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Todo.ts b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Todo.ts
index 9d0d138e5..5f3aaa69c 100644
--- a/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Todo.ts
+++ b/examples-extra/one_dot_one/src/generatedNoCheck/ontology/objects/Todo.ts
@@ -6,8 +6,12 @@ import type { Person } from './Person';
  * Its a todo item.
  */
 export interface Todo extends OntologyObject {
+  /** @deprecated please migrate to $apiName instead */
   readonly __apiName: 'Todo';
+  /** @deprecated please migrate to $primaryKey instead */
   readonly __primaryKey: number;
+  readonly $apiName: 'Todo';
+  readonly $primaryKey: number;
   /**
    * The text of the todo
    */
diff --git a/examples-extra/todoapp/src/generatedNoCheck/ontology/objects/Todo.ts b/examples-extra/todoapp/src/generatedNoCheck/ontology/objects/Todo.ts
index c9b9b3a28..a153bd8e1 100644
--- a/examples-extra/todoapp/src/generatedNoCheck/ontology/objects/Todo.ts
+++ b/examples-extra/todoapp/src/generatedNoCheck/ontology/objects/Todo.ts
@@ -5,8 +5,12 @@ import type { OntologyObject } from '@osdk/legacy-client';
  * Its a todo item.
  */
 export interface Todo extends OntologyObject {
+  /** @deprecated please migrate to $apiName instead */
   readonly __apiName: 'Todo';
+  /** @deprecated please migrate to $primaryKey instead */
   readonly __primaryKey: string;
+  readonly $apiName: 'Todo';
+  readonly $primaryKey: string;
   readonly id: string | undefined;
   readonly isComplete: boolean | undefined;
   /**
diff --git a/examples-extra/todoapp/src/useTodos.tsx b/examples-extra/todoapp/src/useTodos.tsx
index 5e9c8ddaf..87a156bab 100644
--- a/examples-extra/todoapp/src/useTodos.tsx
+++ b/examples-extra/todoapp/src/useTodos.tsx
@@ -1,9 +1,9 @@
+import { ActionValidationError } from "@osdk/client";
 import { useCallback, useEffect } from "react";
 import useSWR from "swr";
 import { foundryClient, foundryClient2 } from "./foundryClient";
-import { isOk, ReturnEditsMode, type Result } from "./generatedNoCheck";
+import { isOk, type Result, ReturnEditsMode } from "./generatedNoCheck";
 import type { Todo } from "./generatedNoCheck/ontology/objects";
-import { ActionValidationError } from "@osdk/client";
 import * as MyOsdk from "./generatedNoCheck2";
 
 function orThrow<T, E>(result: Result<T, E>) {
@@ -18,7 +18,7 @@ export function useTodos() {
   const { data, isLoading, error, isValidating, mutate } = useSWR(
     "/todos",
     async () => orThrow(await foundryClient.ontology.objects.Todo.all()),
-    { keepPreviousData: true, revalidateOnFocus: false }
+    { keepPreviousData: true, revalidateOnFocus: false },
   );
 
   useEffect(() => {
@@ -36,7 +36,7 @@ export function useTodos() {
           } else {
             byApiNameByPK.set(
               object.$apiName,
-              new Map([[object.$primaryKey, object]])
+              new Map([[object.$primaryKey, object]]),
             );
           }
         }
@@ -44,7 +44,7 @@ export function useTodos() {
         // get the new version of an object that has changed, removing it from the list of updates
         const getUpdate = (
           apiName: (typeof objects)[0]["$apiName"],
-          primaryKey: (typeof objects)[0]["$primaryKey"]
+          primaryKey: (typeof objects)[0]["$primaryKey"],
         ) => {
           const byPk = byApiNameByPK.get(apiName);
           if (byPk) {
@@ -58,14 +58,13 @@ export function useTodos() {
 
         mutate((data) => {
           // update any Todos that we got a new version for
-          const updated =
-            data?.map((object) => {
-              const updateObject = getUpdate(
-                object.__apiName,
-                object.__primaryKey
-              );
-              return updateObject ?? object;
-            }) ?? [];
+          const updated = data?.map((object) => {
+            const updateObject = getUpdate(
+              object.__apiName,
+              object.__primaryKey,
+            );
+            return updateObject ?? object;
+          }) ?? [];
 
           // add any new Todos to the bottom
           for (const byPk of byApiNameByPK.values()) {
@@ -91,7 +90,7 @@ export function useTodos() {
   }, [mutate]);
 
   const toggleComplete = useCallback(
-    async function (todo: Todo) {
+    async function(todo: Todo) {
       const b = !todo.isComplete;
       await mutate(
         async () => {
@@ -111,8 +110,8 @@ export function useTodos() {
                   is_complete: b,
                   Todo: todo,
                 },
-                { returnEdits: ReturnEditsMode.ALL }
-              )
+                { returnEdits: ReturnEditsMode.ALL },
+              ),
             );
           }
 
@@ -121,10 +120,10 @@ export function useTodos() {
         {
           optimisticData: updateTodo.bind(undefined, todo.id!, b),
           rollbackOnError: true,
-        }
+        },
       );
     },
-    [mutate]
+    [mutate],
   );
 
   const createTodoMutator = useCallback(
@@ -151,7 +150,7 @@ export function useTodos() {
                     if (constraint.type === "stringLength") {
                       if (constraint.gte != null && constraint.lte != null) {
                         setError?.(
-                          `Todo must be between ${constraint.gte}-${constraint.lte} characters`
+                          `Todo must be between ${constraint.gte}-${constraint.lte} characters`,
                         );
                       }
                     }
@@ -169,11 +168,11 @@ export function useTodos() {
           optimisticData: (todos = []) => [...todos, createFauxTodo(title)],
           rollbackOnError: true,
           throwOnError: true,
-        }
+        },
       );
       return undefined;
     },
-    [mutate]
+    [mutate],
   );
 
   return {
@@ -194,13 +193,16 @@ function createFauxTodo(title: string): Todo {
     __primaryKey: title,
     __apiName: "Todo",
     __rid: "",
+    $primaryKey: title,
+    $apiName: "Todo",
+    $rid: "",
   };
 }
 
 function updateTodo(
   id: string,
   isComplete: boolean,
-  todos: Todo[] | undefined
+  todos: Todo[] | undefined,
 ) {
   return updateOne(todos, id, (todo) => ({ ...todo, isComplete })) ?? [];
 }
@@ -208,7 +210,7 @@ function updateTodo(
 function updateOne<T extends { __primaryKey: Q }, Q>(
   things: T[] | undefined,
   primaryKey: Q,
-  update: (thing: T) => T
+  update: (thing: T) => T,
 ) {
   return things?.map((thing) => {
     if (thing.__primaryKey === primaryKey) {
diff --git a/packages/generator/changelog/@unreleased/pr-142.v2.yml b/packages/generator/changelog/@unreleased/pr-142.v2.yml
new file mode 100644
index 000000000..e2ddeb918
--- /dev/null
+++ b/packages/generator/changelog/@unreleased/pr-142.v2.yml
@@ -0,0 +1,5 @@
+type: deprecation
+deprecation:
+  description: Deprecate __apiName, __rid, and __primaryKey
+  links:
+  - https://github.com/palantir/osdk-ts/pull/142
diff --git a/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.test.ts b/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.test.ts
index 858fd5d58..fa8d628f6 100644
--- a/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.test.ts
+++ b/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.test.ts
@@ -34,8 +34,12 @@ describe("wireObjectTypeV2ToObjectInterfaceStringV1", () => {
        * Its a todo item.
        */
       export interface Todo extends OntologyObject {
+        /** @deprecated please migrate to \$apiName instead */
         readonly __apiName: 'Todo';
+        /** @deprecated please migrate to \$primaryKey instead */
         readonly __primaryKey: number;
+        readonly $apiName: 'Todo';
+        readonly $primaryKey: number;
         /**
          * The text of the todo
          */
@@ -78,8 +82,12 @@ describe("wireObjectTypeV2ToObjectInterfaceStringV1", () => {
       "import type { OntologyObject, SingleLink } from '@osdk/legacy-client';
 
       export interface Todo extends OntologyObject {
+        /** @deprecated please migrate to \$apiName instead */
         readonly __apiName: 'Todo';
+        /** @deprecated please migrate to \$primaryKey instead */
         readonly __primaryKey: number;
+        readonly $apiName: 'Todo';
+        readonly $primaryKey: number;
         readonly break: number | undefined;
         /** @deprecated please migrate to 'break' instead */
         readonly break_: number | undefined;
diff --git a/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.ts b/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.ts
index c4e8fa267..fb8389792 100644
--- a/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.ts
+++ b/packages/generator/src/v1.1/wireObjectTypeV2ToV1ObjectInterfaceString.ts
@@ -38,13 +38,22 @@ ${
 
   ${getDescriptionIfPresent(objectTypeWithLinks.objectType.description)}
   export interface ${objectTypeWithLinks.objectType.apiName} extends OntologyObject {
+  /** \@deprecated please migrate to \$apiName instead */
   readonly __apiName: "${objectTypeWithLinks.objectType.apiName}";
+  /** \@deprecated please migrate to \$primaryKey instead */
   readonly __primaryKey: ${
     wirePropertyTypeV2ToTypeScriptType(
       objectTypeWithLinks.objectType
         .properties[objectTypeWithLinks.objectType.primaryKey].dataType,
     )
   };
+  readonly \$apiName: "${objectTypeWithLinks.objectType.apiName}";
+  readonly \$primaryKey: ${
+    wirePropertyTypeV2ToTypeScriptType(
+      objectTypeWithLinks.objectType
+        .properties[objectTypeWithLinks.objectType.primaryKey].dataType,
+    )
+  };
 ${
     Object.entries(objectTypeWithLinks.objectType.properties).sort((a, b) =>
       a[0].localeCompare(b[0])
diff --git a/packages/legacy-client/changelog/@unreleased/pr-142.v2.yml b/packages/legacy-client/changelog/@unreleased/pr-142.v2.yml
new file mode 100644
index 000000000..e2ddeb918
--- /dev/null
+++ b/packages/legacy-client/changelog/@unreleased/pr-142.v2.yml
@@ -0,0 +1,5 @@
+type: deprecation
+deprecation:
+  description: Deprecate __apiName, __rid, and __primaryKey
+  links:
+  - https://github.com/palantir/osdk-ts/pull/142
diff --git a/packages/legacy-client/src/client/baseTypes/OntologyObject.ts b/packages/legacy-client/src/client/baseTypes/OntologyObject.ts
index e8c68068a..0fd88f2b1 100644
--- a/packages/legacy-client/src/client/baseTypes/OntologyObject.ts
+++ b/packages/legacy-client/src/client/baseTypes/OntologyObject.ts
@@ -20,12 +20,19 @@ export interface OntologyObject<
   T extends string = string,
   P extends NonNullable<ParameterValue> = NonNullable<ParameterValue>,
 > {
+  /** @deprecated use $rid */
   __rid: string;
+  /** @deprecated use $apiName */
   __apiName: T;
+  /** @deprecated use $primaryKey */
   __primaryKey: P;
+  $rid: string;
+  $apiName: T;
+  $primaryKey: P;
 }
 
 export function isOntologyObject(obj: any): obj is OntologyObject {
-  return obj && typeof obj === "object" && typeof obj.__apiName === "string"
-    && "__primaryKey" in obj;
+  return obj && typeof obj === "object" && ((typeof obj.__apiName === "string"
+    && "__primaryKey" in obj) || (typeof obj.$apiName === "string"
+      && "$primaryKey" in obj));
 }
diff --git a/packages/legacy-client/src/client/baseTypes/objectset/FilteredPropertiesTerminalOperations.ts b/packages/legacy-client/src/client/baseTypes/objectset/FilteredPropertiesTerminalOperations.ts
index dcff99e54..8d7325102 100644
--- a/packages/legacy-client/src/client/baseTypes/objectset/FilteredPropertiesTerminalOperations.ts
+++ b/packages/legacy-client/src/client/baseTypes/objectset/FilteredPropertiesTerminalOperations.ts
@@ -25,7 +25,12 @@ export type FilteredPropertiesTerminalOperations<
 > = {
   all(): Promise<
     Result<
-      Array<Pick<T, V[number] | "__apiName" | "__primaryKey">>,
+      Array<
+        Pick<
+          T,
+          V[number] | "$apiName" | "$primaryKey" | "__apiName" | "__primaryKey"
+        >
+      >,
       LoadObjectSetError
     >
   >;
@@ -34,7 +39,12 @@ export type FilteredPropertiesTerminalOperations<
     pageToken?: string;
   }): Promise<
     Result<
-      Page<Pick<T, V[number] | "__apiName" | "__primaryKey">>,
+      Page<
+        Pick<
+          T,
+          V[number] | "$apiName" | "$primaryKey" | "__apiName" | "__primaryKey"
+        >
+      >,
       LoadObjectSetError
     >
   >;
@@ -45,8 +55,14 @@ export type FilteredPropertiesTerminalOperationsWithGet<
   V extends Array<keyof T>,
 > = FilteredPropertiesTerminalOperations<T, V> & {
   get(
-    primaryKey: T["__primaryKey"],
+    primaryKey: T["$primaryKey"],
   ): Promise<
-    Result<Pick<T, V[number] | "__apiName" | "__primaryKey">, GetObjectError>
+    Result<
+      Pick<
+        T,
+        V[number] | "$apiName" | "$primaryKey" | "__apiName" | "__primaryKey"
+      >,
+      GetObjectError
+    >
   >;
 };
diff --git a/packages/legacy-client/src/client/interfaces/baseObjectSet.ts b/packages/legacy-client/src/client/interfaces/baseObjectSet.ts
index 857f30c49..2ec6af3f9 100644
--- a/packages/legacy-client/src/client/interfaces/baseObjectSet.ts
+++ b/packages/legacy-client/src/client/interfaces/baseObjectSet.ts
@@ -29,13 +29,13 @@ export type BaseObjectSet<O extends OntologyObject> =
   & ObjectSet<O>;
 
 export type BaseObjectSetOperations<O extends OntologyObject> = {
-  apiName: O["__apiName"];
+  apiName: O["$apiName"];
 
   description: string;
 
   properties: Properties<O>;
 
-  get(primaryKey: O["__primaryKey"]): Promise<Result<O, GetObjectError>>;
+  get(primaryKey: O["$primaryKey"]): Promise<Result<O, GetObjectError>>;
 
   select<T extends keyof SelectableProperties<O>>(
     properties: readonly T[],
diff --git a/packages/legacy-client/src/client/interfaces/utils/OmitProperties.ts b/packages/legacy-client/src/client/interfaces/utils/OmitProperties.ts
index e078c9dd6..764cd54cb 100644
--- a/packages/legacy-client/src/client/interfaces/utils/OmitProperties.ts
+++ b/packages/legacy-client/src/client/interfaces/utils/OmitProperties.ts
@@ -17,7 +17,17 @@
 import type { IsLink } from "./IsLink";
 
 export declare type OmitMetadataProperties<T> = {
-  [K in keyof Omit<T, "__apiName" | "__rid" | "__primaryKey">]: T[K];
+  [
+    K in keyof Omit<
+      T,
+      | "__apiName"
+      | "__rid"
+      | "__primaryKey"
+      | "$apiName"
+      | "$rid"
+      | "$primaryKey"
+    >
+  ]: T[K];
 };
 
 export declare type OmitLinksProperties<T> = {
diff --git a/packages/legacy-client/src/client/net/getObject.ts b/packages/legacy-client/src/client/net/getObject.ts
index a9e0c871c..0d2fc8f13 100644
--- a/packages/legacy-client/src/client/net/getObject.ts
+++ b/packages/legacy-client/src/client/net/getObject.ts
@@ -27,9 +27,9 @@ import { wrapResult } from "./util/wrapResult";
 import type { WireOntologyObjectV2 } from "./WireOntologyObjectV2";
 
 export async function getObject<T extends OntologyObject>(
-  client: ClientContext<OntologyDefinition<T["__apiName"]>>,
+  client: ClientContext<OntologyDefinition<T["$apiName"]>>,
   objectApiName: string,
-  primaryKey: T["__primaryKey"],
+  primaryKey: T["$primaryKey"],
   selectedProperties: ReadonlyArray<keyof T> = [],
 ): Promise<Result<T, GetObjectError>> {
   return wrapResult(async () => {
@@ -41,7 +41,7 @@ export async function getObject<T extends OntologyObject>(
       {
         select: selectedProperties.map(x => x.toString()),
       },
-    ) as WireOntologyObjectV2<T["__apiName"]>;
+    ) as WireOntologyObjectV2<T["$apiName"]>;
 
     return convertWireToOsdkObject(
       client,
diff --git a/packages/legacy-client/src/client/objectSets/OsdkObjectSet.ts b/packages/legacy-client/src/client/objectSets/OsdkObjectSet.ts
index f28d11ad8..f7dc4b2d8 100644
--- a/packages/legacy-client/src/client/objectSets/OsdkObjectSet.ts
+++ b/packages/legacy-client/src/client/objectSets/OsdkObjectSet.ts
@@ -162,7 +162,7 @@ export function createBaseOsdkObjectSet<
   };
 
   const objectSet: BaseObjectSetOperations<OsdkLegacyObjectFrom<O, K>> = {
-    apiName: apiName as string as OsdkLegacyObjectFrom<O, K>["__apiName"],
+    apiName: apiName as string as OsdkLegacyObjectFrom<O, K>["$apiName"],
 
     description: client.ontology.objects[apiName].description ?? "",
 
diff --git a/packages/legacy-client/src/util/test/TaskObject.ts b/packages/legacy-client/src/util/test/TaskObject.ts
index c0f58c07c..b1c594a5e 100644
--- a/packages/legacy-client/src/util/test/TaskObject.ts
+++ b/packages/legacy-client/src/util/test/TaskObject.ts
@@ -20,6 +20,9 @@ import type { Todo } from "./TodoObject";
 export interface Task extends OntologyObject {
   readonly __apiName: "Task";
   readonly __primaryKey: number;
+  readonly $apiName: "Task";
+  readonly $primaryKey: number;
   readonly id: number | undefined;
+  readonly $rid: string;
   readonly linkedTodos: MultiLink<Todo>;
 }
diff --git a/packages/legacy-client/src/util/test/TodoObject.ts b/packages/legacy-client/src/util/test/TodoObject.ts
index 2f92dd9e2..9c902e8ac 100644
--- a/packages/legacy-client/src/util/test/TodoObject.ts
+++ b/packages/legacy-client/src/util/test/TodoObject.ts
@@ -23,7 +23,10 @@ import type { Task } from "./TaskObject";
 export interface Todo extends OntologyObject {
   readonly __apiName: "Todo";
   readonly __primaryKey: string;
+  readonly $apiName: "Todo";
+  readonly $primaryKey: string;
   readonly id: string | undefined;
+  readonly $rid: string;
   /**
    * The text of the todo
    */