A work-in-progress proposal for schema features in the Hypermedia protocol

Problem - the WHY

Onyx is highly pragmatic- we are not introducing formality for the sake of it.

We aim to solve the following problems:

People need to Understand Hypermedia Protocol

The Hypermedia Protocol Must be Extensible

Programatic Access to Data and RPCs

Protocol Robustness

Solution

Before we implement schemas, we must decide how to balance Open World Assumption and Closed World Assumption. Also, we must support existing data in the HM network which does not yet have a schema. The other goal is to keep the barrier low for new implementers of software on the network.

So, schemas are optional. HM is "Open World" by default. We include fallback schemas for existing types in HM25. A schema provides utility but is not meant to break software. At the most extreme, software will warn users when content does not conform to the stated schema.

What are the hard requirements for data in the HM ecosystem? All HM content must:

Be parsable. We are using DAG-CBOR encoded IPFS blobs. If this parsing fails, the data is considered garbage. Otherwise, we can present it to the user in some capacity.

Have correct signature, trust, capabilities - All software in the HM ecosystem must build upon our trust primitives to ensure that data is owned and controlled by the correct keys. This is a prerequisite of Onyx Hypermedia

Note: it is important for users to see what data exists inside the content they are referencing and signing. If the software encounters unknown fields in the data, they must be presented to the user in the best way possible. This will prevent users from accidentally referencing and signing "invisible" content which may be undesirable or weighty. Unexpected data that shows up in any blob (Profiles, Changes, Refs, Doc Change Blocks) must be surfaced to the user.

Schema Definitions

Still undecided. See below "Schema Decision-Making"

Fallback Schemas

To handle existing content, we will resolve to our own published schemas depending on the "type" field that is defined.

New content signed by respectful software will include the appropriate schema metadata.

Schema Decision-Making

A work in progress

Inspirations and References

Assorted technology we considered, much that helped inspire/influence this proposal

RDF

RDFS

OWL

SHACL + DASH

SKOS

XRPC + Lexicons

graphQL

IPLD schemas

XSL (XML Schemas)

FHIR