Where it goes
Contoso keeps sharepoint-legal in sources/sources.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Source resources.
Limits
A Source names its connector and scope. The connector itself runs outside the package, and records and ACLs arrive only once it does.
Fields
The keys under spec. Nested shapes follow SourceSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
connector | Required | string |
mode | Optional | enum: synced, live, both |
receives | Optional | array |
ai | Optional | object |
scope | Optional | object |
trust | Required | enum: authoritative, curated, conversational, unverified |
acl | Optional | enum: mirror, ignore |
pii | Optional | object |
freshness | Optional | object |
deletes | Optional | enum: propagate, tombstone, ignore |
access | Optional | object |
chunking | Optional | object |
retrieval | Optional | object |
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.
8. Sources, mapping, entity resolution, PII
kind: Source
metadata: { name: sharepoint-legal }
spec:
connector: marketplace:sharepoint@3 # managed outside this package; the name is a contract
scope: { site: legal, library: Contracts }
trust: authoritative # authoritative | curated | conversational | unverified
acl: mirror # mirror the source ACL into row security: mirror | ignore
pii: { scan: true, masker: default, onDetect: mask } # mask | drop | quarantine | allow
freshness: { expect: P1D, alertAfter: P3D }
deletes: propagate # propagate | tombstone | ignore
A Source Gluon serves itself names a gluon: connector (gluon:database@1, gluon:mcp@1, gluon:files@1, gluon:website@1) and needs a source connection of the same name (a platform setting with its credential in the key service, never in GOL); marketplace: connectors push and need none. Added 2026-10-10 for Gluon Context:
kind: Source
metadata: { name: erp-live }
spec:
connector: "gluon:database@1"
trust: curated
mode: live # synced (default) | live | both: copied into memory, queried at question time, or both
freshness: { maxAge: PT0S } # the memory window (ISO duration); default PT0S for live sources, P1D for synced
receives:
["marking:legal"] # markings whose values may appear in a tool's arguments; default none
# `masked`: also after masked data that carries no marking was read
ai: { prompt: "Amounts exclude VAT." } # governed instruction added to the prompt when a tool of this source was used
A Source whose documents are uploaded to Gluon itself names gluon:files@1 (added 2026-10-27 for F31, docs/plans/gluon-guery.md decision 2). Its source connection of the same name has no host and no secret; the files are added, replaced and removed in Admin › Sources and each is read by the ingest.document job. Gluon is the system of record here, so access says what every file carries, and the upload never takes access from the browser:
kind: Source
metadata: { name: handbook, title: Staff handbook }
spec:
connector: "gluon:files@1"
trust: curated
acl: ignore # nothing to mirror: the ACL is the one below, always fresh
access: # on every file and its passages
markings:
["marking:internal"] # each a Marking of the package (GLN-E101 otherwise); any Source may name
# them: every row, passage and kept read of it carries them (2026-11-06)
acl: ["department:hr", "group:managers"] # gluon:files@1 and gluon:website@1 only: principals or "*"; default ["*"]
pii: { scan: true, masker: default, onDetect: mask }
deletes: propagate # a removal tombstones the file; `ignore` refuses removals
A Source whose documents Gluon crawls from a website or knowledge base names gluon:website@1 (added 2026-10-29: Confluence Data Center and Cloud, MediaWiki and generic sites, crawled by the gluon-crawl crate on the desktop and in cloud workers). Its source connection of the same name holds the starting URL and the crawl settings (profile, scope, domain hops, limits, refresh interval, excluded paths) and keeps an Authorization header or a session cookie in the key service, sent only to the starting origin. Per-page wiki permissions are not mirrored: every crawled page and its passages carry the Source's access, as for gluon:files@1, so access names the readers before the first crawl (the default ["*"] lets everyone in the namespace read it). A changed access reaches every page on the next run (Refresh now or the scheduled refresh), which admits all pages again. The crawl is queued as source.website; each page then takes the ingest.document job and its PDP checks:
kind: Source
metadata: { name: knowledge, title: Knowledge base }
spec:
connector: "gluon:website@1"
trust: curated
acl: ignore # wiki permissions are not mirrored; access below applies
access: { acl: ["group:knowledge-readers"] }
pii: { scan: true, masker: default, onDetect: mask }
deletes: propagate # a page a complete enumeration no longer lists is removed
A Source of documents may declare a structure profile (added 2026-10-27, Waseem, F31):
chunking: { structure: nl-legal } # the Dutch legal grammar; the only profile so far
With nl-legal, Gluon Ingest chunks the Source's documents by boek, deel, hoofdstuk, titel, afdeling, paragraaf and artikel, found by their words as well as by the parser's headings: a chunk never crosses an artikel, a lid opens a new chunk when it does not fit beside the text before it, the section path starts with the law's title, and every chunk carries law, lawKey, article and lid. A text numbering its articles in Roman numerals (a wijzigingswet, "ARTIKEL I") takes only those as articles. Each document is also written as one law.Law and one law.Article object per article (the law fragment in examples/wetten/domains/law, which a package copies to read them; a policy must grant readers traverse on the law domain too, or the links between articles show only as stubs, warning GLN-W512), under the document's access, with the article's refersTo and amends found by the grammar ("artikel 6, tweede lid, van de Handelsregisterwet 2007", "komt te luiden", "vervalt"): a reference resolves within the same law first, then by law title among the laws of the same Source; what does not resolve stays text in unresolvedRefs. A question that names an article reads that article first. Without a profile a Source is chunked by heading as before. An unknown profile is GLN-E010. Another jurisdiction is another profile.
A Source of documents may also turn on document summaries (added 2026-11-06, F31):
retrieval: { summaries: true } # off unless set
With summaries: true, Gluon Ingest asks the planner's route for a short overview of each document (what it is, what it covers, its main parts, in the document's language) from its title and the opening 12,000 characters of its text, both masked by the Source's masker, under the document's markings and every marking its type and the type's properties declare, booked to department:ingest (which needs a cap on the planner Model, or no summary is written). The overview is indexed as one more passage of the document (<document>#summary, summary: true, no character span, so it never counts as a labelled passage), with the document's access, and searched like the others, so an overview question ("waar gaat de Handelsregisterwet over?") finds it. A run without a model, or one the route refuses, indexes the document without one. Measured on the legal golden set: no gain in passage recall, so it is off by default (docs/plans/gluon-ingest.md, 5d).
On an ObjectType, sources[] maps source fields to properties (JSONPath for documents, column names for datasets, expr for CEL transforms). With more than one source:
resolution:
match:
- { keys: [contractNumber], confidence: 1.0 }
- { keys: [supplierId, title], fuzzy: { title: 0.92 }, confidence: 0.85 }
autoMergeAbove: 0.95
reviewBetween: [0.75, 0.95] # lands in the designer review inbox
survivorship: { default: by-source-role, value: most-recent, title: primary }
A sources[] entry may say where an object's record lives in that system, so a reader can open it there (added 2026-10-20, Waseem):
sources:
- source: "source:erp"
role: primary
recordUrl: "https://erp.example/contracts/{contractNumber}" # https only; each {name} a property of this type
map: { contractNumber: CONTRACT_NO }
The link is filled from the values the reader sees: a placeholder whose property is withheld, masked or empty for them leaves the object without a link, so a URL never carries a value they may not read. The source system checks its own permissions when the link is opened. A placeholder that is not a property of the type is GLN-E402. The object's detail view in chat shows it as "Open in "; with more than one entry, the one for the Source the object was read from.
A sources[] entry for a database Source may name the table the mapping reads, schema.table or table (added 2026-10-27, guery/sql): - {source: "source:erp", role: primary, table: proc.contracts, map: {contractNumber: CONTRACT_NO}}. Only a table named this way is shown to readers on chat's Data page and can be queried in their SQL editor, under the type's policies (docs/plans/gluon-guery.md decision 9); a mapping without table keeps working as before and is not browsable. Two types naming the same table are browsable, not queryable.
trust: conversational (Outlook, WhatsApp, Slack) values are stored as evidence and cannot populate a property unless the mapping states acceptConversational: true (GLN-E411). It goes on the sources[] entry to cover the whole mapping, or on one long-form map value: note: {from: $.body, acceptConversational: true} (long form keys: from, expr, acceptConversational). This is the rule that stops a chat message becoming policy.
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.
