Context¶

Context is Poly’s hierarchical namespace for catalog resources. It is a string of dot-separated segments, for example payments.stripe. Together with a resource’s name, it becomes the SDK path poly.<context>.<name>.

Empty context is allowed. Then the resource hangs directly under poly as poly.<name>.

Context is not a folder on disk. Generate builds a nested SDK from the dots.

Naming rules¶

Each context segment must start with a letter or underscore. After that: letters, numbers, underscores. Dots separate segments.

Forbidden: consecutive dots (foo..bar), a trailing dot (foo.), a segment that starts with a digit (2fa), hyphens (foo-bar).

Context	Valid?	Notes
(empty)	yes	Resource at `poly.<name>`
`myContext`	yes
`payments.stripe`	yes	SDK `poly.payments.stripe.<name>`
`_private.util`	yes
`2fa`	no	Segment must start with a letter or underscore
`foo..bar`	no	Consecutive dots
`foo.`	no	Trailing dot
`foo-bar`	no	Hyphen not allowed in context

Name is the leaf identifier. It cannot be empty. Default rule: letter or underscore first, then word characters. Hyphens and spaces are off unless a specific DTO enables them.

Context and permission scope.paths matching are case-sensitive. Use the same casing everywhere. Payments and payments are different contexts.

SDK mapping¶

Deploy with --context "myContext" and name helloWorld:

$ npx poly function add helloWorld ./hello-world.ts --context "myContext" --server

Call site after generate:

await poly.myContext.helloWorld();

Filter generate to some contexts:

$ npx poly generate --contexts "myContext,otherContext"

OpenAPI train uses the same field: npx poly model generate … --context "jsonPlaceholder".

Uniqueness¶

Within one environment, context + name is unique per resource kind:

API functions
Server and client functions (they share one uniqueness namespace: you cannot have both a server and a client function with the same pair)
Tabi tables
GraphQL subscriptions
Variables, snippets, and schemas (enforced at the app layer)

Webhook handles store context for SDK naming but uniqueness is on slug + subpath + method, not context+name.

If a tenant-level or public function uses the same pair, the environment-level function wins at generate and execute.

Recommendations¶

One or two segments for newcomers (payments, payments.stripe).
A stable top-level segment per domain.
Exact casing from day one.