finos · rafaelbey · Aug 3, 2026
@@ -0,0 +1,5 @@
+---
+'@finos/legend-graph': patch
+---
+
+Support engine's multi-line (`'''...'''`) string literal protocol changes: `V1_CString` (and its raw value specification counterpart) now carries an optional `multiLine` flag, and a tagged value's `value` accepts both the plain string and the `{ _type: 'string', multiLine: true, value: '...' }` wire shapes.
@@ -29,6 +29,7 @@ import {
   TEST_DATA__FunctionRoundtrip,
   TEST_DATA__MeasureRoundtrip,
   TEST_DATA__ClassWithComplexConstraint,
+  TEST_DATA__ClassWithMultiLineTaggedValue,
   TEST_DATA__OverloadedFunctionsRoundtrip,
 } from './roundtripTestData/TEST_DATA__DomainRoundtrip.js';
 import {
@@ -123,6 +124,10 @@ describe(unitTest('Domain import resolution roundtrip'), () => {
   test.each([
     ['Class', TEST_DATA__ClassRoundtrip],
     ['Class with complex constraint', TEST_DATA__ClassWithComplexConstraint],
+    [
+      'Class with multi-line tagged value',
+      TEST_DATA__ClassWithMultiLineTaggedValue,
+    ],
     ['Enumeration', TEST_DATA__EnumerationRoundtrip],
     ['Association', TEST_DATA__AssociationRoundtrip],
     ['Function', TEST_DATA__FunctionRoundtrip],

@@ -1166,3 +1166,52 @@ export const TEST_DATA__OverloadedFunctionsRoundtrip = [
       'meta::pure::metamodel::function::ConcreteFunctionDefinition',
   },
 ];
+
+export const TEST_DATA__ClassWithMultiLineTaggedValue = [
+  {
+    path: 'test::A',
+    content: {
+      _type: 'class',
+      name: 'A',
+      package: 'test',
+      taggedValues: [
+        {
+          tag: {
+            profile: 'test::tProf',
+            value: 'doc',
+          },
+          value: 'a single-line doc',
+        },
+        {
+          tag: {
+            profile: 'test::tProf',
+            value: 'todo',
+          },
+          value: {
+            _type: 'string',
+            multiLine: true,
+            value: 'line one\nline two',
+          },
+        },
+      ],
+    },
+    classifierPath: 'meta::pure::metamodel::type::Class',
+  },
+  {
+    path: 'test::tProf',
+    content: {
+      _type: 'profile',
+      name: 'tProf',
+      package: 'test',
+      tags: [
+        {
+          value: 'doc',
+        },
+        {
+          value: 'todo',
+        },
+      ],
+    },
+    classifierPath: 'meta::pure::metamodel::extension::Profile',
+  },
+];
@@ -170,6 +170,7 @@ export const observe_TaggedValue = skipObserved(
   (metamodel: TaggedValue): TaggedValue => {
     makeObservable(metamodel, {
       value: observable,
+      multiLine: observable,
       hashCode: computed,
     });
 

@@ -33,6 +33,7 @@ export const observe_RawPrimitiveInstanceValue = skipObserved(
   (metamodel: RawPrimitiveInstanceValue): RawPrimitiveInstanceValue => {
     makeObservable(metamodel, {
       value: observable,
+      multiLine: observable,
       hashCode: computed,
     });
 

@@ -94,6 +94,8 @@ const V1_observe_PrimitiveType = skipObserved(
   ) => {
     V1_observe_Abstract_ValueSpecification(metamodel);
 
+    // NOTE: `V1_CString.multiLine` is not observed here as `mobx` throws when annotating a property which does
+    // not exist on the instance, and this function covers all primitive types.
     makeObservable(metamodel, {
       value: observable,
     });

@@ -21,8 +21,21 @@ import type { V1_TagPtr } from '../../../model/packageableElements/domain/V1_Tag
 export class V1_TaggedValue implements Hashable {
   tag!: V1_TagPtr;
   value!: string;
+  /**
+   * Whether the value was authored as a multi-line (`'''...'''`) block.
+   * See https://github.com/finos/legend-engine/pull/5008
+   */
+  multiLine = false;
 
+  /**
+   * NOTE: must be kept in sync with `TaggedValue.hashCode`.
+   */
   get hashCode(): string {
-    return hashArray([CORE_HASH_STRUCTURE.TAGGED_VALUE, this.tag, this.value]);
+    return hashArray([
+      CORE_HASH_STRUCTURE.TAGGED_VALUE,
+      this.tag,
+      this.value,
+      this.multiLine.toString(),
+    ]);
   }
 }
@@ -29,6 +29,11 @@ export class V1_RawPrimitiveInstanceValue
   readonly multiplicity = V1_Multiplicity.ONE;
   type!: string;
   value?: string | number | boolean | undefined;
+  /**
+   * Only meaningful when `type` is `String`: whether the literal was authored as a multi-line (`'''...'''`) block.
+   * See https://github.com/finos/legend-engine/pull/4998
+   */
+  multiLine = false;
 
   get hashCode(): string {
     return hashArray([

@@ -28,13 +28,22 @@ export class V1_CString
   implements Hashable
 {
   value!: string;
+  /**
+   * Whether the literal was authored as a multi-line (`'''...'''`) block.
+   * See https://github.com/finos/legend-engine/pull/4998
+   */
+  multiLine = false;
 
   accept_ValueSpecificationVisitor<T>(
     visitor: V1_ValueSpecificationVisitor<T>,
   ): T {
     return visitor.visit_CString(this);
   }
 
+  /**
+   * NOTE: `multiLine` is excluded here to keep this hash compatible with `PrimitiveInstanceValue.hashCode`,
+   * whose metamodel has no counterpart for the flag.
+   */
   override get hashCode(): string {
     return hashArray([
       CORE_HASH_STRUCTURE.PRIMITIVE_INSTANCE_VALUE,

@@ -215,6 +215,7 @@ export const V1_transformTaggedValue = (
 ): V1_TaggedValue => {
   const taggedValue = new V1_TaggedValue();
   taggedValue.value = element.value;
+  taggedValue.multiLine = element.multiLine;
   taggedValue.tag = new V1_TagPtr();
   taggedValue.tag.profile =
     element.tag.ownerReference.valueForSerialization ?? '';

@@ -76,6 +76,7 @@ export class V1_RawValueSpecificationTransformer
     const protocol = new V1_RawPrimitiveInstanceValue();
     protocol.type = rawValueSpecification.type.valueForSerialization ?? '';
     protocol.value = rawValueSpecification.value;
+    protocol.multiLine = rawValueSpecification.multiLine;
     return protocol;
   }
 }

@@ -57,9 +57,11 @@ export class V1_RawValueSpecificationBuilder
   visit_PrimitiveInstanceValue(
     valueSpecification: V1_RawPrimitiveInstanceValue,
   ): RawValueSpecification {
-    return new RawPrimitiveInstanceValue(
+    const metamodel = new RawPrimitiveInstanceValue(
       this.context.resolveType(valueSpecification.type),
       valueSpecification.value,
     );
+    metamodel.multiLine = valueSpecification.multiLine;
+    return metamodel;
   }
 }
@@ -79,10 +79,12 @@ export const V1_buildTaggedValue = (
   context: V1_GraphBuilderContext,
 ): TaggedValue | undefined => {
   assertNonNullable(taggedValue.tag, `Tagged value 'tag' field is missing`);
-  return new TaggedValue(
+  const metamodel = new TaggedValue(
     context.resolveTag(taggedValue.tag),
     taggedValue.value,
   );
+  metamodel.multiLine = taggedValue.multiLine;
+  return metamodel;
 };
 
 export const V1_buildConstraint = (

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) 2020-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test, expect, describe } from '@jest/globals';
+import { guaranteeType, type PlainObject } from '@finos/legend-shared';
+import { unitTest } from '@finos/legend-shared/test';
+import {
+  V1_deserializeRawValueSpecification,
+  V1_serializeRawValueSpecification,
+} from '../serializationHelpers/V1_RawValueSpecificationSerializationHelper.js';
+import {
+  TEST__buildGraphWithEntities,
+  TEST__getTestGraphManagerState,
+} from '../../../../../../__test-utils__/GraphManagerTestUtils.js';
+import { RawPrimitiveInstanceValue } from '../../../../../../../graph/metamodel/pure/rawValueSpecification/RawPrimitiveInstanceValue.js';
+import { observe_RawPrimitiveInstanceValue } from '../../../../../../action/changeDetection/RawValueSpecificationObserver.js';
+
+type TestCase = [string, PlainObject, PlainObject];
+
+const cases: TestCase[] = [
+  [
+    'Multi-line raw CString',
+    {
+      _type: 'string',
+      multiLine: true,
+      value: 'line one\nline two',
+    },
+    {
+      _type: 'string',
+      multiLine: true,
+      value: 'line one\nline two',
+    },
+  ],
+  [
+    // engine omits this flag from the wire when it is `false`, we must do the same
+    'Single-line raw CString does not emit the multi-line flag',
+    {
+      _type: 'string',
+      multiLine: false,
+      value: 'hallo',
+    },
+    {
+      _type: 'string',
+      value: 'hallo',
+    },
+  ],
+  [
+    'Legacy format of multi-line raw CString',
+    {
+      _type: 'string',
+      multiLine: true,
+      values: ['line one\nline two'],
+    },
+    {
+      _type: 'string',
+      multiLine: true,
+      value: 'line one\nline two',
+    },
+  ],
+];
+
+describe(unitTest('Raw value specification serialization'), () => {
+  test.each(cases)(
+    '%s',
+    (testName: TestCase[0], before: TestCase[1], after: TestCase[2]) => {
+      expect(
+        V1_serializeRawValueSpecification(
+          V1_deserializeRawValueSpecification(before),
+        ),
+      ).toEqual(after);
+      // do an additional roundtrip
+      expect(
+        V1_serializeRawValueSpecification(
+          V1_deserializeRawValueSpecification(after),
+        ),
+      ).toEqual(after);
+    },
+  );
+
+  test('Multi-line flag survives the metamodel roundtrip', async () => {
+    const graphManagerState = TEST__getTestGraphManagerState();
+    await TEST__buildGraphWithEntities(graphManagerState, []);
+    const json = {
+      _type: 'string',
+      multiLine: true,
+      value: 'line one\nline two',
+    };
+
+    const metamodel = guaranteeType(
+      graphManagerState.graphManager.buildRawValueSpecification(
+        json,
+        graphManagerState.graph,
+      ),
+      RawPrimitiveInstanceValue,
+    );
+    expect(metamodel.value).toBe('line one\nline two');
+    expect(metamodel.multiLine).toBe(true);
+
+    expect(
+      graphManagerState.graphManager.serializeRawValueSpecification(metamodel),
+    ).toEqual(json);
+
+    // the flag must be observable, else change detection would not pick up a toggle
+    observe_RawPrimitiveInstanceValue(metamodel);
+    metamodel.multiLine = false;
+    expect(
+      graphManagerState.graphManager.serializeRawValueSpecification(metamodel),
+    ).toEqual({ _type: 'string', value: 'line one\nline two' });
+  });
+});