Citi Hackathon FDC3 Use Case: Create a tool for defining FDC3 Context schemas

[lucaborella89]

Create a tool for defining FDC3 Context schemas

Expected Features

• FDC3 messaging is based on a set of standardized context messages, defined in JSON schema
  E.g. https://fdc3.finos.org/docs/next/context/ref/Chart
  Schema file: https://github.com/finos/FDC3/blob/main/schemas/context/chart.schema.json
• The schema file is the 'single source of truth' for the definition of a Context - the documentation page above is generated from it (a recent change being released in 2.2), as are typescript types representing contexts. e.g. https://github.com/finos/FDC3/blob/93685d9e5dcebf7faa784f860e1898253013c6ac/src/context/ContextTypes.ts#L202-L239
• However, defining a context type in JSON Schema currently requires learning JSON Schema, which is complex, or copying an example and updating it (with your fingers crossed that you got it right).
• Further, new standardized contexts are currently only released when a new FDC3 version is released (which happens on a cadence set by changes to the FDC3 API). The FDC3 maintainers have long had a goal of separating the two so that context can be contributed more easily and released on a rolling schedule, rather than annually (or less than annually) as at present, see: Should we split context & intent out of the main FDC3 standard? FDC3#940

Useful info

Kris West is the maintainer of FDC3
Alexandru Dumitru is a contributor and Project Administrator to FDC3

• Generating the context docs from the schemas was a first step in getting that done - now a context is represented only by its schema file.
• We've discussed trying to create a tool/webpage that helps you generate a schema for your context and add docs to it, before helping you to contribute it to FDC3
• Quicktype could be useful here: https://app.quicktype.io/

[kriswest]

To work on this use case, create your own github repository for your tool - if you're successful the FDC3 maintainers can work with you to add it to the FDC3 website to help companies to contribute to the Standard in future.

[kriswest]

Also checkout:

• QuickType on Github for programmatic use in JavaScript: https://github.com/glideapps/quicktype
• Introduction to JSON schema: https://json-schema.org/learn/getting-started-step-by-step

[robmoffat]

Have a look at the GitHub API if you want to raise a PR: https://docs.github.com/en/rest?apiVersion=2022-11-28

or, use a language wrapper on this (e.g. Java: https://github-api.kohsuke.org)

[aakti]

I'm not sure if I understood this correctly, looks like the expectation is to build a UI that simplifies the creation and documentation of FDC3 context schemas. This includes user-friendly forms and automated documentation. quicktype is doing the same thing but there is no UI.

@robmoffat, @kriswest could you please explain the use-case?

[kriswest]

Hi @aakti - apologies I missed the notification for your message!

... the expectation is to build a UI that simplifies the creation and documentation of FDC3 context schemas.

Correct - in the past it was a lot of work to contribute to the FDC3 Context part of the Standard if you hadn't done so before. You needed to write both a JSON schema file and a markdown documentation page, ensure the code generation scripts picked up the new context and that the new docs page was linked into the navigation and from other relevant pages etc.. That has slowed down contributions and sometimes led to firms looking at the Standard, not seeing matching their use cases and moving on rather than contributing a new context type to support their use case (and that of others that might want to work with them). Hence, our goal is to make it easier to contribute.

In FDC3 2.2 we are moving to high-quality autogenerated documentation pages - so that a contributor no longer has to deal with those. They are generated from the schema, linked into the site and from other pages automatically. E.g.:

• Old (manually created) page: https://fdc3.finos.org/docs/2.0/context/ref/Chart
• New (autogenerated) page: https://fdc3.finos.org/docs/next/context/ref/Chart

That solves half of the problem as now you can open pull request that adds a new schema file in here: https://github.com/finos/FDC3/tree/main/schemas/context and a documentation page is automatically generated. The remaining problem is that developers need to:

1. Learn JSON Schema,
2. Produce a valid schema representing their context object.
3. Add documentation and examples to that schema.
4. Then create a pull request to contribute it.

A UI tool that helps create a context schema could make these steps much easier, and could even go as far as helping to create the PR into the FDC3 repository. I can see a couple of ways of approaching the build of such a tool:

1. Use a tool like quicktype that can help turn a JSON example into a schema and build on it.
   • Quicktype can be called from javascript to interpret a JSON input and to produce a JSON schema output.
2. Build something manually that helps to build-up a schema quickly by adding fields to it (JSON schema is still just JSON afterall and hence easy to assemble).

Work would be needed to make sure any solution:

• Applies the BaseContext schema: note how the BaseContext schema is combined with the custom schema for existing context types in the first and last lines of this example: https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/country.schema.json#L7-L51
• Includes a title and description
  • for the whole schema, e.g. https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/country.schema.json#L5-L6
  • for each field in the schema: e.g. https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/country.schema.json#L17-L21
• Uses sensible types (perhaps by selecting them from a drop-down), including:
  • References to other context types, e.g.: https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/email.schema.json#L14-L25
  • Conventions in the standard: https://fdc3.finos.org/docs/next/context/spec#other-field-type-conventions
    • Which may be supported via string formats defined in JSON schema: https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/timeRange.schema.json#L13-L18
    • A regex pattern: https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/currency.schema.json#L24
    • Or an enum: https://github.com/finos/FDC3/blob/7e5d89cfaa48decb181bbcc9e1c56f280e121f1c/schemas/context/transactionresult.schema.json#L16-L21
    • or other types defined in JSON schema, see: https://json-schema.org/understanding-json-schema/reference/type

I would start by checking out a few of the schemas in https://github.com/finos/FDC3/tree/main/schemas/context and their docs pages at: https://fdc3.finos.org/docs/next/context/spec#standard-context-types to make sure you understand the schemas. Then start thinking about how you could make it easy to create one from scratch or build one up by modifying a simple example (fdc3.nothing is our simplest type, while fdc3.contact is likely the lowest common denominator (has type, id and name fields only).

I hope that helps - I believe we are planning for a office hours session tomorrow at 17:30 IST - happy to discuss this more there or in this discussion thread!

[001ak]

This is our repo link for the contribution:
https://github.com/bpranjal/FinosHackathon
Team Members:
Aman Kumar
Nikhil Bhisle
Pranjal Bagal
(Citi Employees)

[swatighadge]

Hi Finos/Community, My Repo https://github.com/swatnew/finos_repo Swati Ghadge (Citi Employee)

…

On Fri, Nov 15, 2024 at 11:48 PM Aman Kumar ***@***.***> wrote: This is our repo link for the contribution: https://github.com/bpranjal/FinosHackathon <http://url> Team Members: Aman Kumar Nikhil Bhisle Pranjal Bagal (Citi Employees) — Reply to this email directly, view it on GitHub <#332 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AI2MXRKO34OBKAXJN4GYPM32AY3IXAVCNFSM6AAAAABQNIBLTCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTCMRXGE4TEOA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[kriswest]

Hi @swatighadge, I can't see that repository on either of your github profiles (@swatighadge and @swatnew). Could you check that it's public please?

K

[kriswest]

Many thanks, can see it now

[swatighadge]

Yes, I will check.

…

On Tue, Nov 19, 2024, 19:40 Kris West ***@***.***> wrote: Hi @swatighadge <https://github.com/swatighadge>, I can't see that repository. Could you check that its public please? K — Reply to this email directly, view it on GitHub <#332 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AI2MXRLK5JQAMMPB4MUJ2X32BNBGVAVCNFSM6AAAAABQNIBLTCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTCMZQGYYTAOI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[swatighadge]

Hi Finos/Community , Please check now , the repo is public. Swati Ghadge

…

On Tue, Nov 19, 2024 at 8:11 PM Swati Ghadge ***@***.***> wrote: Yes, I will check. On Tue, Nov 19, 2024, 19:40 Kris West ***@***.***> wrote: > Hi @swatighadge <https://github.com/swatighadge>, I can't see that > repository. Could you check that its public please? > > K > > — > Reply to this email directly, view it on GitHub > <#332 (reply in thread)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AI2MXRLK5JQAMMPB4MUJ2X32BNBGVAVCNFSM6AAAAABQNIBLTCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTCMZQGYYTAOI> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >