Summary#
Prints the source of a capability. using Osysharp.Memory; puts real entities — real tables, with their own access
rules — into your app, but that source lives inside the platform rather than in your project, so no amount of
searching your own files will find it. osy source is how you read it. Offline: no server, no account, no database.
Signature#
osy source [name] [--json]name is a capability (Osysharp.Memory, or just memory) or a type it declares (MemoryChunk). Omit it to list
every capability with what it declares.
name may also be one file: a path on disk (../model/Checking.osy), or any tail of a file's path in a kit this
project can see (Osysharp.Qualifications/model/Checking.osy, qualifications/model/Checking.osy) or in a capability's
listing (Capabilities/Osysharp.Llm/model/Budgets.osy). A tail that two files share is refused, naming each one's full
address.
Description#
A capability is opted into per app in app.osy (use Osysharp.Memory;) and per file (using Osysharp.Memory;). What you
get in return is a set of declared types. Those types are not abstract: they become tables in your app's own database,
carrying the access rules the capability declares.
Because the source is embedded in the platform, three ordinary ways of answering "what did I just agree to" do not work — you cannot open the file, you cannot grep for it, and it is not in your version control. That gap is what this command closes.
It only ever reads. A capability declares types; the behaviour behind them is the platform's own (Osysharp.Blocks
and Osysharp.Llm are the exceptions: their functions are their implementation, in Osy#). So there is no
useful copy to take: a local fork would be a declaration with nothing implementing it, which would compile, shadow the
real one, and then be wrong. The one supported change to a capability entity is its security, and that is written as a
partial entity block in your own source:
```osy title="stating security for an entity a using brought in" test app=local-reading-a-capability
app Invoicing { use Osysharp.Storage; }
// use in the manifest takes the DEPENDENCY; using brings its types into THIS file's scope — the same split C#
// makes between a package reference and a using directive. A partial entity resolves its target through the
// file's usings, so both lines are needed.
using Osysharp.Storage;
[Principal] entity User { string Email; }
// FileAsset is declared by using Osysharp.Storage; — this app never declares it, and cannot.
// A partial adds no fields and changes no shape; it states who may reach the type.
partial entity FileAsset {
security { allow read when IsAuthenticated; }
}
For an entity the capability leaves ungoverned — as `FileAsset` is above — what you write is the whole rule.
Some capability tables arrive already governed, because their rows belong to one signed-in user and only the
capability knows that: a chat conversation is yours, not the app's. There your partial **adds** to the rule already
there rather than replacing it, so you can grant a support role extra reach without being able to take the owner's
access away. See [capability rows that belong to a user](/reference/security/capability-row-ownership/).
> The UI kit is the exception, and deliberately so. A kit control is presentational — the source you read *is* the
> implementation — so it is meant to be forked. `osy kit` browses it and `osy get ui/<control>` vendors a copy into
> your project to change. See [Osysharp.Ui (the UI kit)](/reference/ui/kit/).
## Examples {#examples}
Every capability, and what each declares:
```console
osy sourcePlatform capabilities — opt in per file with `using <name>;` (and in app.osy)
Osysharp.Memory
ContextType, EntityContext, FileChunk, Reference, ReferenceKind, …
Osysharp.Storage v1.1.0
FileAsset, FileGrant, FileGrantLevel, FileVersion, Folder, IBlobStore, …
(+1)
Osysharp.Workflow v1.0.0
AuditKind, CorrelationOutcome, FlowMetrics, Leg, Losers,
RequirementStatus, … (+18)
The core baseline — in every app; no `using` opts in, and none can opt out
Osyrin (21 files)
ActionState, Align, AlignSelf, Allowance, AllowanceState, ApiResponse, …
(+66)The core baseline is the last section, and it is not one of the choices above it: it is what your app carries
having asked for nothing. Read it with osy source core.
⚠ It is much smaller than it used to be. The workflow runtime, the markdown store and the OAuth grant store were
all core once — this page said so, and listed AuditKind among the always-in-scope names. They are capabilities
now (Osysharp.Workflow is in the list above, carrying exactly that type), and an app that names none of them
carries two tables of the platform's: Osysharp.AppAdmission and Osysharp.Continuation. osy model reports
the count for your app — see use.
One capability's whole source, comments and all:
osy source Osysharp.MemoryOr start from a type you met in osy model output or in an error, and let it find the using:
osy source FileAsset# FileAsset is declared by `using Osysharp.Storage;`When the question is only what fields does it have, osy docs takes the same names and answers shorter — the
member list and the using, without the declaration around it:
osy docs FileAssetFileAsset — a platform entity, in scope with `using Osysharp.Storage;`
A stored file asset with hybrid inline/external storage.
string? AltText
string? MimeType
string Name
FileVersion CurrentVersion
bool IsPublic
Folder Folder
the full declaration — doc comments, attributes, security: osy source FileAssetAn enum answers with every member it has, which is usually the whole question — osy docs Size prints
Sm · Md · Lg. osy docs --list <word> searches these names too, so a half-remembered type is findable without
knowing which capability declares it.
See also#
- Explaining your app's security — which of these your app has actually opted into, and who can read each one, including the core baseline every app carries
- Understanding your app — the resolved model, with capability types bound exactly as the server binds them
- Osysharp.Ui (the UI kit) — the kit, which is read the same way but is meant to be forked