Use Open API v3 spec as the reference specification for the API

[adrianhopebailie]

As discussed in the CCB call on 19 March:

I propose that we use the Open API Specification v3 version of the API specification as the primary reference for the API Definition.

This will allow us to easily track changes using Git and also more easily assess proposals using GitHub Pull Requests. (Also see #9 which proposes using GitHub for issue tracking).

Where possible I propose we also do away with documents that could be replaced with existing standards as these add an unnecessary maintenance burden on the project.

Proposed changes to existing documents:

• Logical Data Model & JSON Binding Rules

These documents could be replaced with a comprehensive JSON Schema definition for all types. If this is done with care these schemas can be referenced directly from the Open API v3 specification which would no longer need all of the schemas to be redefined.

This also allows developers to use the data models in isolation.

While I recognise the desire to have a binding-free data model definition we should be pragmatic about the cost of maintaining this AND bindings definitions.

If we REALLY want to we could define the data models using ASN.1 and generate JSON Schema from this but that seems like unnecessary overhead.

• API Definition

Migrate to be an Open API v3 schema. This would be a lightweight document, especially if it references all data schemas from the stand-alone data model definitions.

Tags and annotations can be used to provide much of the necessary additional context in auto-generated documentation that would be produced from the YAML format spec.

A good CI process would auto-publish a rich human readable version of the spec whenever changes are published to the YAML file.

• Generic Transaction Patterns
• Use Cases
• Scheme Rules
• Data Integrity, Confidentiality, and Non-Repudiation
• PKI Best Practices
• Signature
• Encryption

Ideally these documents could be migrated to Markdown so that the source text is easy to edit and collaborate on without external tools.

Admittedly tables are a challenge in markdown but they are not impossible and this makes the barrier to entry for contributions lower.

Images

The specifications contain a rich set of extremely valuable diagrams. Migrating these to a form that supports collaboration is tracked in this issue #10.

Let's keep this issue focused purely on the documents themselves.