An annotation shape may declare properties that do not belong to the shared Annotation node. Here a separate role type has a required name. Its RoleName data type allows only three values.
All properties on the Annotation node and its ancestors apply automatically to every annotation shape, including optional fields. A shape adds its own properties and cannot redeclare a shared name. Separate shapes may independently use the same property name with different data types or constraints. Invalid JSON Schema expressions on shape-owned properties are reported during model validation.
Annotation definitions, their own properties and constraints share the owning model's ID space. Each declaration needs a unique ID. Deleting a shape leaves shared node properties intact.
Define the nodes and relationships that role may use:
import type { Node, Relation } from '@ramen-suite/core/model';
import { RAMEN_ELEMENT, RamenModel } from '@ramen-suite/core/ramen';
const media: RamenModel = RamenModel.create('Media');
const text: Node = media.createNode({ name: 'Text', refines: RAMEN_ELEMENT.CONTENT }).element;
const person: Node = media.createNode({ name: 'Person', refines: RAMEN_ELEMENT.ENTITY }).element;
const textLink: Relation = media.hasAnnotation(text, RAMEN_ELEMENT.ANNOTATION).element;
const personLink: Relation = media.refersTo(RAMEN_ELEMENT.ANNOTATION, person).element;
Declare RoleName with three permitted string literals:
import { DataTypes } from '@ramen-suite/core/model';
import type { DataType } from '@ramen-suite/core/model';
const roleName: DataType = media.createDataType({ name: 'RoleName', baseType: DataTypes.String }).element;
media.createLiteral(roleName.id, { name: 'Sender', literal: 'sender' });
media.createLiteral(roleName.id, { name: 'Recipient', literal: 'recipient' });
media.createLiteral(roleName.id, { name: 'Mentioned', literal: 'mentioned' });
Now declare role. Its name property belongs only to this type, while uuid, type and selector remain on the shared Annotation node:
media.createAnnotationShape({
nodeId: RAMEN_ELEMENT.ANNOTATION,
type: 'role',
properties: [{ name: 'name', type: roleName, bounds: { lowerBound: 1, upperBound: 1 } }],
relations: [
{ relation: textLink, direction: 'incoming', bounds: { lowerBound: 1, upperBound: 1 } },
{ relation: personLink, direction: 'outgoing', bounds: { lowerBound: 1, upperBound: 1 } },
],
});
The relevant properties of a recorded Role annotation are:
{ "type": "role", "name": "sender" }
validateAnnotationValue() checks this input without recorded nodes or links. In a complete data graph with the required Text and Person links, validateInstances() also accepts sender. The literal check rejects editor, and omitting name violates 1..1. See Validate RAMEN Data for both checks and Add Constraints for rules beyond a value list.