Describe How Common Accord Can Use Distributed Authoritative Sources

[dazzaji]

Below is slight update something law.MIT.edu proposed as the basis of a collaboration (potentially grant funded) testing refinement of CommonAccord to make it usable for use by communities with distributed sources of authoritative content. The ideal implementation would enable a de-coupling of the application/processing from the server where the content resides. At the time this plan was created, the setup required a full version of the CommonAccord application in order to house the authoritative version of content. The idea is to enable groups like law firms, companies, experts, etc to house "just the content" of clauses in their own GitHub repositories and to structure a simple method for communities of interest to use a list of URL's to indicate which clauses from which sources they will incorporate into their final formal legal document.

---

a) A simple, reusable and scalable implementation whereby external entities can locally instal/configure/operate an instance of CommonAccord integrated with their own workflow and approval chains; and

b) How those external entities can choose to integrate with one or more standard "distributed content banks" to access reusable agreement clauses and reusable agreement templates. The places we'd like to stage the clauses and templates reside in a mix of GitHub repositories and flat file directories hosted on regular webservers. As an example, describe how you'd reflect the following scenario:

• Content Banks hosted or forked and mirrored at GitHub repositories belonging to multiple sometimes non-cooperating/adverse organizations;
• ContentBank1 hosted at uniformlaws.org/bank1 and mirrored at MIT.edu/Law/bank1
• ContentBank2 hosted at Law.MIT.edu/bank2 and mirrored at (eg) abajournal.com/Bank2
• ContentBank3 hosted at (eg) Boston.Gov/bank3 and mirrored at (eg) Mass.Gov/MassIT/Legal/bank3
• ContentBank4 hosted at UMKC.edu/Law/bank4 and mirrored at Law.Media.MIT.edu/bank4
• ContentBank5 hosted at (eg) http://ag.ny.gov/bank5 and mirrored at CommonAccord.com/bank5

I am confident you can demo CommonAccord as the go-to destination of content and templates. For purposes of what we want to show in this project, can describe how you'd set up CommonAccord to leverage the power and freedom of more distributed sources of content and templates wherein people may select their own sources of content and templates while always maintaining (by design) the capability to select a common, widely used agreed source.

c) A short few sentences (not more than a couple paragraphs) on the who/what/when/where/how would also be important to fill out a full proposal enough that it could form the basis of an agreement. To that end, can you please include a few words on how you'd approach development/testing/delivery of the project and who would do what by when (or over what period of time)?

[HazardJ]

This is a wonderful suggestion. To restate the basics:

A truly peer-to-peer approach to legal relationships allows integration into a contract or other legal document of materials posted at any URL by any of the participants or any third person. Typical materials would be (i) boilerplate and forms maintained by a law firm, trade group or agency, (ii) product descriptions, (iii) party information, (iv) deal points and negotiation history.

In an ideal environment, these materials could be at any URL on generic websites maintained by the participant or kept at a shared site such as GitHub.

Currently, the implementation of CommonAccord involves a local parser and local materials. In other words, it is not distributed. There is a limited facility to reference any number of single URLs (pages), but links in such a URL (PageX1) to other URLs within those pages (PagesX2-N) will be evaluated locally, rather than in the context of PageX1. Accordingly, links on external pages are not correctly evaluated.

Correctly handling such referenced materials from a local rendering engine would make CommonAccord a truly decentralized system for collaboration. It would reduce the barrier to participation, make authoring extremely open, allow integration of public materials with fully private materials. It would have many of the attributes of the "semantic web".

An ideal implementation would be a modular parser in a widely used language that could be integrated into numerous environments. These environments would include as a browser plugin, as part of a P2P transacting system, as part of enterprise management systems and into Word and other word processing programs. The goal would be to have a single implementation of the parser that could be used across these different environments to assure consistency and to allow the community to add features community-wide. However, the data model paradigm of CommonAccord is simple and rigorous, so it is fully possible that there will be multiple parallel implementations and that they will have a high degree of interoperability.

It is also possible to build on additional features in a modular way. For instance, currently CommonAccord works with key=value pairs based on NewLines and the equal sign. Modules could permit expression in JSON or XML, for instance.

In connection with writing this parser there are a number of additional views that could be implemented. We refer to the X-view - which permits a wysiwyg or Xanadu-like presentation of the document, an unfound fields view, a view of all fields actually used in the document, etc. The hooks for creating these views should be included in the parser to assure consistency.

MORE LATER.

[HazardJ]

Aggregating texts across sites involves the following issues, each of which has a more or less elegant solution. The coming p2p system will provide integrated solutions.

The issues I am aware of include:

• Down time - the site doesn't respond or responds slowly.
• Inconsistency - the site serves up a bad copy of the file or the wrong file.
• Link rot - the site changes the content or ceases to serve it.
• Snooping - the site monitors who accesses what files, learns something about their plans.
• Inconsistent key names, structures and texts. It is always possible to bridge inconsistencies, and even at its worst this is better than the current system of word processing. But it would be helpful to develop best practices
• Inconsistent format: the format of markers for the beginning, divider and end of a key/value, the use of markdown, etc.
• Incompatible copyright assertions.

[dazzaji]

There are many ways to address each of these issues - some more or less elegant in general but some are definitely keyed to the underlying context. Is there a link to more info on the coming p2p system? Not sure what you are referring to. I would hope the assumptions and priorities reflected by the "integrated solution" are flexible enough to be usable in an adequate range of contexts (ideally they would be mostly agnostic to underlying business and legal arrangements of those who implement the CommonAccord approach rather than prescriptive about the nature and functions of roles and relationships among parties using CommonAccord). If the solutions are not agnostic, then at least I hope they are informed by the sorts of basic business and distributed media asset management frameworks and design patterns we've discussed in the past.

For my own part, I'd like to see a way affiliated projects can "transclude" clauses and work out for themselves whether it is important and if so how they deal with each of the valid issues you have identified. The folks I usually work with professionally have a variety of different ways of addressing each of those points (and others that come up with distributed systems, services and data). For CommonAccord to work well and be eligible for adoption it would need to be well informed by the widely adopted existed practices and approaches for addressing these and other issues and the best approach would frequently be full agnosticism with easy re-usable solution (ie: adaptors, plugins, modules, connectors, etc) to demonstrate how to implement CommonAccord in each key context of use and to illustrate how interoperability can work according to the expectations and requirements present in various key scenarios. The in-house counsel and data sharing agreement scenario is a really important context of use to keep in mind, and the mostly "do-it-yourself" small business or fledgling startup is another one. The consumer apps/services market is another core context (individuals who currently have no way to keep organized the range of agreements like the EULA and Privacy Policy files of all their web based providers) and the related "trusted partner" and "open dynamics apps bus" contexts for organizations that integrate with other organizations based on OAuth 2 and OpenID Connect style client registrations (the "Iron Triangle" and BLT design pattern I showed you and Primavera in Berkman that long late Saturday night).

[HazardJ]

Yes, absolutely. Totally agnostic, decentralized, etc. Full flexibility on all levels. I've been working on the specification for how we transclude across sites.

[HazardJ]

Yes, the core is a parser and it should be as simple as possible. Adaptors can extend it.

[HazardJ]

CommonAccord is neutral with respect to the way people use it.

[HazardJ]

Here is a rough specification for transclusion of exogenous materials. One needs to be able to include materials from any website, and to have the links in those materials work correctly. One also needs to be able to override any part of those materials, to customize or to complete them. The solution, I propose, looks like this:

Transcluding Materials from another Website To smoothly integrate materials on another website, it will be necessary to respect the links in those materials. This means that they need to be understood as relative links, but the client side needs also to be able to override them. This of course is similar to how we handle overrides in local materials.

A consistent way to do this is to reuse the notion of prefixing and of lists, but this time at the level of lists of lists. Concretely:

If one declared the following:

[Seller/]=[[http://acme.com/foo/]]

then a statement like this:

P1.=[Seller/Us.md]

would be evaluated as:

P1.=[http://acme.com/foo/Us.md]

And a statement in acme.com/foo/Us.md like:

Parent.=[Acme_Holding.md]

would be evaluated as:

P1.Parent.=[Seller/Acme_Holding.md]

then as:

P1.Parent.=[http://acme.com/foo/Acme_Holding.md]

This allows a user to attach a distant solution in its entirety, and also to override as desired, in a manner that can be made to feel local and consistent with the way fields work.

Since this is untested, I really invite suggestions from all about this. The goal in this, as in everything we do, is to invent as little as possible and to connect tested ideas.

[HazardJ]

A MVP parser would be:

1. in a language that is widely used
2. as simple to read as possible, even for a relatively unsophisticated programmer
3. modular
4. lazy (per perl version)
5. pluggable into a browser, apps, etc.
6. with the ability to handle links in exogenous materials. Because this part is experimental, it should be modular to the extent that it is different from traversing local links. Ideally, the notion of exogenous vs local would disappear, and the "local" would merely be a non-prefixed, top-level. (This is how lists currently work.)

It would render the following views:

1. Source (or "List") - as the current
2. Document view - exactly as the current except - it would be able to pull the materials from a collection of distant sites, e.g. materials from the raw view at Github. - and it would ignore single carriage returns in a value and treat only a double carriage return as an end of field. (This permits editing of large files in html editors - which often include lots of single carriage returns. Double carriage returns also make the lists easier to read.)
3. X-View - rendered as current but with metadata permitting in-browser expansion, collapse and pop-up editing similar to the XWiki version
4. Opens - a list of the {fields} that remain unmatched after rendering 1 (and 2, which is the same)
5. Search - a list of possible completions (subject to certain limitations)
6. Diff - variety of views that compare the document at various stages of override. (TBD)

[dazzaji]

Why not use web components? Could some or all of CommonAccord be expressed via web components? Here are some links:

• https://elements.polymer-project.org
• www.w3.org/TR/components-intro/
• https://github.com/webcomponents
• webcomponents.org

That would make the design pattern much more adoptable and would mean two conforming implementations exist starting with Primavera's. I'd recommend settling on polymer, bower and the right packages in Atom as the way people actually implement and customize their use of CommonAccord. I'd be willing to feature a "Let's express CommonAccord as Web Components" in an upcoming legal Hackathon we are starting planning to convene early fall. I'd personally volunteer to help you push forward a focused Hackathon project to get that banged into shape. What do you think?

[HazardJ]

This is a GREAT idea.

An app that used Polymer, browser, Atom, would be great. It could suck up Cmacc-compatible content from wherever, including Cmacc-formatted repos at GitHub.

If they restated the context as JSON (as they likely would) then we have a bit of a fork, but we’d figure out a way to merge. Perhaps that ecosystem would prevail over the plaintext-with-=-and-linefeeds. The point of CommonAccord is to codify legal docs and make them interoperable, so whatever direction anyone builds, we’ll end up coming back together around legal text.

It would be useful that anyone coding actually understood the inheritance model of Cmacc. Of course, even if they did something else, they would either have found something better or something worse, and a merge would again happen.

Some others have suggested a JS extension for the browser and muttered things about Angular that are beyond my ken.

Will also plop this in the Slack room.

On Jul 5, 2015, at 2:00 PM, Dazza Greenwood notifications@github.com wrote:

Why not use web components? Could some or all of CommonAccord be expressed via web components? That would make the design pattern much more adoptable and would mean two conforming implementations exist starting with Primavera's. I'd recommend settling on polymer, bower and the right packages in Atom as the way people actually implement and customize their use of CommonAccord. I'd be willing to convene and push forward a focused Hackathon to get that banged into shape. What do you think?

— Reply to this email directly or view it on GitHub https://github.com/CommonAccord/Site-DataShare/issues/1#issuecomment-118615987.

[dazzaji]

Glad you like the idea. Regarding JSON: it isn't necessarily the optimal lowest level structure but there needs to be some common way to indicate the what is what on the content and processing and display fronts and those are the sorts of things JSON and XML provide for. The template format we settled on for the NDoCH included a place for the CMAC plain text -=- stuff and also unique identifiers tied to the authoritative source URL (which in turn provides a way to associate JSON version and other goodies).

So... I think I can infer a yes from your comment but to be prudent before expending effort I'm just going to ask: 1) Do you support an effort to express CommonAccord via web components? If so, then: 2) Would you help and/or lead a team prepping for and working on this at a legal hackathon?

This should help flesh out the place of JavaScript and Angular Vis-a-Vis CommonAccord (and basically the rest of the modern web) in one fell swoop.

[HazardJ]

I’m very eager to pursue this. I think we might have different ideas about where the handoff is between “cards” and Cmacc text. But we can work that out. I’m handling a couple of other threads right now - and am famished - but maybe we could talk in a bit?

Yes! on the rest of the modern web. I also saw the extraordinary work that Sandy’s team announced last week using the Bitcoin blockchain. Legal codification could add to the value proposition of a truly P2P platform.

On Jul 5, 2015, at 3:07 PM, Dazza Greenwood notifications@github.com wrote:

Glad you like the idea. Regarding JSON: it isn't necessarily the optimal lowest level structure but there needs to be some common way to indicate the what is what on the content and processing and display fronts and those are the sorts of things JSON and XML provide for. The template format we settled on for the NDoCH included a place for the CMAC plain text -=- stuff and also unique identifiers tied to the authoritative source URL (which in turn provides a way to associate JSON version and other goodies).

So... I think I can infer a yes from your comment but to be prudent before expending effort I'm just going to ask: 1) Do you support an effort to express CommonAccord via web components? If so, then: 2) Would you help and/or lead a team prepping for and working on this at a legal hackathon?

This should help flesh out the place of JavaScript and Angular Vis-a-Vis CommonAccord (and basically the rest of the modern web) in one fell swoop.

— Reply to this email directly or view it on GitHub https://github.com/CommonAccord/Site-DataShare/issues/1#issuecomment-118619099.