SPEC_CONFORMANCE.md

Spec conformance report

Spec version: 0.9.0 (client_rest.yaml and indexing.yaml, identical info.version)
Operations in spec: 135
Cmdlets generated: 126 API + 11 core
Generated by: tools/spec_conformance.py, from contract/glean-api.json and contract/cmdlet-surface.json

This report is regenerated by ./build.ps1. It is not maintained by hand, so it cannot drift from what the module actually does.

Method

Both published specs are parsed into one contract file (tools/extract_contract.py), every operation is mapped to a cmdlet with the naming rules enforced (tools/build_cmdlet_map.py), and both module implementations are generated from the result. Coverage is therefore checked at build time rather than audited afterwards: an operation with no cmdlet fails the build.

Specs diffed against:

https://gleanwork.github.io/open-api/specs/final/client_rest.yaml
https://gleanwork.github.io/open-api/specs/final/indexing.yaml

Coverage

API surface	Operations	Covered	Gaps
client	91	91	0
custommetadata	6	6	0
indexing	38	38	0
Total	135	135	0

Every operation in the spec is reachable from a cmdlet. Get-GleanApiOperation lists the mapping at runtime.

Divergences from the spec

None. Paths, methods, request body field names and required-field flags are taken verbatim from the spec by the generator; there is no hand-written call site that could disagree with it. The two places the generator does not copy the spec verbatim are PowerShell naming rules and cmdlet consolidation, both listed below.

Divergences glean-code-cli has that this SDK does not

glean-code-cli's incompat_report.md records twelve places where its hand-written client disagrees with spec 0.9.0. Because this SDK is generated from the spec, it calls the documented path and body in each case:

glean-code-cli sends	Spec requires	This SDK
POST /getdocumentpermissions body {documentSpec:{id}}	POST /getdocpermissions body {documentId}	Get-GleanDocumentPermission
POST /announcements/list	no list endpoint exists in the spec	not exposed — the endpoint does not exist
POST /announcements/create	POST /createannouncement	New-GleanAnnouncement
POST /announcements/delete	POST /deleteannouncement	Remove-GleanAnnouncement
POST /createpin body {url, query}	POST /pin body {documentId, queries[]}	New-GleanPin
POST /tools/list	GET /tools/list with a toolNames query parameter	Get-GleanTool
POST /tools/call body {name, arguments}	body requires {name, parameters}	Invoke-GleanTool
POST /people body {email}	body requires {emailIds: [...]}	Get-GleanPerson
POST /summarize body {documentSpec}	body requires {documentSpecs: [...]}	Get-GleanDocumentSummary
POST /feedback body {trackingToken, category}	body requires {event, trackingTokens: [...]}	Send-GleanFeedback
POST /agents.run body {agentId, input: str}	body requires {agent_id, input: {}}	Invoke-GleanAgent

The mock responder in this SDK keys off the spec paths as well, so a script written against mock mode calls the same endpoint live.

Naming decisions

Verbs used across 126 API cmdlets, all approved by Get-Verb:

Verb	Cmdlets	Meaning in this SDK
Get	42	read something
Set	23	create or update one record (upsert)
Remove	17	delete
New	11	create something that did not exist
Sync	7	bulk upload that makes the index match your source of truth
Invoke	4	run an operation whose result is the point
Save	4	write a returned file to disk
Send	4	push data one way
Start	3	begin asynchronous server-side processing
Add	2	add to an existing container
Request	2	begin an authorization flow
Test	2	check and report
Update	2	rotate or refresh an existing credential
Find	1	search a container
Import	1	load a definition
Submit	1	hand data to a processing pipeline

Parameters renamed from their wire name

A spec field is renamed only when its PowerShell name would collide with a PowerShell automatic variable or a common parameter. Where the original spelling is still safe to accept, it is kept as an alias.

Cmdlet	Spec field	Parameter	Alias	Reason
Invoke-GleanAgent	input	-AgentInput	-Input	shadows a PowerShell automatic variable
New-GleanAnnouncement	body	-BodyValue	—	collides with a parameter this SDK adds to every cmdlet
Send-GleanFeedback	event	-EventType	-Event	shadows a PowerShell automatic variable
Set-GleanAnnouncement	body	-BodyValue	—	collides with a parameter this SDK adds to every cmdlet

Operations consolidated into one cmdlet

PowerShell convention is that a Get- cmdlet lists when given no identifier and fetches when given one, rather than shipping separate Get- and List- commands (List is not an approved verb). These cmdlets front more than one operation, selected by parameter set:

Cmdlet	Parameter sets
Get-GleanAnswer	List, ById
Get-GleanChat	List, ById
Get-GleanCollection	List, ById
Get-GleanPin	List, ById
Get-GleanPolicy	List, ById
Get-GleanShortcut	List, ById
Invoke-GleanAgent	Wait, Stream
Remove-GleanChat	ById, All
Send-GleanChatMessage	Wait, Stream

Verifying this yourself

# every operation and the cmdlet that covers it
Get-GleanApiOperation | Format-Table Cmdlet, Method, Path, Api

# coverage by API surface
Get-GleanApiOperation | Group-Object Api | Select-Object Name, Count

# find the cmdlet for an endpoint you know by path
Get-GleanApiOperation -Path '*summarize*'