Context Data & Intents Discussion group - 7 Sep 2023

[mistryvinay]

Group overview

At the FDC3 Use Cases Roundtable London, October 5th 2021 participants agreed that the FDC3 lexicon needs to be expanded, both with additional intents and context types to support Use Cases, but also to include more primitive data types in order to construct complex types. A number of participants also agreed that now is an appropriate time to expand the Lexicon.
​
See #455 for full details of the meeting outcomes.
​
This group is being convened to discuss and arrange work to contribute further Context types and Intents to support Use Cases being implemented by participants.

Relevant issue tags

Current open issues that relate to the discussion group:

Issues will also be tagged with the labels:

Meeting Date

Thursday 7 September 2023 - 9am EST / 2pm BST

WebEx info

• Meeting Link: https://finos.webex.com/finos/j.php?MTID=mbb193ae433ce8d4366adcecd94355734
• Meeting number: 2556 257 8293

More ways to join

• Join by video system:
  • Dial [email protected]
  • You can also dial 173.243.2.68 and enter your meeting number
• Join by phone
  • +1-415-655-0003 US Toll
  • +44-20319-88141 UK Toll
• Access code: 2556 257 8293

Meeting notices

• FINOS Project leads are responsible for observing the FINOS guidelines for running project meetings. Project maintainers can find additional resources in the FINOS Maintainers Cheatsheet.

• All participants in FINOS project meetings are subject to the LF Antitrust Policy, the FINOS Community Code of Conduct and all other FINOS policies.

• FINOS meetings involve participation by industry competitors, and it is the intention of FINOS and the Linux Foundation to conduct all of its activities in accordance with applicable antitrust and competition laws. It is therefore extremely important that attendees adhere to meeting agendas, and be aware of, and not participate in, any activities that are prohibited under applicable US state, federal or foreign antitrust and competition laws. Please contact [email protected] with any questions.

• FINOS project meetings may be recorded for use solely by the FINOS team for administration purposes. In very limited instances, and with explicit approval, recordings may be made more widely available.

• A Discussion Group has no direct decision-making power regarding the FDC3 standard - rather it is intended that anything they propose or work on will result in proposals (via Github issues and PRs) for the Standards Working Group participants to consider and vote on for inclusion in the standard.

Agenda

• Convene & roll call, review meeting notices (5mins)
• Review action items from previous meeting (5mins)
  • Context Data & Intents Discussion group - 3 Aug 2023 #1048
• Discussion of open issues (35mins)
  • Should we split context & intent out of the main FDC3 standard? #940
    • Continued discussion from last months meeting on reviewing proposal for new governance process
    • Identify automation / tooling required for proposal
    • Draft Proposal Copying markdown docs for contexts into schema files #1020
    • Google Doc tracking proposal
• Issues requiring a PR (5mins)
  • Actionable Notifications via Intent & Context #828
• AOB & Adjourn (5mins)

Minutes

• Should we split context & intent out of the main FDC3 standard? #940
  • Workflow: Continued discussion around the proposed governance workflow [Governance of Context and Intents Types from the FDC3 API(https://docs.google.com/document/d/183KJ6tIkrgsboFYp-cMEjCOvtumLwkFD1IRJ0Nzx5-8/edit?usp=sharing)
  • Type Namespacing: Name spacing and validation of naming new types. When creating a PR for new types we should ask "are you looking to contribute this type to the standard or are you looking to publicize a proprietary one in its own name space?" This would then determine which workflow is followed
    • All the standardized FDC3 types have to be named fdc3.something and the proprietary ones have to be named anything other than fdc3.something. If they change name, they're not the same thing anymore because everything is keyed on the typemote. So I think you have to the beginning be to make a decision am I submitting a proprietary type or a proposal for a standardized type. Once you've done a proprietary type, it's it would be really easy to just grab the schema, change the name and go. And we propose standardizing this and submit it again. The rest of the tooling, there will be great similarities like generating documentation, etc.
  • Proprietary Types: Existing types could start out proprietarily and then derive a standard one from it. This would involve a re-submission of a PR to start the workflow process again.
    • So it may be that for proprietary types, we are generating documentation from them only and keeping the schema hosted remotely so that they're not changing ownership essentially. So the record for a proprietary type might be just the location of the schema, and we retrieve it, generate some documentation from it, publicize it as opposed to keeping the master source contribution that needs to go into one of our root repository trees.
  • We might just take the URL to the schema so we keep the actual schema out of our repository and it doesn't go under a contributed license agreement in the same way.
  • But whereas if you put something into the FDC3 repository on a PR, you're contributing it and then it becomes owned by the standard once it's adopted.
  • End Goal: Long term goal for type submission would be some sort of form. A form where you paste in a JSON schema. It does some form of validation on the form as part of the tooling and then accepts it and creates the issue and PR.
  • Governance Consideration: A proprietary type should probably have an owner or at least a firm, individual email address or domain of ownership (e.g. @symphony) which can be referenced for maintenance or issues.
  • Versioning: We could be accepting proposals for new versions of schemas, essentially. If it's, revising an existing schema, then essentially it's a PR over the top, as opposed to a PR to add a new file.
    • The same process for an edition or an edit. but the governance would be to look at what the changes are.
      • For example adding optional fields is not breaking changes.
      • Adding required fields or removing required fields is breaking removing even option fields might be considered breaking, when you can use deprecation instead.
      • We will need reviews to decide on them. But we should be able to come up with something that is either add it or replace it. Standard ones we're going to calculate from the type name.
  • Next Steps: Raise an issue to replace the existing context pages.
  • Break off a specific issue for that with either a script to generate static markdown documentation because that's easy to script. Some of them have even can even generate the Docusaurus front matter, programmatically modify the sidebars file to make sure that they're linked and they're in the website or the viewer.
• JSON Schema documentation rendering notes from @kriswest
  • JSON Schema -> Markdown or HTML conversion:
    • https://tomcollins.github.io/json-schema-static-docs/
      • Node module
      • Generates static markdown docs
      • Example:
        • HTML: https://tomcollins.github.io/json-schema-static-docs/examples/person.html
        • Generated markdown source: https://raw.githubusercontent.com/tomcollins/json-schema-static-docs/master/gh-pages/examples/person.md
    • https://pypi.org/project/json-schema-for-humans/
      • Python module
      • Docs: https://coveooss.github.io/json-schema-for-humans/#/
      • Only supports up to JSON Schema Draft-07
      • Can generate JS/HTML or Markdown, number of template options
      • Examples: https://coveooss.github.io/json-schema-for-humans/#/Examples
    • https://github.com/CesiumGS/wetzel
      • https://github.com/CesiumGS/wetzel#example
      • Node module
      • Generates static markdown docs
      • Example: https://github.com/CesiumGS/wetzel#example
    • https://github.com/interagent/prmd
      • Ruby
      • Generates static markdown docs
    • https://github.com/BrianWendt/json-schema-md-doc
      • Node module
      • Generates static markdown docs
      • Example:
        • Live: https://brianwendt.github.io/json-schema-md-doc
    • https://github.com/adobe/jsonschema2md
    • https://www.npmjs.com/package/json-schema-to-markdown
    • https://npmjs.com/package/json-schema-to-markdown-table
  • JSON Schema viewers (have to be embedded on a static page)
    • https://github.com/lbovet/docson
      • Example: http://lbovet.github.io/docson/index.html#/docson/examples/example.json
    • https://github.com/yanick/jsonschematic/
      • Example: https://yanick.github.io/jsonschematic/
  • Docusaurus plugins
    • https://jy95.github.io/docusaurus-json-schema-plugin/
      • Only supports up to JSON Schema Draft-07
      • Viewer AND editor
      • Example:
        • https://jy95.github.io/docusaurus-json-schema-plugin/boxFileSchema
        • https://jy95.github.io/docusaurus-json-schema-plugin/docs/demo/viewer

Action Items

• @mistryvinay Raise an issue to replace the existing context pages

Untracked attendees

Full name	Affiliation	GitHub username

[nemery-flextrade]

Afraid I won't be able to make this one folks, feel free to reach out if needed however.

[mistryvinay]

Vinay Mistry / Symphony 🎵

[Julia-Ritter]

Julia / FINOS

[Yannick-Malins]

Yannick Malins / Symphony 🦄 🌈 ✨

[kriswest]

Kris West / Interop.io 🚀

[robmoffat]

Rob / FINOS 🐚