Skip to manual
gluon

GOL language

ObjectType

An ObjectType describes a business entity: its keys, properties, source mappings and how the product shows it.

Model author or developer

Where it goes

Contoso keeps Contract in domains/procurement/objects/contract.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in PascalCase. The name must be unique within its domain across all type kinds.

Fields

The keys under spec. Nested shapes follow ObjectTypeSpec in the GOL JSON Schema.

FieldPresenceShape
aggregateOptionalobject
identityRequiredobject
implementsOptionalarray
propertiesRequiredpropertyMap
invariantsOptionalinvariants
lifecycleOptionalobject
sourcesOptionalarray
resolutionOptionalobject
editsOptionalobject
searchOptionalsearch
retentionOptionalobject
securityOptionalobject
displayOptionalobject
aiOptionalai

Syntax and rules

The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.

5. ObjectType (entity)

GOL · YAML
kind: ObjectType
metadata: { name: Contract, plural: Contracts, status: active }
spec:
  aggregate: { role: root } # root | member; members name their root
  identity:
    primaryKey: [contractId]
    naturalKeys: [[supplierId, contractNumber]]
    title: title # property shown as the object's name
    subtitle: contractNumber
  implements:
    - interface: core.Agreement
      map: { startsOn: effectiveDate, endsOn: expiryDate } # interface property -> local property
      links: { counterparty: supplier } # interface link constraint -> local link role
      actions: { Renew: RenewContract } # interface action contract -> ActionType
  properties:
    contractId: { type: uuid, required: true, immutable: true }
    contractNumber: { type: string, required: true, unique: true, searchable: true }
    title: { type: string, required: true, searchable: true }
    supplierId: { type: uuid, required: true, indexed: true }
    region: { type: Region, required: true, facet: true } # an EnumType; row policies filter on it
    effectiveDate: { type: date, required: true }
    expiryDate: { type: date }
    renewalDate: { use: core.renewalDate } # SharedProperty
    value: { type: "std::Money" }
    negotiatedRate:
      type: "decimal(5,2)"
      unit: percent
      sensitivity: { classification: restricted, markings: ["marking:commercial-sensitive"] }
    ownerEmail:
      type: std::Email
      sensitivity: { pii: contact, masking: { method: partial } }
    state: { type: ContractState, required: true, default: draft }
    daysToRenewal:
      type: integer
      derived: { expr: "gluon.days(self.renewalDate - gluon.today())", materialize: daily }
    openIssues:
      type: integer
      derived: { aggregate: count, over: issues, where: "it.state != 'closed'" } # over a link role
    summary: { type: text, ai: { generated: true, from: [attachment] } }
    document: { type: attachment }
    embedding: { type: "vector(1024)", derived: { embed: [title, summary], model: default } }
  invariants:
    - id: dates-ordered
      expr: "!has(self.expiryDate) || self.expiryDate > self.effectiveDate"
      message: Expiry must be after the effective date.
      severity: error
  lifecycle:
    property: state
    initial: draft
    transitions:
      - { from: draft, to: active, via: ActivateContract }
      - { from: active, to: expiring, when: "self.daysToRenewal <= 90" } # automatic
      - { from: [active, expiring], to: expired, via: ExpireContract }
  sources: # section 8
    - source: source:sharepoint-legal
      role: primary
      map: { contractNumber: $.fields.ContractNo, title: $.name, document: $.file }
    - source: source:erp-contracts
      role: enrich
      map: { value.amount: TOTAL_VALUE, value.currency: CURR }
  edits: { mode: actions-only, history: true } # none | actions-only | direct
  search: { fullText: [title, summary], facets: [state, supplier], semantic: embedding }
  retention: { keep: P7Y, after: expiryDate, basis: legal-obligation, then: anonymize }
  security:
    classification: confidential
    markings: ["marking:legal"]
    rowPolicy: policy:contracts-by-region
  display:
    {
      icon: file-signature,
      color: "#7C5CFF",
      visibility: prominent,
      card: [contractNumber, supplier, state, renewalDate],
    }
  ai:
    description: Use for any question about supplier agreements, renewals, spend commitments.
    exampleQuestions: ["Which supplier contracts renew next month?"]
    neverExpose: [negotiatedRate] # never placed in an LLM prompt, even if readable
    never: # what its records never hold: asked about someone, Gluon says so
      - {
          about: [bribe, kickback],
          message: "A contract never records a payment outside its terms.",
        }

ai.never (added 2026-10-21, Waseem, asked interactively) lists topics the type's records never hold, each with the words that ask for it (about, three characters or more) and what to say (message). A question that uses one of those words and names someone a record of that type read for the answer is about (its capitalised words, in the record) is refused by Gluon with the message, before the model is asked: a sick-leave record never holds a diagnosis, an employee record no salary. A question naming nobody ("Wat verdient een Wmo-consulent maximaal?") goes on, since a document may answer it.

5.1 Property attributes

GroupKeys
Shapetype or use (SharedProperty), required, default, immutable, unique, constraints
Queryindexed, searchable, sortable, filterable, facet
Derivationderived: {expr} or {function, args} or {aggregate, over, where} or {embed, model}; each form takes materialize: never, on-write, hourly, daily inside derived
Sensitivitysensitivity: {classification, pii, markings, masking: {method: redact, partial, hash, tokenize, generalize, keepFirst, keepLast}}
Timehistory: true (keep prior values), bitemporal: true, asOf
Displaytitle, description, unit, format, renderHint (badge link image longText code progress), conditionalFormat: [{when, color}], visibility
Lineagelineage: required, optional (required means a value without a source reference is rejected at ingest)
AIai: {generated, from, neverExpose}
Lifestatus, since, deprecated, provenance

Shorthand: title: string equals title: {type: string}.

Further rules:

  • derived properties are read only, may traverse at most 3 link hops, cannot be a primary key or required, and are evaluated under the reader's security: a hop the reader cannot see contributes nothing (GLN-E214 for a longer path).
  • semantics gives a property a machine-readable meaning beyond its type, used by apps, maps and chat rendering: identifier userId thumbnailUrl latitude longitude altitude eventStart eventEnd measure currencyAmount parentKey (the useful core of Palantir's type classes, as a closed list).
  • sensitivity.encryption: at-rest | field stores the value encrypted with a per-marking key (P9 readableBy). Readers without the marking receive the mask, never the ciphertext.
  • When a property policy fails, the property is absent from the result and listed in _withheld, so a client can say "1 field withheld" and never mistakes a withheld value for a null one.
  • Primary key types: string integer long uuid. Anything else is GLN-E211.

5.2 Aggregates

aggregate.role: member types name their root. Rules the validator enforces: a member's primary key includes or references the root's key (GLN-E231); links from outside the aggregate should target the root (GLN-W232); composition links may only run inside one aggregate (GLN-E233); actions modify one aggregate per rule unless marked saga: true (GLN-W234).

Check your package

Shell
gluon validate examples/contoso
gluon test examples/contoso

validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.

Contoso's Contract ObjectType in the designer's YAML pane, with its validation status.
Contoso's Contract ObjectType in the designer's YAML pane, with its validation status.