feat(context): add programmatic context schema discovery - #1980
feat(context): add programmatic context schema discovery#1980nchalaisRocket wants to merge 3 commits into
Conversation
✅ Deploy Preview for fdc3 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
543e02e to
07594ea
Compare
Expose the standardized FDC3 context JSON Schemas at runtime from @finos/fdc3-context (re-exported from @finos/fdc3) so applications and tooling can enumerate context types and retrieve their schemas without a Desktop Agent connection. Adds getContextTypes(), getContextSchema(), getAllContextSchemas(), getContextSchemaMetadata() and isStandardContextType(). The registry is generated from the existing schema files (single source of truth) via a new schemagen build step, keeping it automatically in sync. The abstract base context type is excluded and all returned values are defensive copies. Includes tests, spec documentation and a CHANGELOG entry.
07594ea to
ef8bece
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1980 +/- ##
=======================================
Coverage 95.32% 95.32%
=======================================
Files 85 85
Lines 6698 6698
Branches 788 782 -6
=======================================
Hits 6385 6385
Misses 313 313 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
kriswest
left a comment
kriswest
left a comment
There was a problem hiding this comment.
Please do raise an issue for this proposed change describing the use cases - we use issues for release milestone planning so all PRs should (for anything other than project governance/infrastructure maintenance) should have an associated issue.
Generating a copy of every schema as a javascript object to facilitate this access at runtime seems wasteful when the schema files themselves are bundled (
FDC3/packages/fdc3-context/tsconfig.json
Line 13 in 15931ac
However, one generation step is desired already for #1852, where an enum and union of the known types is desired (similar to your getContextTypes function). That could be dealt with here in fdc3-context (where should have been moved to previously) and then re-exported by fdc3-standard.
|
Thanks for the review @kriswest!
I'll push a revised implementation along those lines. Let me know if you'd prefer #1852 handled as a separate PR that this one builds on, or all together here. |
Personally, I'm happy to deal with both issues in one PR/review. I support the schema access use case and am very happy to see a new contributor taking it on, alongside overlapping work we've already committed to! |
|
n.b. |
|
"Today the standardized context JSON Schemas are the single source of truth for context definitions" - this is not true. The schemas must represent the actual apps which are available in any given system (which will rarely conform to the standard definitions, and certainly wouldn't support all of them in any given configuration). Agreed that such a feature would allow agents to interoperate with FDC3 in a very powerful way but it involves multiple changes to the specification, not a library commit that reads from hardcoded files: 1 - an expansion of appd to support context schemas (which would be loaded by desktop agents) |
|
@thorsent makes a good point - this will of course only enable retrieval of the standard schemas. Apps can define their own context types and there would end up being no way to retrieve those schemas (a context does not link to its schema). There is a very old issue open for the AppD to be able to do that: #719 then as @thorsent indicates a desktop agent could make all schemas from all appDs it is aware of available. However, I don't think that negates the value of improving access to the standard's own schemas. But, depending on your use case, further work my be needed! |
|
@kriswest we wouldn't want to expose the standard schemas in totum (as implemented here) because it would imply that the running instance contains apps which support those contexts. A coding agent might desire a complete set, which it could already obtain from the source code. But a runtime agent really needs to know what is actually available at runtime. Even if the hardcoded list were filtered by availability the net result would be that the agent has access to partial information at best, which would result (I think) in confused developers and agents. I don't think it's that much extra specification to implement a more complete solution. The question is whether there's an appetite to expand the spec in this direction. |
|
This proposal doesn't expose anything through the Desktop Agent API, only from the fdc3-context and fdc3 libs. I read this as relating to cases where you already know its one of the standardized types that you are working with and want to gather context (about the the context type) to generate a valid instance of a context type - rather than discovering what's in use through the Desktop Agent or AppD.. On that level it seems reasonable - but definitely does not solve a wider problem where a firm defines their own context - in our case we provide our own library for that includes our custom schemas and types (+the FDC3 standard ones for convenience). Hence a question to @nchalaisRocket: is the problem you want to solve tightly scoped to the standard types. Or are you interested in a general solution? As discussed here a general solution is possible but would require us to evolve the AppD servers and Desktop Agent API to manage and expose additional data, which could then include custom/proprietary types. We've had a related issue open for many years, but the use cases have grown due to AI. There is another issue open that relates to that: |
|
Thanks @kriswest and @thorsent, good points from both of you. On scope: this PR is small on purpose. It just lets you read the standard context schemas straight from the library. The idea is simple. Say you already know you're working with an Tom, fair point on the "single source of truth" wording. I only meant that the schema files are the official definition of the standard types, not what's available at runtime. I'll fix that and make the scope clear. Runtime discovery of what a DA or AppD actually offers, custom types included (#719 / #1713), is clearly the bigger goal, but that's a real spec change and out of scope here. I'd keep it separate. This PR just gives it a solid starting point for the standard types.
Does that sound reasonable? Standard schemas here, runtime discovery as its own thing. thanks a lot for your kind reviews |
|
This did sound reasonable to me - please do update it as described when you have a minute and we'll try and get it merged. |
4 participants
Describe your change
This PR adds programmatic context schema discovery to
@finos/fdc3-context(and, by re-export,@finos/fdc3).Today the standardized context JSON Schemas are the single source of truth for context definitions, but they are only used at build time (to generate
ContextTypes.ts) and are not available to consumers at runtime. This makes it hard for tooling — resolvers, validators, form/UI generators, documentation, and agents bridging FDC3 onto other protocols (e.g. MCP) — to reason about the set of available context types and their shapes without hard-coding or re-bundling the schemas.This change exposes the schemas at runtime via a small accessor API:
getContextTypes(): string[]getContextSchema(type): ContextSchema | undefinedundefined.getAllContextSchemas(): Record<string, ContextSchema>getContextSchemaMetadata(type): ContextSchemaMetadata | undefinedtitle,description,$id,examples).isStandardContextType(type): booleanImplementation notes:
schemas/context/*.schema.jsonfiles via a newschemagenbuild step (generateContextSchemas.cjs), wired intonpm run generate. It therefore stays automatically in sync with the source-of-truth schemas — no hand-maintained duplication.fdc3.context) is intentionally excluded, as it is not a concrete, broadcastable context type.website/docs/context/spec.md→ "Programmatic Schema Discovery"), package README docs, and a CHANGELOG entry. Full monoreponpm run buildand the@finos/fdc3-contexttest suite pass.Related Issue
No existing issue — raising this to propose and discuss the feature. Happy to open a tracking issue if the maintainers prefer. This is intended as a starting point for discussion.
Contributor License Agreement
Review Checklist
DesktopAgent,Channel,PrivateChannel,Listener,Bridging)? — No. This adds library accessor functions to@finos/fdc3-context; the Desktop Agent API and wire protocols are unchanged.npm run build) was run and the generated registry checked in.