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.
| Field | Presence | Shape |
|---|---|---|
aggregate | Optional | object |
identity | Required | object |
implements | Optional | array |
properties | Required | propertyMap |
invariants | Optional | invariants |
lifecycle | Optional | object |
sources | Optional | array |
resolution | Optional | object |
edits | Optional | object |
search | Optional | search |
retention | Optional | object |
security | Optional | object |
display | Optional | object |
ai | Optional | ai |
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)
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
| Group | Keys |
|---|---|
| Shape | type or use (SharedProperty), required, default, immutable, unique, constraints |
| Query | indexed, searchable, sortable, filterable, facet |
| Derivation | derived: {expr} or {function, args} or {aggregate, over, where} or {embed, model}; each form takes materialize: never, on-write, hourly, daily inside derived |
| Sensitivity | sensitivity: {classification, pii, markings, masking: {method: redact, partial, hash, tokenize, generalize, keepFirst, keepLast}} |
| Time | history: true (keep prior values), bitemporal: true, asOf |
| Display | title, description, unit, format, renderHint (badge link image longText code progress), conditionalFormat: [{when, color}], visibility |
| Lineage | lineage: required, optional (required means a value without a source reference is rejected at ingest) |
| AI | ai: {generated, from, neverExpose} |
| Life | status, since, deprecated, provenance |
Shorthand: title: string equals title: {type: string}.
Further rules:
derivedproperties are read only, may traverse at most 3 link hops, cannot be a primary key orrequired, and are evaluated under the reader's security: a hop the reader cannot see contributes nothing (GLN-E214for a longer path).semanticsgives 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 | fieldstores the value encrypted with a per-marking key (P9readableBy). 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 isGLN-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
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.
